=== PAGE: https://www.union.ai/docs/v2/union ===

# Documentation

Welcome to the documentation.

## Subpages

- **Union.ai**
- **Tutorials**
- **Integrations**
- **Reference**
- **Community**
- **Release notes**
- **Platform deployment**
- **Security**


=== PAGE: https://www.union.ai/docs/v2/union/user-guide ===

# Union.ai

Union.ai empowers AI development teams to rapidly ship high-quality code to production by offering optimized performance, unparalleled resource efficiency, and a delightful workflow authoring experience. With Union.ai your team can:

* Run complex AI workloads with performance, scale, and efficiency.
* Achieve millisecond-level execution times with reusable containers.
* Scale out to multiple regions, clusters, and clouds as needed for resource availability, scale, or compliance.

Union.ai is built on top of the leading open-source workflow orchestrator, [Flyte](/docs/v2/flyte/).

Union.ai provides all the features of Flyte, plus much more, in an environment where you keep your data and workflow code on your own infrastructure. Union.ai is available as [BYOC](/docs/v2/union//deployment/byoc/_index) (Bring Your Own Cloud), where Union.ai manages the infrastructure for you, or [Self-managed](/docs/v2/union//deployment/selfmanaged/_index), where you manage the data plane yourself.

> [!NOTE]
> These are the Union.ai **2.0** docs.
> To switch to [version 1.0](/docs/v1/union/) or to another product variant, use the selectors above.

> **📝 Note**
>
> Want to try Flyte without installing anything? [Try Flyte 2 in your browser](https://flyte2intro.apps.demo.hosted.unionai.cloud/).

### **From Flyte 1 to 2**

Flyte 2 represents a fundamental shift in how AI workflows are written and executed. Learn
more in this section.

### **Quickstart**

Install Flyte 2, configure your local IDE, create and run your first task, and inspect the results in 2 minutes.

## Subpages
- **Overview**
- **Quickstart**
- **Core concepts**
- **Running locally**
- **Connecting to a cluster**
- **Projects and domains**
- **Basic project: RAG**
- **Advanced project: LLM reporting agent**
- **From Flyte 1 to 2**
- **Configure tasks**
- **Build tasks**
- **Run and deploy tasks**
- **Scale your runs**
- **Configure apps**
- **Build apps**
- **Serve and deploy apps**
- **Build an agent**
- **Sandboxing**
- **Authenticating with Union**
- **User management**


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/overview ===

# Overview

In this guide we cover how to build AI applications, data pipelines, and ML workflows using the Flyte 2 SDK.

Programs written using the Flyte 2 SDK can run on either a Union.ai or Flyte OSS back-end. This guide applies to both.

## Pure Python, no DSL

Flyte lets you write workflows in standard Python—no domain-specific language, no special syntax, no restrictions.

Your "workflow" is simply a task that calls other tasks:

```python
@env.task()
async def my_workflow(data: list[str]) -> list[str]:
    results = []
    for item in data:
        if should_process(item):
            result = await process_item(item)
            results.append(result)
    return results
```

You can use everything Python offers:

- **Loops and conditionals** — standard `for`, `while`, `if-elif-else`
- **Error handling** — `try/except` blocks work as expected
- **Async/await** — native Python concurrency model
- **Any library** — import and use whatever you need

This means no learning curve beyond Python itself, and no fighting a DSL when your requirements don't fit its constraints.

## Durability

Every task execution in Flyte is automatically persisted. Inputs, outputs, and intermediate results are stored in an object store, giving you:

- **Full observability** — see exactly what data flowed through each step
- **Audit trail** — track what ran, when, and with what parameters
- **Data lineage** — trace outputs back to their inputs

This persistence happens automatically. You don't need to add logging or manually save state—Flyte handles it.

## Reproducibility

Flyte ensures that runs can be reproduced exactly:

- **Deterministic execution** — same inputs produce same outputs
- **Caching** — task results are cached and reused when inputs match
- **Versioned containers** — code runs in the same environment every time

Caching is configurable per task:

```python
@env.task(cache="auto")
async def expensive_computation(data: str) -> str:
    # This result will be cached and reused for identical inputs
    ...
```

When you rerun a workflow, Flyte serves cached results for unchanged tasks rather than recomputing them.

## Recoverability

When something fails, Flyte doesn't make you start over. Failed workflows can resume from where they left off:

- **Completed tasks are preserved** — successful outputs remain cached
- **Retry from failure point** — no need to re-execute what already succeeded
- **Fine-grained checkpoints** — the `@flyte.trace` decorator creates checkpoints within tasks

This reduces wasted compute and speeds up debugging. When a task fails after hours of prior computation, you fix the issue and continue—not restart.

## Built for scale

Flyte handles the hard parts of distributed execution:

- **Parallel execution** — express parallelism with `asyncio.gather()`, Flyte handles the rest
- **Dynamic workflows** — construct workflows based on runtime data, not just static definitions
- **Fast scheduling** — reusable containers achieve millisecond-level task startup
- **Resource management** — specify CPU, memory, and GPU requirements per task

## What this means in practice

Consider a data pipeline that processes thousands of files, trains a model, and deploys it:

- If file processing fails on item 847, you fix the issue and resume from item 847
- If training succeeds, but deployment fails, you redeploy without retraining
- If you rerun next week with the same data, cached results skip redundant computation
- If you need to audit what happened, every step is recorded

Flyte gives you the flexibility of Python scripts with the reliability of a production system.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/quickstart ===

# Quickstart

Let's get you up and running with your first workflow on your local machine.

> **📝 Note**
>
> Want to try Flyte without installing anything? [Try Flyte 2 in your browser](https://flyte2intro.apps.demo.hosted.unionai.cloud/).

## What you'll need

- Python 3.10+ in a virtual environment

## Install the SDK

Install the `flyte` package:

```bash
pip install 'flyte[tui]'
```
> **📝 Note**
>
> We also install the `tui` extra to enable the terminal user interface.

Verify it worked:

```bash
flyte --version
```

Output:

```bash
Flyte SDK version: 2.*.*
```

## Configure

Create a config file for local execution. Runs will be persisted locally in a SQLite database.

```bash
flyte create config --local-persistence
```

This creates `.flyte/config.yaml` in your current directory. See [Setting up a configuration file](./connecting-to-a-cluster#configuration-file) for more options.

> **📝 Note**
>
> Run `flyte get config` to check which configuration is currently active.

## Write your first workflow

Create `hello.py`:

```python
# hello.py

import flyte

# The `hello_env` TaskEnvironment is assigned to the variable `env`.
# It is then used in the `@env.task` decorator to define tasks.
# The environment groups configuration for all tasks defined within it.
env = flyte.TaskEnvironment(name="hello_env")

# We use the `@env.task` decorator to define a task called `fn`.
@env.task
def fn(x: int) -> int: # Type annotations are required
    slope, intercept = 2, 5
    return slope * x + intercept

# We also use the `@env.task` decorator to define another task called `main`.
# This is the is the entrypoint task of the workflow.
# It calls the `fn` task defined above multiple times using `flyte.map`.
@env.task
def main(x_list: list[int] = list(range(10))) -> float:
    y_list = list(flyte.map(fn, x_list)) # flyte.map is like Python map, but runs in parallel.
    y_mean = sum(y_list) / len(y_list)
    return y_mean
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/getting-started/hello.py*

Here's what's happening:

- **`TaskEnvironment`** specifies configuration for your tasks (container image, resources, etc.)
- **`@env.task`** turns Python functions into tasks that run remotely
- Both tasks share the same `env`, so they'll have identical configurations

## Run it

Create a project directory and place your files there:

CODE4

> [!WARNING]
> Do not run `flyte run` from your home directory. Flyte packages the current directory when running remotely, so running from `$HOME` would attempt to bundle your entire home folder. Always work from a dedicated project directory.

Run the workflow:

CODE5

This executes the workflow locally on your machine.

## See the results

You can see the run in the TUI by running:

CODE6

The TUI will open into the explorer view

![Explorer View](../_static/images/user-guide/quickstart/explorer-tui.png)

To navigate to the run details, double-click it or press `Enter` to view the run details.

![Run Details View](../_static/images/user-guide/quickstart/run-tui.png)

## Next steps

Now that you've run your first workflow:

- [**Core concepts**](./core-concepts/_index): Understand the core concepts of Flyte programming
- [**Running locally**](./running-locally): Learn about the TUI, caching, and other features that work locally
- [**Connecting to a cluster**](./connecting-to-a-cluster): Configure your environment for remote execution


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/core-concepts ===

# Core concepts

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

Now that you've completed the **Quickstart**, let's explore Flyte's core concepts through working examples.

By the end of this section, you'll understand:

- **TaskEnvironment**: The container configuration that defines where and how your code runs
- **Tasks**: Python functions that execute remotely in containers
- **Runs and Actions**: How Flyte tracks and manages your executions
- **Apps**: Long-running services for APIs, dashboards, and inference endpoints

Each concept is introduced with a practical example you can run yourself.

## How Flyte works

When you run code with Flyte, here's what happens:

1. You define a **TaskEnvironment** that specifies the container image and resources
2. You decorate Python functions with `@env.task` to create **tasks**
3. When you execute a task, Flyte creates a **run** that tracks the execution
4. Each task execution within a run is an **action**

Let's explore each of these in detail.

## Subpages
- **Core concepts > TaskEnvironment**
- **Core concepts > Tasks**
- **Core concepts > Runs and actions**
- **Core concepts > Apps**
- **Core concepts > Key capabilities**


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/core-concepts/task-environment ===

# TaskEnvironment

A `TaskEnvironment` defines the hardware and software environment where your tasks run. Think of it as the container configuration for your code.

## A minimal example

Here's the simplest possible TaskEnvironment:

```python
import flyte

env = flyte.TaskEnvironment(name="my_env")

@env.task
def hello() -> str:
    return "Hello from Flyte!"
```

With just a `name`, you get Flyte's default container image and resource allocation. This is enough for simple tasks that only need Python and the Flyte SDK.

## What TaskEnvironment controls

A TaskEnvironment specifies two things:

**Hardware environment** - The compute resources allocated to each task:
- CPU cores
- Memory
- GPU type and count

**Software environment** - The container image your code runs in:
- Base image (Python version, OS)
- Installed packages and dependencies
- Environment variables

## Configuring resources

Use the `limits` parameter to specify compute resources:

```python
env = flyte.TaskEnvironment(
    name="compute_heavy",
    limits=flyte.Resources(cpu="4", mem="16Gi"),
)
```

For GPU workloads:

```python
env = flyte.TaskEnvironment(
    name="gpu_training",
    limits=flyte.Resources(cpu="8", mem="32Gi", gpu="1"),
    accelerator=flyte.GPUAccelerator.NVIDIA_A10G,
)
```

## Configuring container images

For tasks that need additional Python packages, specify a custom image:

```python
image = flyte.Image.from_debian_base().with_pip_packages("pandas", "scikit-learn")

env = flyte.TaskEnvironment(
    name="ml_env",
    image=image,
)
```

See [Container images](../task-configuration/container-images) for detailed image configuration options.

## Multiple tasks, one environment

All tasks decorated with the same `@env.task` share that environment's configuration:

```python
env = flyte.TaskEnvironment(
    name="data_processing",
    limits=flyte.Resources(cpu="2", mem="8Gi"),
)

@env.task
def load_data(path: str) -> dict:
    # Runs with 2 CPU, 8Gi memory
    ...

@env.task
def transform_data(data: dict) -> dict:
    # Also runs with 2 CPU, 8Gi memory
    ...
```

This is useful when multiple tasks have similar requirements.

## Multiple environments

When tasks have different requirements, create separate environments:

```python
light_env = flyte.TaskEnvironment(
    name="light",
    limits=flyte.Resources(cpu="1", mem="2Gi"),
)

heavy_env = flyte.TaskEnvironment(
    name="heavy",
    limits=flyte.Resources(cpu="8", mem="32Gi"),
)

@light_env.task
def preprocess(data: str) -> str:
    # Light processing
    ...

@heavy_env.task
def train_model(data: str) -> dict:
    # Resource-intensive training
    ...
```

## Next steps

Now that you understand TaskEnvironments, let's look at how to define [tasks](./tasks) that run inside them.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/core-concepts/tasks ===

# Tasks

A task is a Python function that runs remotely in a container. You create tasks by decorating functions with `@env.task`.

## Defining a task

Here's a simple task:

```python
import flyte

env = flyte.TaskEnvironment(name="my_env")

@env.task
def greet(name: str) -> str:
    return f"Hello, {name}!"
```

The `@env.task` decorator tells Flyte to run this function in a container configured by `env`.

## Type hints are required

Flyte uses type hints to understand your data and serialize it between tasks:

```python
@env.task
def process_numbers(values: list[int]) -> int:
    return sum(values)
```

Supported types include:
- Primitives: `int`, `float`, `str`, `bool`
- Collections: `list`, `dict`, `tuple`
- DataFrames: `pandas.DataFrame`, `polars.DataFrame`
- Files: `flyte.File`, `flyte.Directory`
- Custom: dataclasses, Pydantic models

See [Data classes and structures](../task-programming/dataclasses-and-structures) for complex types.

## Tasks calling tasks

In Flyte 2, tasks can call other tasks directly. The called task runs in its own container:

```python
@env.task
def fetch_data(url: str) -> dict:
    # Runs in container 1
    ...

@env.task
def process_data(url: str) -> str:
    data = fetch_data(url)  # Calls fetch_data, runs in container 2
    return transform(data)
```

This is how you build workflows in Flyte 2. There's no separate `@workflow` decorator - just tasks calling tasks.

## The top-level task

The task you execute directly is the "top-level" or "driver" task. It orchestrates other tasks:

```python
@env.task
def step_one(x: int) -> int:
    return x * 2

@env.task
def step_two(x: int) -> int:
    return x + 10

@env.task
def pipeline(x: int) -> int:
    a = step_one(x)   # Run step_one
    b = step_two(a)   # Run step_two with result
    return b
```

When you run `pipeline`, it becomes the top-level task and orchestrates `step_one` and `step_two`.

## Running tasks locally

For quick testing, you can call a task like a regular function:

```python
# Direct call - runs locally, not in a container
result = greet("World")
print(result)  # "Hello, World!"
```

This bypasses Flyte entirely and is useful for debugging logic. However, local calls don't track data, use remote resources, or benefit from Flyte's features.

## Running tasks remotely

To run a task on your Flyte backend:

```python
import flyte

flyte.init_from_config()
result = flyte.run(greet, name="World")
print(result)  # "Hello, World!"
```

Or from the command line:

```bash
flyte run my_script.py greet --name World
```

This sends your code to the Flyte backend, runs it in a container, and returns the result.

## Next steps

Now that you can define and run tasks, let's understand how Flyte tracks executions with [runs and actions](./runs-and-actions).


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/core-concepts/runs-and-actions ===

# Runs and actions

When you execute a task on Flyte, the system creates a **run** to track it. Each individual task execution within that run is an **action**. Understanding this hierarchy helps you navigate the UI and debug your workflows.

## What is a run?

A **run** is the execution of a task that you directly initiate, plus all its descendant task executions, considered as a single unit.

When you execute:

```bash
flyte run my_script.py pipeline --x 5
```

Flyte creates a run for `pipeline`. If `pipeline` calls other tasks, those executions are part of the same run.

## What is an action?

An **action** is the execution of a single task, considered independently. A run consists of one or more actions.

Consider this workflow:

```python
@env.task
def step_one(x: int) -> int:
    return x * 2

@env.task
def step_two(x: int) -> int:
    return x + 10

@env.task
def pipeline(x: int) -> int:
    a = step_one(x)
    b = step_two(a)
    return b
```

When you run `pipeline(5)`:

- **1 run** is created for the entire execution
- **3 actions** are created: one for `pipeline`, one for `step_one`, one for `step_two`

## Runs vs actions in practice

| Concept | What it represents | In the UI |
|---------|-------------------|-----------|
| **Run** | Complete execution initiated by user | Runs list, top-level view |
| **Action** | Single task execution | Individual task details, logs |

For details on how to run tasks locally and remotely, see [Tasks](./tasks#running-tasks-locally).

## Viewing runs in the UI

After running a task remotely, click the URL in the output to see your run in the UI:

```bash
flyte run my_script.py pipeline --x 5
```

Output:

```bash
abc123xyz
https://my-instance.example.com/v2/runs/project/my-project/domain/development/abc123xyz
Run 'a0' completed successfully.
```

In the UI, you can:

- See the overall run status and duration
- Navigate to individual actions
- View inputs and outputs for each task
- Access logs for debugging
- See the execution graph

## Understanding the execution graph

The UI shows how tasks relate to each other:

```
pipeline (action)
├── step_one (action)
└── step_two (action)
```

Each box is an action. Arrows show data flow between tasks. This visualization helps you understand complex workflows and identify bottlenecks.

## Checking run status

From the command line:

```bash
flyte get run <run-id>
```

From Python:

```python
import flyte

flyte.init_from_config()
run = flyte.run(pipeline, x=5)

# The run object has status information
print(run.status)
```

## Next steps

You now understand tasks and how Flyte tracks their execution. Next, let's learn about [apps](./introducing-apps) - Flyte's approach to long-running services.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/core-concepts/introducing-apps ===

# Apps

Now that you understand tasks, let's learn about apps - Flyte's way of running long-lived services.

## Tasks vs apps

You've already learned about **tasks**: Python functions that run to completion in containers. Tasks are great for data processing, training, and batch operations.

**Apps** are different. An app is a long-running service that stays active and handles requests over time. Apps are ideal for:

- REST APIs and webhooks
- Model inference endpoints
- Interactive dashboards
- Real-time data services

| Aspect | Task | App |
|--------|------|-----|
| Lifecycle | Runs once, then exits | Stays running indefinitely |
| Invocation | Called with inputs, returns outputs | Receives HTTP requests |
| Use case | Batch processing, training | APIs, inference, dashboards |
| Durability | Inputs/outputs stored, can resume | Stateless request handling |

## AppEnvironment

Just as tasks use `TaskEnvironment`, apps use `AppEnvironment` to configure their runtime.

An `AppEnvironment` specifies:

- **Hardware**: CPU, memory, GPU allocation
- **Software**: Container image with dependencies
- **App-specific settings**: Ports, scaling, authentication

Here's a simple example:

```python
import flyte
from flyte.app.extras import FastAPIAppEnvironment

env = FastAPIAppEnvironment(
    name="my-app",
    image=flyte.Image.from_debian_base().with_pip_packages("fastapi", "uvicorn"),
    limits=flyte.Resources(cpu="1", mem="2Gi"),
)
```

## A hello world app

Let's create a minimal FastAPI app to see how this works.

First, create `hello_app.py`:

```python
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
#    "uvicorn",
# ]
# ///

"""A simple "Hello World" FastAPI app example for serving."""

from fastapi import FastAPI
import pathlib
import flyte
from flyte.app.extras import FastAPIAppEnvironment

# Define a simple FastAPI application
app = FastAPI(
    title="Hello World API",
    description="A simple FastAPI application",
    version="1.0.0",
)

# Create an AppEnvironment for the FastAPI app
env = FastAPIAppEnvironment(
    name="hello-app",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
    ),
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
)

# Define API endpoints
@app.get("/")
async def root():
    return {"message": "Hello, World!"}

@app.get("/health")
async def health_check():
    return {"status": "healthy"}

# Serving this script will deploy and serve the app on your Union/Flyte instance.
if __name__ == "__main__":
    # Initialize Flyte from a config file.
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)

    # Serve the app remotely.
    app_instance = flyte.serve(env)

    # Print the app URL.
    print(app_instance.url)
    print("App 'hello-app' is now serving.")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/getting-started/serving/hello_app.py*

### Understanding the code

- **`FastAPI()`** creates the web application with its endpoints
- **`FastAPIAppEnvironment`** configures the container and resources
- **`@app.get("/")`** defines an HTTP endpoint that returns a greeting
- **`flyte.serve()`** deploys and starts the app on your Flyte backend

### Serving the app

With your config file in place, serve the app:

```bash
flyte serve hello_app.py env
```

Or run the Python file directly (which calls `flyte.serve()` in the main block):

```bash
python hello_app.py
```

You'll see output like:

```output
https://my-instance.flyte.com/v2/domain/development/project/my-project/apps/hello-app
App 'hello-app' is now serving.
```

Click the link to view your app in the UI. You can find the app URL there, or visit `/docs` for FastAPI's interactive API documentation.

## When to use apps vs tasks

Use **tasks** when:
- Processing takes seconds to hours
- You need durability (inputs/outputs tracked)
- Work is triggered by events or schedules
- Results need to be cached or resumed

Use **apps** when:
- Responses must be fast (milliseconds)
- You're serving an API or dashboard
- Users interact in real-time
- You need a persistent endpoint

## Common patterns

**Model serving with FastAPI**: Train a model with a Flyte pipeline, then serve predictions from it. During local development, the app loads the model from a local file. When deployed remotely, Flyte's `Parameter` system automatically resolves the model from the latest training run output. See [FastAPI app](../build-apps/fastapi-app) for the full example.

**Agent UI with Gradio**: Build an interactive UI that kicks off agent runs using `flyte.with_runcontext()`. A single `RUN_MODE` environment variable controls the deployment progression: fully local (rapid iteration), local UI with remote task execution (cluster compute), or fully remote (production). See [Build apps](../build-apps/_index) for details.

## Next steps

You now understand the core building blocks of Flyte:

- **TaskEnvironment** and **AppEnvironment** configure where code runs
- **Tasks** are functions that execute and complete
- **Apps** are long-running services
- **Runs** and **Actions** track executions

Before diving deeper, check out [Key capabilities](./key-capabilities) for an overview of what Flyte can do—from parallelism and caching to LLM serving and error recovery.

Then head to [Basic project](../basic-project) to build an end-to-end ML system with training tasks and a serving app.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/core-concepts/key-capabilities ===

# Key capabilities

Now that you understand the core concepts -- `TaskEnvironment`, tasks, runs, and apps -- here's an overview of what Flyte can do. Each capability is covered in detail later in the documentation.

## Environment and resources

Configure how and where your code runs.

- **Multiple environments**: Create separate configurations for different use cases (dev, prod, GPU vs CPU)
  → [Multiple environments](../task-configuration/multiple-environments)

- **Resource specification**: Request specific CPU, memory, GPU, and storage for your tasks
  → [Resources](../task-configuration/resources)

- **Reusable containers**: Eliminate container startup overhead with pooled, warm containers for millisecond-level task scheduling
  → [Reusable containers](../task-configuration/reusable-containers)

## Deployment

Get your code running remotely.

- **Cloud image building**: Build container images remotely without needing local Docker
  → [Container images](../task-configuration/container-images)

- **Code packaging**: Your local code is automatically bundled and deployed to remote execution
  → [Packaging](../task-deployment/packaging)

- **Local testing**: Test tasks locally before deploying with `flyte run --local`
  → [How task run works](../task-deployment/how-task-run-works)

## Data handling

Pass data efficiently between tasks.

- **Files and directories**: Pass large files and directories between tasks using `flyte.io.File` and `flyte.io.Dir`
  → [Files and directories](../task-programming/files-and-directories)

- **DataFrames**: Work with pandas, Polars, and other DataFrame types natively
  → [DataFrames](../task-programming/dataframes)

## Parallelism and composition

Scale out and compose workflows.

- **Fanout parallelism**: Process items in parallel using `flyte.map` or `asyncio.gather`
  → [Fanout](../task-programming/fanout)

- **Remote tasks**: Call previously deployed tasks from within your workflows
  → [Remote tasks](../task-programming/remote-tasks)

## Security and automation

Manage credentials and automate execution.

- **Secrets**: Inject API keys, passwords, and other credentials securely into tasks
  → [Secrets](../task-configuration/secrets)

- **Triggers**: Schedule tasks on a cron schedule or trigger them from external events
  → [Triggers](../task-configuration/triggers)

- **Webhooks**: Build APIs that trigger task execution from external systems
  → [App usage patterns](../build-apps/app-usage-patterns)

## Durability and reliability

Handle failures and avoid redundant work.

- **Error handling**: Catch failures and retry with different resources (e.g., more memory)
  → [Error handling](../task-programming/error-handling)

- **Retries and timeouts**: Configure automatic retries and execution time limits
  → [Retries and timeouts](../task-configuration/retries-and-timeouts)

- **Caching**: Add `cache="auto"` to any task and Flyte stores its outputs keyed on task name and inputs. Same inputs means instant results with no recomputation. This speeds up your development loop: skip re-downloading data, avoid replaying earlier steps in agentic chains, or bypass any expensive computation while you iterate.
  → [Caching](../task-configuration/caching)

  ```python
  @env.task(cache="auto")
  async def load_data(data_dir: str = "./data") -> str:
      """Downloads once, then returns instantly on subsequent runs."""
      # ... expensive download ...
      return data_dir
  ```

- **Traces**: Use `@flyte.trace` to get visibility into the internal steps of a task without the overhead of making each step a separate task. Traced functions show up as child nodes under their parent task, each with their own timing, inputs, and outputs. This is particularly useful for AI agents where you want to see which tools were called.
  → [Traces](../task-programming/traces)

  ```python
  @flyte.trace
  async def search(query: str) -> str:
      """Shows up as a child node under the parent task."""
      return await do_search(query)

  @env.task
  async def agent(request: str) -> str:
      results = await search(request)    # Traced
      answer = await summarize(results)   # Also traced if decorated
      return answer
  ```

- **Reports**: Add `report=True` to a task and it can generate an HTML report (charts, tables, images) saved alongside the task output. Combined with caching and persisted inputs/outputs, reports act as lightweight experiment tracking—each run produces a self-contained HTML file you can compare across runs and share with your team.
  → [Reports](../task-programming/reports)

  ```python
  import flyte.report

  @env.task(report=True)
  async def evaluate(model_file: File, test_data: str) -> str:
      # ... run evaluation ...
      await flyte.report.replace.aio(
          f"<h2>Training Report</h2>"
          f"<h3>Test Results</h3>"
          f"<p>Accuracy: {accuracy:.4f}</p>"
      )
      await flyte.report.flush.aio()
      return f"Accuracy: {accuracy:.4f}"
  ```

## Apps and serving

Deploy long-running services.

- **FastAPI apps**: Deploy REST APIs and webhooks
  → [FastAPI app](../build-apps/fastapi-app)

- **LLM serving**: Serve large language models with vLLM or SGLang
  → [vLLM app](../build-apps/vllm-app), [SGLang app](../build-apps/sglang-app)

- **Autoscaling**: Scale apps up and down based on traffic, including scale-to-zero
  → [Autoscaling apps](../configure-apps/auto-scaling-apps)

- **Streamlit dashboards**: Deploy interactive data dashboards
  → [Streamlit app](../build-apps/streamlit-app)

## Notebooks

Work interactively.

- **Jupyter support**: Author and run workflows directly from Jupyter notebooks, and fetch workflow metadata (inputs, outputs, logs)
  → [Notebooks](../task-programming/notebooks)

## Next steps

Ready to put it all together? Head to [Basic project](../basic-project) to build an end-to-end ML system with training tasks and a serving app.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/running-locally ===

# Running locally

Flyte runs locally with no cluster or Docker needed. Install the SDK, write tasks, and run them on your machine. When you're ready to scale, drop the `--local` flag and the same code runs on a remote cluster with GPUs.

![TUI agent run](../_static/images/user-guide/local/tui_agent_run.png)

---

## Getting started

If you haven't already, install the SDK and configure local persistence as described in the [Quickstart](./quickstart).

---

## Running tasks locally

The `--local` flag tells Flyte to execute a task in your local Python environment rather than on a remote cluster. Add `--tui` to launch the interactive Terminal UI for real-time monitoring.

Basic local execution:

```bash
flyte run --local my_pipeline.py my_task --arg value
```

With the interactive TUI:

```bash
flyte run --local --tui my_pipeline.py my_task --arg value
```

You can also run tasks programmatically using the Python SDK with `flyte.run()`. See [Run and deploy tasks](./task-deployment/_index) for details.

Drop `--local` to run on a remote cluster when one is configured:

```bash
flyte run my_pipeline.py my_task --arg value
```

---

## Terminal UI

The TUI is an interactive split-screen dashboard. Task tree on the left, details and logs on the right.

```bash
flyte run --local --tui my_pipeline.py pipeline --epochs 5
```

![TUI agent run](../_static/images/user-guide/local/tui_agent_run.png)

What you see:

- **Task tree** with live status: `●` running, `✓` done, `✗` failed
- **Cache indicators**: `$` cache hit, `~` cache enabled but missed
- **Live logs**: `print()` output streams in real time
- **Details panel**: inputs, outputs, timing, report paths
- **Traced sub-tasks**: child nodes for `@flyte.trace` decorated functions

**Keyboard shortcuts:**

| Key | Action |
|-----|--------|
| `q` | Quit |
| `d` | Details tab |
| `l` | Logs tab |

### Exploring past runs

Flyte persists the inputs and outputs of every task run locally, so you can always go back and inspect what a task received and produced. Launch the TUI on its own to browse past runs, compare inputs and outputs, and review reports:

```bash
flyte start tui
```

---

## What works locally

Most Flyte features work in both local and remote execution. The table below summarizes how each feature behaves locally.

| Feature | Local behavior | Details |
|---------|---------------|---------|
| **Caching** | Outputs stored in local SQLite, keyed on task name and inputs. Same inputs = instant results. | [Caching](./task-configuration/caching) |
| **Tracing** | `@flyte.trace` functions appear as child nodes in the TUI with their own timing, inputs, and outputs. | [Traces](./task-programming/traces) |
| **Reports** | HTML files saved locally. TUI shows the file path. | [Reports](./task-programming/reports) |
| **Serving** | Run apps locally with `python serve.py` or `flyte.with_servecontext(mode="local")`. | [Serve and deploy apps](./serve-and-deploy-apps/_index) |
| **Plugins** | Same decorators and APIs as remote. Secrets come from environment variables. | [Integrations](../integrations/_index) |
| **Secrets** | Read from `.env` files or environment variables. No `flyte create secret` needed. | [Secrets](./task-configuration/secrets) |

---

## Local to remote

The same code runs in both environments. Here's what changes:

| Aspect | Local | Remote |
|--------|-------|--------|
| **Run pipeline** | `flyte run --local` | `flyte run` |
| **TUI** | `--tui` flag | Dashboard in Flyte UI |
| **Caching** | Local SQLite | Cluster-wide distributed cache |
| **Reports** | Local HTML files | Rendered in the Flyte UI |
| **Serving** | `python serve.py` | `flyte deploy serve.py env` |
| **Secrets** | `.env` / environment variables | `flyte create secret` / `flyte.Secret` |
| **Compute** | Your CPU/GPU | `Resources(cpu=2, memory="4Gi", gpu=1)` |

The [`TaskEnvironment`](./core-concepts/task-environment) is the bridge. Locally, image and resource settings are ignored. On the cluster, Flyte builds containers and allocates compute from the same definition.

---

## Next steps

When you're ready to run on a remote Flyte cluster, see [Connecting to a cluster](./connecting-to-a-cluster) to configure the CLI and SDK.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/connecting-to-a-cluster ===

# Connecting to a cluster

This guide covers setting up your local development environment and configuring the `flyte` CLI and SDK to connect to your Union/Flyte instance.

> **📝 Note**
>
> Want to try Flyte without installing anything? [Try Flyte 2 in your browser](https://flyte2intro.apps.demo.hosted.unionai.cloud/).

## Prerequisites

- **Python 3.10+**
- **`uv`** — A fast Python package installer. See the [`uv` installation guide](https://docs.astral.sh/uv/getting-started/installation/).
- Access to a Union/Flyte instance (URL and a project where you can run workflows)

## Install the flyte package

Create a virtual environment and install the `flyte` package:

```bash
uv venv
source .venv/bin/activate
uv pip install flyte
```

> [!NOTE]
> On Windows, use `.venv\Scripts\activate` instead.

Verify installation:

```bash
flyte --version
```

## Configuration file

As we did in [Quickstart](./quickstart), use `flyte create config` to create a configuration file:

```bash
flyte create config \
    --endpoint my-org.my-company.com \
    --domain development \
    --project my-project \
    --builder remote
```

This creates `./.flyte/config.yaml`:

```yaml
admin:
  endpoint: dns:///my-org.my-company.com
image:
  builder: remote
task:
  org: my-org
  domain: development
  project: my-project
```

<details>
<summary>Full example with all options</summary>

Create a custom config file with all available options:
```bash
flyte create config \
    --endpoint my-org.my-company.com \
    --org my-org \
    --domain development \
    --project my-project \
    --builder remote \
    --insecure \
    --output my-config.yaml \
    --force
```

See the [CLI reference](../api-reference/flyte-cli#flyte-create-config) for all parameters.

</details>

<details>
<summary>Config properties explained</summary>

**`admin`** — Connection details for your Union/Flyte instance.

- `endpoint`: URL with `dns:///` prefix. If your UI is at `https://my-org.my-company.com`, use `dns:///my-org.my-company.com`.
- `insecure`: Set to `true` only for local instances without TLS.

**`image`** — Docker image building configuration.

- `builder`: How container images are built.
  - `remote` (Union): Images built on Union's infrastructure.
  - `local` (Flyte OSS): Images built on your machine. Requires Docker. See [Image building](./task-configuration/container-images#image-building).

**`task`** — Default settings for task execution.

- `org`: Organization name (usually matches the first part of your endpoint URL).
- `domain`: Environment separation (`development`, `staging`, `production`).
- `project`: Default project for deployments. Must already exist on your instance. See [Projects and domains](./projects-and-domains) for how to create projects.

</details>

## Using the configuration

You can reference your config file explicitly or let the SDK find it automatically.

### Explicit configuration

### Programmatic

Initialize with [`flyte.init_from_config`](../api-reference/flyte-sdk/packages/flyte/_index#init_from_config):

```python
flyte.init_from_config("my-config.yaml")
run = flyte.run(main)
```

### CLI

Use `--config` or `-c`:

```bash
flyte --config my-config.yaml run hello.py main
flyte -c my-config.yaml run hello.py main
```

<details>
<summary>Configuration precedence</summary>

Without an explicit path, the SDK searches these locations in order:

1. `./config.yaml`
2. `./.flyte/config.yaml`
3. `UCTL_CONFIG` environment variable
4. `FLYTECTL_CONFIG` environment variable
5. `~/.union/config.yaml`
6. `~/.flyte/config.yaml`

</details>

### Programmatic

```python
flyte.init_from_config()
```

### CLI

```bash
flyte run hello.py main
```

### Check current configuration

```bash
flyte get config
```

Output:

```bash
CLIConfig(
    Config(
        platform=PlatformConfig(endpoint='dns:///my-org.my-company.com', scopes=[]),
        task=TaskConfig(org='my-org', project='my-project', domain='development'),
        source=PosixPath('/Users/me/.flyte/config.yaml')
    ),
    ...
)
```

## Inline configuration

Skip the config file entirely by passing parameters directly.

### Programmatic

Use [`flyte.init`](../api-reference/flyte-sdk/packages/flyte/_index#init):

```python
flyte.init(
    endpoint="dns:///my-org.my-company.com",
    org="my-org",
    project="my-project",
    domain="development",
)
```

### CLI

Some parameters go after `flyte`, others after the subcommand:

```bash
flyte \
    --endpoint my-org.my-company.com \
    --org my-org \
    run \
    --domain development \
    --project my-project \
    hello.py \
    main
```

See the [CLI reference](../api-reference/flyte-cli) for details.

See related methods:

* [`flyte.init_from_api_key`](../api-reference/flyte-sdk/packages/flyte/_index#init_from_api_key)
* [`flyte.init_from_config`](../api-reference/flyte-sdk/packages/flyte/_index#init_from_config)
* [`flyte.init_in_cluster`](../api-reference/flyte-sdk/packages/flyte/_index#init_in_cluster)
* [`flyte.init_passthrough`](../api-reference/flyte-sdk/packages/flyte/_index#init_passthrough)

## Next steps

With your environment fully configured, you're ready to build:

- [**Core concepts**](./core-concepts/_index): Understand `TaskEnvironment`s, tasks, runs, and actions through working examples.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/projects-and-domains ===

# Projects and domains

Union.ai organizes work into a hierarchy of **organization**, **projects**, and **domains**.

- **Organization**: Your Union.ai instance, typically representing a company or department. Set up during onboarding and mapped to your endpoint URL (e.g., `my-org.my-company.com`). You do not create or manage organizations directly. The organization is normally determined automatically from your endpoint URL, but you can override it with the `--org` flag on any CLI command (e.g., `flyte --org my-org get project`). This is only relevant if you have a multi-organization installation.
- **Project**: A logical grouping of related workflows, tasks, launch plans, and executions. Projects are the primary unit you create and manage.
- **Domain**: An environment classification within each project. Three fixed domains exist: `development`, `staging`, and `production`. Domains cannot be created or deleted.

Every project contains all three domains, creating **project-domain pairs** like `my-project/development`, `my-project/staging`, and `my-project/production`. Workflows, executions, and data are scoped to a specific project-domain pair.

## How projects and domains are used

When you run or deploy workflows, you target a project and domain:

- **CLI**: Use `--project` and `--domain` flags with `flyte run` or `flyte deploy`, or set defaults in your [configuration file](./connecting-to-a-cluster).
- **Python SDK**: Specify `project` and `domain` in [`flyte.init`](../api-reference/flyte-sdk/packages/flyte/_index#init) or [`flyte.init_from_config`](../api-reference/flyte-sdk/packages/flyte/_index#init_from_config).

Projects and domains also determine:

- **Access control**: RBAC policies scope permissions to an organization, project, domain, or project-domain pair. See [User management](./user-management).
- **Data isolation**: Storage and cache are isolated per project-domain pair.

## Managing projects via CLI

### Create a project

```shell
flyte create project --id my-project --name "My Project"
```

The `--id` is a unique identifier used in CLI commands and configuration (immutable once set). The `--name` is a human-readable display name.

You can also add a description and labels:

```shell
flyte create project \
    --id my-project \
    --name "My Project" \
    --description "ML platform workflows" \
    -l team=ml-platform \
    -l env=prod
```

Labels are specified as `-l key=value` and can be repeated.

### List projects

List all active projects:

```shell
flyte get project
```

Get details of a specific project:

```shell
flyte get project my-project
```

List archived projects:

```shell
flyte get project --archived
```

### Update a project

Update the name, description, or labels of a project:

```shell
flyte update project my-project --description "Updated description"
flyte update project my-project --name "New Display Name"
flyte update project my-project -l team=ml -l env=staging
```

> [!NOTE]
> Setting labels replaces all existing labels on the project.

### Archive a project

Archiving a project hides it from default listings but does not delete its data:

```shell
flyte update project my-project --archive
```

### Unarchive a project

Restore an archived project to active status:

```shell
flyte update project my-project --unarchive
```

## Listing projects programmatically

You can list and retrieve projects from Python using [`flyte.remote.Project`](../api-reference/flyte-sdk/packages/flyte.remote/project/_index):

```python
import flyte

flyte.init_from_config()

# Get a specific project
project = flyte.remote.Project.get(name="my-project", org="my-org")

# List all projects
for project in flyte.remote.Project.listall():
    print(project.to_dict())

# List with filtering and sorting
for project in flyte.remote.Project.listall(sort_by=("created_at", "desc")):
    print(project.to_dict())
```

Both `get()` and `listall()` support async execution via `.aio()`:

```python
project = await flyte.remote.Project.get.aio(name="my-project", org="my-org")
```

> [!NOTE]
> The Python SDK provides read-only access to projects. To create or modify projects, use the `flyte` CLI or the UI.

## Managing projects via the UI

When you log in to your Union.ai instance, you land on the **Projects** page, which lists all projects in your organization. By default, the domain is set to `development`. You can change the active domain using the selector in the top left.

A **Recently viewed** list on the left sidebar provides quick access to your most commonly used projects.

From the project list you can:

* **Open a project**: Select a project from the list to navigate to it.
* **Create a project**: Click **+ New project** in the top right. In the dialog, specify a name and description. The project will be created across all three domains.
* **Archive a project**: Click the three-dot menu on a project's entry and select **Archive project**.

## Domains

Domains provide environment separation within each project. The three domains are:

| Domain | Purpose |
|--------|---------|
| `development` | For iterating on workflows during active development. |
| `staging` | For testing workflows before promoting to production. |
| `production` | For production workloads. |

Domains are predefined and cannot be created, renamed, or deleted.

### Targeting a domain

Set the default domain in your configuration file:

```yaml
task:
  domain: development
```

Or override per command:

```shell
flyte run --domain staging hello.py main
```

When using `flyte deploy`, the domain determines where the deployed workflows will execute:

```shell
flyte deploy --project my-project --domain production workflows
```


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/basic-project ===

# Basic project: RAG

This example demonstrates a two-stage RAG (Retrieval-Augmented Generation) pattern:
an offline embedding pipeline that processes and stores quotes, followed by an online
serving application that enables semantic search.

## Concepts covered

- `TaskEnvironment` for defining task execution environments
- `Dir` artifacts for passing directories between tasks
- `AppEnvironment` for serving applications
- `Parameter` and `RunOutput` for connecting apps to task outputs
- Semantic search with sentence-transformers and ChromaDB

## Part 1: The embedding pipeline

The embedding pipeline fetches quotes from a public API, creates vector embeddings
using sentence-transformers, and stores them in a ChromaDB database.

### Setting up the environment

The `TaskEnvironment` defines the execution environment for all tasks in the pipeline.
It specifies the container image, required packages, and resource allocations:

```python
# Define the embedding environment
embedding_env = flyte.TaskEnvironment(
    name="quote-embedding",
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "sentence-transformers>=2.2.0",
        "chromadb>=0.4.0",
        "requests>=2.31.0",
    ),
    resources=flyte.Resources(cpu=2, memory="4Gi"),
    cache="auto",
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/basic-project/embed.py*

The environment uses:
- `Image.from_debian_base()` to create a container with Python 3.12
- `with_pip_packages()` to install sentence-transformers and ChromaDB
- `Resources` to request 2 CPUs and 4GB of memory
- `cache="auto"` to enable automatic caching of task outputs

### Fetching data

The `fetch_quotes` task retrieves quotes from a public API:

```python
@embedding_env.task
async def fetch_quotes() -> list[dict]:
    """
    Fetch quotes from a public quotes API.

    Returns:
        List of quote dictionaries with 'quote' and 'author' fields.
    """
    import requests

    print("Fetching quotes from API...")
    response = requests.get("https://dummyjson.com/quotes?limit=100")
    response.raise_for_status()

    data = response.json()
    quotes = data.get("quotes", [])

    print(f"Fetched {len(quotes)} quotes")
    return quotes
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/basic-project/embed.py*

This task demonstrates:
- Async task definition with `async def`
- Returning structured data (`list[dict]`) from a task
- Using the `@embedding_env.task` decorator to associate the task with its environment

### Creating embeddings

The `embed_quotes` task creates vector embeddings and stores them in ChromaDB:

```python
@embedding_env.task
async def embed_quotes(quotes: list[dict]) -> Dir:
    """
    Create embeddings for quotes and store them in ChromaDB.

    Args:
        quotes: List of quote dictionaries with 'quote' and 'author' fields.

    Returns:
        Directory containing the ChromaDB database.
    """
    import chromadb
    from sentence_transformers import SentenceTransformer

    print("Loading embedding model...")
    model = SentenceTransformer("all-MiniLM-L6-v2")

    # Create ChromaDB in a temporary directory
    db_dir = tempfile.mkdtemp()
    print(f"Creating ChromaDB at {db_dir}...")

    client = chromadb.PersistentClient(path=db_dir)
    collection = client.create_collection(
        name="quotes",
        metadata={"hnsw:space": "cosine"},
    )

    # Prepare data for insertion
    texts = [q["quote"] for q in quotes]
    ids = [str(q["id"]) for q in quotes]
    metadatas = [{"author": q["author"], "quote": q["quote"]} for q in quotes]

    print(f"Embedding {len(texts)} quotes...")
    embeddings = model.encode(texts, show_progress_bar=True)

    # Add to collection
    collection.add(
        ids=ids,
        embeddings=embeddings.tolist(),
        metadatas=metadatas,
        documents=texts,
    )

    print(f"Stored {len(quotes)} quotes in ChromaDB")
    return await Dir.from_local(db_dir)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/basic-project/embed.py*

Key points:
- Uses the `all-MiniLM-L6-v2` model from sentence-transformers (runs on CPU)
- Creates a persistent ChromaDB database with cosine similarity
- Returns a `Dir` artifact that captures the entire database directory
- The `await Dir.from_local()` call uploads the directory to artifact storage

### Orchestrating the pipeline

The main pipeline task composes the individual tasks:

```python
@embedding_env.task
async def embedding_pipeline() -> Dir:
    """
    Main pipeline that fetches quotes and creates embeddings.

    Returns:
        Directory containing the ChromaDB database with quote embeddings.
    """
    print("Starting embedding pipeline...")

    # Fetch quotes from API
    quotes = await fetch_quotes()

    # Create embeddings and store in ChromaDB
    db_dir = await embed_quotes(quotes)

    print("Embedding pipeline complete!")
    return db_dir
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/basic-project/embed.py*

### Running the pipeline

To run the embedding pipeline:

```python
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(embedding_pipeline)
    print(f"Embedding run URL: {run.url}")
    run.wait()
    print(f"Embedding complete! Database directory: {run.outputs()}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/basic-project/embed.py*

```bash
uv run embed.py
```

The pipeline will:
1. Fetch 100 quotes from the API
2. Create embeddings using sentence-transformers
3. Store everything in a ChromaDB database
4. Return the database as a `Dir` artifact

## Part 2: The serving application

The serving application provides a Streamlit web interface for searching quotes
using the embeddings created by the pipeline.

### App environment configuration

The `AppEnvironment` defines how the application runs:

```python
# Define the app environment
env = AppEnvironment(
    name="quote-search-app",
    description="Semantic search over quotes using embeddings",
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "streamlit>=1.41.0",
        "sentence-transformers>=2.2.0",
        "chromadb>=0.4.0",
    ),
    args=["streamlit", "run", "app.py", "--server.port", "8080"],
    port=8080,
    resources=flyte.Resources(cpu=2, memory="4Gi"),
    parameters=[
        Parameter(
            name="quotes_db",
            value=RunOutput(task_name="quote-embedding.embedding_pipeline", type="directory"),
            download=True,
            env_var="QUOTES_DB_PATH",
        ),
    ],
    include=["app.py"],
    requires_auth=False,
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/basic-project/serve.py*

Key configuration:
- `args` specifies the command to run the Streamlit app
- `port=8080` exposes the application on port 8080
- `parameters` defines inputs to the app:
  - `RunOutput` connects to the embedding pipeline's output
  - `download=True` downloads the directory to local storage
  - `env_var="QUOTES_DB_PATH"` makes the path available to the app
- `include=["app.py"]` bundles the Streamlit app with the deployment

### The Streamlit application

The app loads the ChromaDB database using the path from the environment variable:

```python
# Load the database
@st.cache_resource
def load_db():
    db_path = os.environ.get("QUOTES_DB_PATH")
    if not db_path:
        st.error("QUOTES_DB_PATH environment variable not set")
        st.stop()

    client = chromadb.PersistentClient(path=db_path)
    collection = client.get_collection("quotes")
    model = SentenceTransformer("all-MiniLM-L6-v2")
    return collection, model

collection, model = load_db()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/basic-project/app.py*

The search interface provides a text input and result count slider:

```python
# Search interface
query = st.text_input("Enter your search query:", placeholder="e.g., love, wisdom, success")
top_k = st.slider("Number of results:", min_value=1, max_value=20, value=5)

col1, col2 = st.columns([1, 1])
with col1:
    search_button = st.button("Search", type="primary", use_container_width=True)
with col2:
    random_button = st.button("Random Quote", use_container_width=True)

st.divider()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/basic-project/app.py*

When the user searches, the app encodes the query and finds similar quotes:

```python
if search_button and query:
    # Encode query and search
    query_embedding = model.encode([query])[0].tolist()
    results = collection.query(
        query_embeddings=[query_embedding],
        n_results=top_k,
    )

    if results["documents"] and results["documents"][0]:
        for i, (doc, metadata, distance) in enumerate(
            zip(results["documents"][0], results["metadatas"][0], results["distances"][0])
        ):
            similarity = 1 - distance  # Convert distance to similarity
            st.markdown(f'**{i+1}.** "{doc}"')
            st.caption(f"— {metadata['author']} | Similarity: {similarity:.2%}")
            st.write("")
    else:
        st.info("No results found.")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/basic-project/app.py*

The app also includes a random quote feature:

```python
elif random_button:
    # Get a random quote from the collection
    all_data = collection.get(limit=100)
    if all_data["documents"]:
        idx = random.randint(0, len(all_data["documents"]) - 1)
        quote = all_data["documents"][idx]
        author = all_data["metadatas"][idx]["author"]
        st.markdown(f'**"{quote}"**')
        st.caption(f"— {author}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/basic-project/app.py*

### Deploying the app

To deploy the quote search application:

```python
if __name__ == "__main__":
    flyte.init_from_config()

    # Deploy the quote search app
    print("Deploying quote search app...")
    deployment = flyte.serve(env)
    print(f"App deployed at: {deployment.url}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/basic-project/serve.py*

```bash
uv run serve.py
```

The app will be deployed and automatically connected to the embedding pipeline's
output through the `RunOutput` parameter.

## Key takeaways

1. **Two-stage RAG pattern**: Separate offline embedding creation from online serving
   for better resource utilization and cost efficiency.

2. **Dir artifacts**: Use `Dir` to pass entire directories (like databases) between
   tasks and to serving applications.

3. **RunOutput**: Connect applications to task outputs declaratively, enabling
   automatic data flow between pipelines and apps.

4. **CPU-friendly embeddings**: The `all-MiniLM-L6-v2` model runs efficiently on CPU,
   making this pattern accessible without GPU resources.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/advanced-project ===

# Advanced project: LLM reporting agent

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

This example demonstrates a resilient agentic report generator that showcases
Flyte 2.0's advanced features for building production-grade AI workflows.

## What you'll build

A batch report generator that:
1. Processes multiple topics in parallel
2. Iteratively critiques and refines each report until it meets a quality threshold
3. Produces multiple output formats (Markdown, HTML, summary) for each report
4. Serves results through an interactive UI

## Concepts covered

| Feature | Description |
|---------|-------------|
| `ReusePolicy` | Keep containers warm for high-throughput batch processing |
| `@flyte.trace` | Checkpoint LLM calls for recovery and observability |
| `RetryStrategy` | Handle transient API failures gracefully |
| `flyte.group` | Organize parallel batches and iterations in the UI |
| `asyncio.gather` | Fan out to process multiple topics concurrently |
| Pydantic models | Structured LLM outputs |
| `AppEnvironment` | Deploy interactive Streamlit apps |
| `RunOutput` | Connect apps to pipeline outputs |

## Architecture

```mermaid
flowchart TD
    A[Topics List] --> B

    B["report_batch_pipeline<br/><i>driver_env</i>"]

    subgraph B1 ["refine_all (parallel)"]
        direction LR
        R1["refine_report<br/>topic 1"]
        R2["refine_report<br/>topic 2"]
        R3["refine_report<br/>topic N"]
    end
    B --> B1

    subgraph B2 ["format_all (parallel)"]
        direction LR
        F1["format_outputs<br/>report 1"]
        F2["format_outputs<br/>report 2"]
        F3["format_outputs<br/>report N"]
    end
    B1 --> B2

    B2 --> C["Output: List of Dirs"]
```

Each `refine_report` task runs in a reusable container (`llm_env`) and performs
multiple LLM calls through traced functions:

```mermaid
flowchart TD
    A[Topic] --> B["generate_initial_draft<br/><i>@flyte.trace</i>"]
    B --> C

    subgraph C ["refinement_loop"]
        direction TB
        D["critique_content<br/><i>@flyte.trace</i>"] -->|score >= threshold| E[exit loop]
        D -->|score < threshold| F["revise_content<br/><i>@flyte.trace</i>"]
        F --> D
    end
    C --> G[Refined Report]
```

## Prerequisites

- A Union.ai account with an active project
- An OpenAI API key stored as a secret named `openai-api-key`

To create the secret:

```bash
flyte secret create openai-api-key
```

## Parts

1. ****Advanced project: LLM reporting agent > Resilient generation****: Set up reusable environments, traced LLM calls, and retry strategies
2. ****Advanced project: LLM reporting agent > Agentic refinement****: Build the iterative critique-and-revise loop
3. ****Advanced project: LLM reporting agent > Parallel outputs****: Generate multiple formats concurrently
4. ****Advanced project: LLM reporting agent > Serving app****: Deploy an interactive UI for report generation

[Resilient generation]()

## Key takeaways

1. **Reusable environments for batch processing**: `ReusePolicy` keeps containers warm,
   enabling efficient processing of multiple topics without cold start overhead. With
   5 topics × ~7 LLM calls each, the reusable pool handles ~35 calls efficiently.

2. **Checkpointed LLM calls**: `@flyte.trace` provides automatic checkpointing at the
   function level, enabling recovery without re-running expensive API calls.

3. **Agentic patterns**: The generate-critique-revise loop demonstrates how to build
   self-improving AI workflows with clear observability through `flyte.group`.

4. **Parallel fan-out**: `asyncio.gather` processes multiple topics concurrently,
   maximizing throughput by running refinement tasks in parallel across the batch.

## Subpages
- **Advanced project: LLM reporting agent > Resilient generation**
- **Advanced project: LLM reporting agent > Agentic refinement**
- **Advanced project: LLM reporting agent > Parallel outputs**
- **Advanced project: LLM reporting agent > Serving app**


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/advanced-project/resilient-generation ===

# Resilient generation

This section covers the foundational patterns for building resilient LLM-powered
tasks: reusable environments, traced function calls, and retry strategies.

## Two environments

This example uses two task environments with different characteristics:

1. **`llm_env`** (reusable): For tasks that make many LLM calls in a loop or
   process batches in parallel. Container reuse avoids cold starts.
2. **`driver_env`** (standard): For orchestration tasks that fan out work to
   other tasks but don't make LLM calls themselves.

### Reusable environment for LLM work

When processing a batch of topics, each topic goes through multiple LLM calls
(generate, critique, revise, repeat). With 5 topics × ~7 calls each, that's ~35
LLM calls. `ReusePolicy` keeps containers warm to handle this efficiently:

```python
# Reusable environment for tasks that make many LLM calls in a loop.
# The ReusePolicy keeps containers warm, reducing cold start latency for iterative work.
llm_env = flyte.TaskEnvironment(
    name="llm-worker",
    secrets=[] if MOCK_MODE else [flyte.Secret(key="openai-api-key", as_env_var="OPENAI_API_KEY")],
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "unionai-reuse>=0.1.10",
        "openai>=1.0.0",
        "pydantic>=2.0.0",
    ),
    resources=flyte.Resources(cpu=1, memory="2Gi"),
    reusable=flyte.ReusePolicy(
        replicas=2,              # Keep 2 container instances ready
        concurrency=4,           # Allow 4 concurrent tasks per container
        scaledown_ttl=timedelta(minutes=5),   # Wait 5 min before scaling down
        idle_ttl=timedelta(minutes=30),       # Shut down after 30 min idle
    ),
    cache="auto",
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/advanced-project/generate.py*

### ReusePolicy parameters

| Parameter | Description |
|-----------|-------------|
| `replicas` | Number of container instances to keep ready (or `(min, max)` tuple) |
| `concurrency` | Maximum tasks per container at once |
| `scaledown_ttl` | Minimum wait before scaling down a replica |
| `idle_ttl` | Time after which idle containers shut down completely |

The configuration above keeps 2 containers ready, allows 4 concurrent tasks per
container, waits 5 minutes before scaling down, and shuts down after 30 minutes
of inactivity.

> **📝 Note**
>
> Both `scaledown_ttl` and `idle_ttl` must be at least 30 seconds.

### Standard environment for orchestration

The driver environment doesn't need container reuse—it just coordinates work.
The `depends_on` parameter declares that tasks in this environment call tasks
in `llm_env`, ensuring both environments are deployed together:

```python
# Standard environment for orchestration tasks that don't need container reuse.
# depends_on declares that this environment's tasks call tasks in llm_env.
driver_env = flyte.TaskEnvironment(
    name="driver",
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "pydantic>=2.0.0",
    ),
    resources=flyte.Resources(cpu=1, memory="1Gi"),
    depends_on=[llm_env],
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/advanced-project/generate.py*

## Traced LLM calls

The `@flyte.trace` decorator provides automatic checkpointing at the function level.
When a traced function completes successfully, its result is cached. If the task
fails and restarts, previously completed traced calls return their cached results
instead of re-executing.

```python
@flyte.trace
async def call_llm(prompt: str, system: str, json_mode: bool = False) -> str:
    """
    Make an LLM call with automatic checkpointing.

    The @flyte.trace decorator provides:
    - Automatic caching of results for identical inputs
    - Recovery from failures without re-running successful calls
    - Full observability in the Flyte UI

    Args:
        prompt: The user prompt to send
        system: The system prompt defining the LLM's role
        json_mode: Whether to request JSON output

    Returns:
        The LLM's response text
    """
    # Use mock responses for testing without API keys
    if MOCK_MODE:
        import asyncio
        await asyncio.sleep(0.5)  # Simulate API latency

        if "critique" in prompt.lower() or "critic" in system.lower():
            # Return good score if draft has been revised (contains revision marker)
            if "[REVISED]" in prompt:
                return MOCK_CRITIQUE_GOOD
            return MOCK_CRITIQUE_NEEDS_WORK
        elif "summary" in system.lower():
            return MOCK_SUMMARY
        elif "revis" in system.lower():
            # Return revised version with marker
            return MOCK_REPORT.replace("## Introduction", "[REVISED]\n\n## Introduction")
        else:
            return MOCK_REPORT

    from openai import AsyncOpenAI

    client = AsyncOpenAI()

    kwargs = {
        "model": "gpt-4o-mini",
        "messages": [
            {"role": "system", "content": system},
            {"role": "user", "content": prompt},
        ],
        "max_tokens": 2000,
    }

    if json_mode:
        kwargs["response_format"] = {"type": "json_object"}

    response = await client.chat.completions.create(**kwargs)
    return response.choices[0].message.content
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/advanced-project/generate.py*

### Benefits of tracing

1. **Cost savings**: Failed tasks don't re-run expensive API calls that already succeeded
2. **Faster recovery**: Resuming from checkpoints skips completed work
3. **Observability**: Each traced call appears in the Flyte UI with timing data

### When to use @flyte.trace

Use `@flyte.trace` for:
- LLM API calls (OpenAI, Anthropic, etc.)
- External API requests
- Any expensive operation you don't want to repeat on retry

Don't use `@flyte.trace` for:
- Simple computations (overhead outweighs benefit)
- Operations with side effects that shouldn't be skipped

## Traced helper functions

The LLM-calling functions are decorated with `@flyte.trace` rather than being
separate tasks. This keeps the architecture simple while still providing
checkpointing:

```python
@flyte.trace
async def generate_initial_draft(topic: str) -> str:
    """
    Generate the initial report draft.

    The @flyte.trace decorator provides checkpointing - if the task fails
    after this completes, it won't re-run on retry.

    Args:
        topic: The topic to write about

    Returns:
        The initial draft in markdown format
    """
    print(f"Generating initial draft for topic: {topic}")

    prompt = f"Write a comprehensive report on the following topic:\n\n{topic}"
    draft = await call_llm(prompt, GENERATOR_SYSTEM_PROMPT)

    print(f"Generated initial draft ({len(draft)} characters)")
    return draft
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/advanced-project/generate.py*

These traced functions run inside the `refine_report` task. If the task fails
and retries, completed traced calls return cached results instead of re-executing.

## Retry strategies

The task that orchestrates the LLM calls uses `retries` to handle transient failures:

```python
@llm_env.task(retries=3)
async def refine_report(topic: str, ...) -> str:
    # Traced functions are called here
    draft = await generate_initial_draft(topic)
    ...
```

### Configuring retries

You can specify retries as a simple integer:

```python
@llm_env.task(retries=3)
async def my_task():
    ...
```

Or use `RetryStrategy` for more control:

```python
@llm_env.task(retries=flyte.RetryStrategy(count=3))
async def my_task():
    ...
```

### Combining tracing with retries

When you combine `@flyte.trace` with task-level retries, you get the best of both:

1. Task fails after completing some traced calls
2. Flyte retries the task
3. Previously completed traced calls return cached results
4. Only the failed operation (and subsequent ones) re-execute

This pattern is essential for multi-step LLM workflows where you don't want to
re-run the entire chain when a single call fails.

## Structured prompts

The example uses a separate `prompts.py` module for system prompts and Pydantic models:

```python
GENERATOR_SYSTEM_PROMPT = """You are an expert report writer. Generate a well-structured,
informative report on the given topic. The report should include:

1. An engaging introduction that sets context
2. Clear sections with descriptive headings
3. Specific facts, examples, or data points where relevant
4. A conclusion that summarizes key takeaways

Write in a professional but accessible tone. Use markdown formatting for structure.
Aim for approximately 500-800 words."""

CRITIC_SYSTEM_PROMPT = """You are a demanding but fair editor reviewing a report draft.
Evaluate the report on these criteria:

- Clarity: Is the writing clear and easy to follow?
- Structure: Is it well-organized with logical flow?
- Depth: Does it provide sufficient detail and insight?
- Accuracy: Are claims supported and reasonable?
- Engagement: Is it interesting to read?

Provide your response as JSON matching this schema:
{
    "score": <1-10 integer>,
    "strengths": ["strength 1", "strength 2", ...],
    "improvements": ["improvement 1", "improvement 2", ...],
    "summary": "brief overall assessment"
}

Be specific in your feedback. A score of 8+ means the report is ready for publication."""

REVISER_SYSTEM_PROMPT = """You are an expert editor revising a report based on feedback.
Your task is to improve the report by addressing the specific improvements requested
while preserving its strengths.

Guidelines:
- Address each improvement point specifically
- Maintain the original voice and style
- Keep the same overall structure unless restructuring is requested
- Preserve any content that was praised as a strength
- Ensure the revised version is cohesive and flows well

Return only the revised report in markdown format, no preamble or explanation."""

SUMMARY_SYSTEM_PROMPT = """Create a concise executive summary (2-3 paragraphs) of the
following report. Capture the key points and main takeaways. Write in a professional
tone suitable for busy executives who need the essential information quickly."""
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/advanced-project/prompts.py*

### Pydantic models for structured output

LLM responses can be unpredictable. Using Pydantic models with JSON mode ensures
you get structured, validated data:

```python
class Critique(BaseModel):
    """Structured critique response from the LLM."""

    score: int = Field(
        ge=1,
        le=10,
        description="Quality score from 1-10, where 10 is publication-ready",
    )
    strengths: list[str] = Field(
        description="List of strengths in the current draft",
    )
    improvements: list[str] = Field(
        description="Specific improvements needed",
    )
    summary: str = Field(
        description="Brief summary of the critique",
    )
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/advanced-project/prompts.py*

The `Critique` model validates that:
- `score` is an integer between 1 and 10
- `strengths` and `improvements` are lists of strings
- All required fields are present

If the LLM returns malformed JSON, Pydantic raises a validation error, which
triggers a retry (if configured).

## Next steps

With resilient generation in place, you're ready to build the
[agentic refinement loop](./agentic-refinement).


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/advanced-project/agentic-refinement ===

# Agentic refinement

The core of this example is an agentic refinement loop: generate content, critique
it, revise based on feedback, and repeat until quality meets a threshold. This
pattern is fundamental to building self-improving AI systems.

## The agentic pattern

Traditional pipelines are linear: input → process → output. Agentic workflows
are iterative: they evaluate their own output and improve it through multiple
cycles.

```mermaid
flowchart TD
    A[Generate] --> B[Critique]
    B -->|score >= threshold| C[Done]
    B -->|score < threshold| D[Revise]
    D --> B
```

## Critique function

The critique function evaluates the current draft and returns structured feedback.
It's a traced function (not a separate task) that runs inside `refine_report`:

```python
@flyte.trace
async def critique_content(draft: str) -> Critique:
    """
    Critique the current draft and return structured feedback.

    Uses Pydantic models to parse the LLM's JSON response into
    a typed object for reliable downstream processing.

    Args:
        draft: The current draft to critique

    Returns:
        Structured critique with score, strengths, and improvements
    """
    print("Critiquing current draft...")

    response = await call_llm(
        f"Please critique the following report:\n\n{draft}",
        CRITIC_SYSTEM_PROMPT,
        json_mode=True,
    )

    # Parse the JSON response into our Pydantic model
    critique_data = json.loads(response)
    critique = Critique(**critique_data)

    print(f"Critique score: {critique.score}/10")
    print(f"Strengths: {len(critique.strengths)}, Improvements: {len(critique.improvements)}")

    return critique
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/advanced-project/generate.py*

Key points:
- Uses `json_mode=True` to ensure the LLM returns valid JSON
- Parses the response into a Pydantic `Critique` model
- Returns a typed object for reliable downstream processing
- `@flyte.trace` provides checkpointing—if the task retries, completed critiques aren't re-run

## Revise function

The revise function takes the current draft and specific improvements to address:

```python
@flyte.trace
async def revise_content(draft: str, improvements: list[str]) -> str:
    """
    Revise the draft based on critique feedback.

    Args:
        draft: The current draft to revise
        improvements: List of specific improvements to address

    Returns:
        The revised draft
    """
    print(f"Revising draft to address {len(improvements)} improvements...")

    improvements_text = "\n".join(f"- {imp}" for imp in improvements)
    prompt = f"""Please revise the following report to address these improvements:

IMPROVEMENTS NEEDED:
{improvements_text}

CURRENT DRAFT:
{draft}"""

    revised = await call_llm(prompt, REVISER_SYSTEM_PROMPT)

    print(f"Revision complete ({len(revised)} characters)")
    return revised
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/advanced-project/generate.py*

The prompt includes:
1. The list of improvements from the critique
2. The current draft to revise

This focused approach helps the LLM make targeted changes rather than rewriting
from scratch.

## The refinement loop

The `refine_report` task orchestrates the iterative refinement. It runs in the
reusable `llm_env` because it makes multiple LLM calls through traced functions:

```python
@llm_env.task(retries=3)
async def refine_report(
    topic: str,
    max_iterations: int = 3,
    quality_threshold: int = 8,
) -> str:
    """
    Iteratively refine a report until it meets the quality threshold.

    This task runs in a reusable container because it makes multiple LLM calls
    in a loop. The traced helper functions provide checkpointing, so if the
    task fails mid-loop, completed LLM calls won't be re-run on retry.

    Args:
        topic: The topic to write about
        max_iterations: Maximum refinement cycles (default: 3)
        quality_threshold: Minimum score to accept (default: 8)

    Returns:
        The final refined report
    """
    # Generate initial draft
    draft = await generate_initial_draft(topic)

    # Iterative refinement loop
    for i in range(max_iterations):
        with flyte.group(f"refinement_{i + 1}"):
            # Get critique
            critique = await critique_content(draft)

            # Check if we've met the quality threshold
            if critique.score >= quality_threshold:
                print(f"Quality threshold met at iteration {i + 1}!")
                print(f"Final score: {critique.score}/10")
                break

            # Revise based on feedback
            print(f"Score {critique.score} < {quality_threshold}, revising...")
            draft = await revise_content(draft, critique.improvements)
    else:
        print(f"Reached max iterations ({max_iterations})")

    return draft
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/advanced-project/generate.py*

### How it works

1. **Generate initial draft**: Creates the first version of the report
2. **Enter refinement loop**: Iterates up to `max_iterations` times
3. **Critique**: Evaluates the current draft and assigns a score
4. **Check threshold**: If score meets `quality_threshold`, exit early
5. **Revise**: If below threshold, revise based on improvements
6. **Repeat**: Continue until threshold met or iterations exhausted

All the LLM calls (generate, critique, revise) are traced functions inside this
single task. This keeps the task graph simple while the reusable container handles
the actual LLM work efficiently.

### Early exit

The `if critique.score >= quality_threshold: break` pattern enables early exit
when quality is sufficient. This saves compute costs and time—no need to run
all iterations if the first draft is already good.

## Grouping iterations with flyte.group

Each refinement iteration is wrapped in `flyte.group`:

```python
for i in range(max_iterations):
    with flyte.group(f"refinement_{i + 1}"):
        critique = await critique_content(draft)
        # ...
```

### Why use flyte.group?

Groups provide hierarchical organization in the Flyte UI. Since critique and
revise are traced functions (not separate tasks), groups help organize them:

```
refine_report
├── generate_initial_draft (traced)
├── refinement_1
│   ├── critique_content (traced)
│   └── revise_content (traced)
├── refinement_2
│   ├── critique_content (traced)
│   └── revise_content (traced)
└── [returns refined report]
```

Benefits:
- **Clarity**: See exactly how many iterations occurred
- **Debugging**: Quickly find which iteration had issues
- **Observability**: Track time spent in each refinement cycle

### Group context

Groups are implemented as context managers. All traced calls and nested groups
within the `with flyte.group(...)` block are associated with that group.

## Configuring the loop

The refinement loop accepts parameters to tune its behavior:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `max_iterations` | 3 | Upper bound on refinement cycles |
| `quality_threshold` | 8 | Minimum score (1-10) to accept |

### Choosing thresholds

- **Higher threshold** (9-10): More refinement cycles, higher quality, more API costs
- **Lower threshold** (6-7): Faster completion, may accept lower quality
- **More iterations**: Safety net for difficult topics
- **Fewer iterations**: Cost control, faster turnaround

A good starting point is `quality_threshold=8` with `max_iterations=3`. Adjust
based on your quality requirements and budget.

## Best practices for agentic loops

1. **Always set max iterations**: Prevent infinite loops if the quality threshold
   is never reached.

2. **Use structured critiques**: Pydantic models ensure you can reliably extract
   the score and improvements from LLM responses.

3. **Log iteration progress**: Print statements help debug when reviewing logs:
   ```python
   print(f"Iteration {i + 1}: score={critique.score}")
   ```

4. **Consider diminishing returns**: After 3-4 iterations, improvements often
   become marginal. Set `max_iterations` accordingly.

5. **Use groups for observability**: `flyte.group` makes the iterative nature
   visible in the UI, essential for debugging and monitoring.

## Next steps

With the agentic refinement loop complete, learn how to
[generate multiple outputs in parallel](./parallel-outputs).


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/advanced-project/parallel-outputs ===

# Parallel outputs

After refining the report, the pipeline generates multiple output formats in
parallel. This demonstrates how to use `asyncio.gather` for concurrent execution
within a task.

## The formatting functions

The pipeline generates three outputs: markdown, HTML, and an executive summary.
Only `generate_summary` uses `@flyte.trace` because it makes an LLM call.
The markdown and HTML functions are simple, deterministic transformations that
don't benefit from checkpointing:

```python
async def format_as_markdown(content: str) -> str:
    """Format the report as clean markdown."""
    # Content is already markdown, but we could add TOC, metadata, etc.
    return f"""---
title: Generated Report
date: {__import__('datetime').datetime.now().isoformat()}
---

{content}
"""

async def format_as_html(content: str) -> str:
    """Convert the report to HTML."""
    # Simple markdown to HTML conversion
    import re

    html = content
    # Convert headers
    html = re.sub(r"^### (.+)$", r"<h3>\1</h3>", html, flags=re.MULTILINE)
    html = re.sub(r"^## (.+)$", r"<h2>\1</h2>", html, flags=re.MULTILINE)
    html = re.sub(r"^# (.+)$", r"<h1>\1</h1>", html, flags=re.MULTILINE)
    # Convert bold/italic
    html = re.sub(r"\*\*(.+?)\*\*", r"<strong>\1</strong>", html)
    html = re.sub(r"\*(.+?)\*", r"<em>\1</em>", html)
    # Convert paragraphs
    html = re.sub(r"\n\n", r"</p><p>", html)

    return f"""<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Generated Report</title>
    <style>
        body {{ font-family: system-ui, sans-serif; max-width: 800px; margin: 2rem auto; padding: 0 1rem; }}
        h1, h2, h3 {{ color: #333; }}
        p {{ line-height: 1.6; }}
    </style>
</head>
<body>
<p>{html}</p>
</body>
</html>
"""

@flyte.trace
async def generate_summary(content: str) -> str:
    """Generate an executive summary of the report."""
    return await call_llm(content, SUMMARY_SYSTEM_PROMPT)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/advanced-project/generate.py*

### When to trace and when not to

Use `@flyte.trace` for operations that are expensive, non-deterministic, or
call external APIs (like `generate_summary`). Skip it for cheap, deterministic
transformations (like `format_as_markdown` and `format_as_html`) where
re-running on retry is trivial.

## Parallel execution with asyncio.gather

The `format_outputs` task runs all formatters concurrently:

```python
@llm_env.task
async def format_outputs(content: str) -> Dir:
    """
    Generate multiple output formats in parallel.

    Uses asyncio.gather to run all formatting operations concurrently,
    maximizing efficiency when each operation is I/O-bound.

    Args:
        content: The final report content

    Returns:
        Directory containing all formatted outputs
    """
    print("Generating output formats in parallel...")

    with flyte.group("formatting"):
        # Run all formatting operations in parallel
        markdown, html, summary = await asyncio.gather(
            format_as_markdown(content),
            format_as_html(content),
            generate_summary(content),
        )

    # Write outputs to a directory
    output_dir = tempfile.mkdtemp()

    with open(os.path.join(output_dir, "report.md"), "w") as f:
        f.write(markdown)

    with open(os.path.join(output_dir, "report.html"), "w") as f:
        f.write(html)

    with open(os.path.join(output_dir, "summary.txt"), "w") as f:
        f.write(summary)

    print(f"Created outputs in {output_dir}")
    return await Dir.from_local(output_dir)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/advanced-project/generate.py*

### How asyncio.gather works

`asyncio.gather` takes multiple coroutines and runs them concurrently:

```python
markdown, html, summary = await asyncio.gather(
    format_as_markdown(content),  # Starts immediately
    format_as_html(content),      # Starts immediately
    generate_summary(content),    # Starts immediately
)
# All three run concurrently, results returned in order
```

Without `gather`, these would run sequentially:

```python
# Sequential (slower)
markdown = await format_as_markdown(content)  # Wait for completion
html = await format_as_html(content)          # Then start this
summary = await generate_summary(content)     # Then start this
```

### When to use asyncio.gather

Use `asyncio.gather` when:
- Operations are independent (don't depend on each other's results)
- Operations are I/O-bound (API calls, file operations)
- You want to minimize total execution time

Don't use `asyncio.gather` when:
- Operations depend on each other
- Operations are CPU-bound (use process pools instead)
- Order of execution matters for side effects

## Grouping parallel operations

The parallel formatting is wrapped in a group for UI clarity:

```python
with flyte.group("formatting"):
    markdown, html, summary = await asyncio.gather(...)
```

In the Flyte UI, the traced call within the group is visible:

```
format_outputs
└── formatting
    ├── format_as_markdown
    ├── format_as_html
    └── generate_summary (traced)
```

## Collecting outputs in a directory

The formatted outputs are written to a temporary directory and returned as a
`Dir` artifact:

```python
output_dir = tempfile.mkdtemp()

with open(os.path.join(output_dir, "report.md"), "w") as f:
    f.write(markdown)

with open(os.path.join(output_dir, "report.html"), "w") as f:
    f.write(html)

with open(os.path.join(output_dir, "summary.txt"), "w") as f:
    f.write(summary)

return await Dir.from_local(output_dir)
```

The `Dir.from_local()` call uploads the directory to Union.ai's
artifact storage, making it available to downstream tasks or applications.

## The batch pipeline

The batch pipeline processes multiple topics in parallel, demonstrating where
`ReusePolicy` truly shines:

```python
@driver_env.task
async def report_batch_pipeline(
    topics: list[str],
    max_iterations: int = 3,
    quality_threshold: int = 8,
) -> list[Dir]:
    """
    Generate reports for multiple topics in parallel.

    This is where ReusePolicy shines: with N topics, each going through
    up to max_iterations refinement cycles, the reusable container pool
    handles potentially N × 7 LLM calls efficiently without cold starts.

    Args:
        topics: List of topics to write about
        max_iterations: Maximum refinement cycles per topic
        quality_threshold: Minimum quality score to accept

    Returns:
        List of directories, each containing a report's formatted outputs
    """
    print(f"Starting batch pipeline for {len(topics)} topics...")

    # Fan out: refine all reports in parallel
    # Each refine_report makes 2-7 LLM calls, all hitting the reusable pool
    with flyte.group("refine_all"):
        reports = await asyncio.gather(*[
            refine_report(topic, max_iterations, quality_threshold)
            for topic in topics
        ])

    print(f"All {len(reports)} reports refined, formatting outputs...")

    # Fan out: format all reports in parallel
    with flyte.group("format_all"):
        outputs = await asyncio.gather(*[
            format_outputs(report)
            for report in reports
        ])

    print(f"Batch pipeline complete! Generated {len(outputs)} reports.")
    return outputs
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/advanced-project/generate.py*

### Pipeline flow

1. **Fan out refine_all**: Process all topics in parallel using `asyncio.gather`
2. **Fan out format_all**: Format all reports in parallel
3. **Return list of Dirs**: Each directory contains one report's outputs

With 5 topics, each making ~7 LLM calls, the reusable container pool handles
~35 LLM calls efficiently without cold starts.

## Running the pipeline

To run the batch pipeline:

```python
if __name__ == "__main__":
    flyte.init_from_config()

    # Multiple topics to generate reports for
    topics = [
        "The Impact of Large Language Models on Software Development",
        "Edge Computing: Bringing AI to IoT Devices",
        "Quantum Computing: Current State and Near-Term Applications",
        "The Rise of Rust in Systems Programming",
        "WebAssembly: The Future of Browser-Based Applications",
    ]

    print(f"Submitting batch run for {len(topics)} topics...")
    import sys
    sys.stdout.flush()

    # Run the batch pipeline - this will generate all reports in parallel,
    # with the reusable container pool handling 5 topics × ~7 LLM calls each
    run = flyte.run(
        report_batch_pipeline,
        topics=topics,
        max_iterations=3,
        quality_threshold=8,
    )
    print(f"Batch report generation run URL: {run.url}")
    sys.stdout.flush()
    print("Waiting for pipeline to complete (Ctrl+C to skip)...")
    try:
        run.wait()
        print(f"Pipeline complete! Outputs: {run.outputs()}")
    except KeyboardInterrupt:
        print(f"\nSkipped waiting. Check status at: {run.url}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/advanced-project/generate.py*

```bash
uv run generate.py
```

The pipeline will:
1. Process all topics in parallel (each with iterative refinement)
2. Format all reports in parallel
3. Return a list of directories, each containing a report's outputs

## Cost optimization tips

### 1. Choose the right model

The example uses `gpt-4o-mini` for cost efficiency. For higher quality (at higher
cost), you could use `gpt-4o` or `gpt-4-turbo`:

```python
response = await client.chat.completions.create(
    model="gpt-4o",  # More capable, more expensive
    ...
)
```

### 2. Tune iteration parameters

Fewer iterations mean fewer API calls:

```python
run = flyte.run(
    report_batch_pipeline,
    topics=["Topic A", "Topic B"],
    max_iterations=2,      # Limit iterations
    quality_threshold=7,   # Accept slightly lower quality
)
```

### 3. Use caching effectively

The `cache="auto"` setting on the environment caches task outputs. Running the
same pipeline with the same inputs returns cached results instantly:

```python
llm_env = flyte.TaskEnvironment(
    ...
    cache="auto",  # Cache task outputs
)
```

### 4. Scale the batch

The batch pipeline already processes topics in parallel. To handle larger batches,
adjust the `ReusePolicy`:

```python
reusable=flyte.ReusePolicy(
    replicas=4,           # More containers for larger batches
    concurrency=4,        # Tasks per container
    ...
)
```

With 4 replicas × 4 concurrency = 16 slots, you can process 16 topics' refinement
tasks concurrently.

## Next steps

Learn how to [deploy a serving app](./serving-app) that connects to the pipeline
outputs and provides an interactive UI for report generation.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/advanced-project/serving-app ===

# Serving app

The final piece is a serving application that displays generated reports and
provides an interactive interface. This demonstrates how to connect apps to
pipeline outputs using `RunOutput`.

## App environment configuration

The `AppEnvironment` defines how the Streamlit application runs and connects to
the batch report pipeline:

```python
# Define the app environment
env = AppEnvironment(
    name="report-generator-app",
    description="Interactive report generator with AI-powered refinement",
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "streamlit>=1.41.0",
    ),
    args=["streamlit", "run", "app.py", "--server.port", "8080"],
    port=8080,
    resources=flyte.Resources(cpu=1, memory="2Gi"),
    parameters=[
        # Connect to the batch pipeline output (list of report directories)
        Parameter(
            name="reports",
            value=RunOutput(
                task_name="driver.report_batch_pipeline",
                type="directory",
            ),
            download=True,
            env_var="REPORTS_PATH",
        ),
    ],
    include=["app.py"],
    requires_auth=False,
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/advanced-project/serve.py*

### Key configuration

| Setting | Purpose |
|---------|---------|
| `args` | Command to run the Streamlit app |
| `port` | Port the app listens on |
| `parameters` | Inputs to the app, including pipeline connections |
| `include` | Additional files to bundle with the app |

### Connecting to pipeline output with RunOutput

The `RunOutput` parameter connects the app to the batch pipeline's output:

```python
Parameter(
    name="reports",
    value=RunOutput(
        task_name="driver.report_batch_pipeline",
        type="directory",
    ),
    download=True,
    env_var="REPORTS_PATH",
)
```

This configuration:
1. **Finds the latest run** of `report_batch_pipeline` in the `driver` environment
2. **Downloads the output** to local storage (`download=True`)
3. **Sets an environment variable** with the path (`REPORTS_PATH`)

The app can then scan this directory for all generated reports.

## The Streamlit application

The app loads and displays all generated reports from the batch pipeline:

```python
def load_report_from_dir(report_dir: str) -> dict | None:
    """Load a single report from a directory."""
    if not os.path.isdir(report_dir):
        return None

    report = {"path": report_dir, "name": os.path.basename(report_dir)}

    md_path = os.path.join(report_dir, "report.md")
    if os.path.exists(md_path):
        with open(md_path) as f:
            report["markdown"] = f.read()

    html_path = os.path.join(report_dir, "report.html")
    if os.path.exists(html_path):
        with open(html_path) as f:
            report["html"] = f.read()

    summary_path = os.path.join(report_dir, "summary.txt")
    if os.path.exists(summary_path):
        with open(summary_path) as f:
            report["summary"] = f.read()

    # Only return if we found at least markdown content
    return report if "markdown" in report else None

def load_all_reports() -> list[dict]:
    """Load all reports from the batch pipeline output."""
    reports_path = os.environ.get("REPORTS_PATH")
    if not reports_path or not os.path.exists(reports_path):
        return []

    reports = []

    # Check if this is a single report directory (has report.md directly)
    if os.path.exists(os.path.join(reports_path, "report.md")):
        report = load_report_from_dir(reports_path)
        if report:
            report["name"] = "Report"
            reports.append(report)
    else:
        # Batch output: scan subdirectories for reports
        for entry in sorted(os.listdir(reports_path)):
            entry_path = os.path.join(reports_path, entry)
            report = load_report_from_dir(entry_path)
            if report:
                reports.append(report)

    return reports
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/advanced-project/app.py*

### Displaying multiple reports

The app provides a sidebar for selecting between reports when multiple are available:

```python
reports = load_all_reports()

if reports:
    # Sidebar for report selection if multiple reports
    if len(reports) > 1:
        st.sidebar.header("Select Report")
        report_names = [f"Report {i+1}: {r['name']}" for i, r in enumerate(reports)]
        selected_idx = st.sidebar.selectbox(
            "Choose a report to view:",
            range(len(reports)),
            format_func=lambda i: report_names[i],
        )
        selected_report = reports[selected_idx]
        st.sidebar.markdown(f"**Viewing {len(reports)} reports**")
    else:
        selected_report = reports[0]

    st.header(f"Generated Report: {selected_report['name']}")

    # Summary section
    if "summary" in selected_report:
        with st.expander("Executive Summary", expanded=True):
            st.write(selected_report["summary"])

    # Tabbed view for different formats
    tab_md, tab_html = st.tabs(["Markdown", "HTML Preview"])

    with tab_md:
        st.markdown(selected_report.get("markdown", ""))

    with tab_html:
        if "html" in selected_report:
            st.components.v1.html(selected_report["html"], height=600, scrolling=True)

    # Download options
    st.subheader("Download")
    col1, col2, col3 = st.columns(3)

    with col1:
        if "markdown" in selected_report:
            st.download_button(
                label="Download Markdown",
                data=selected_report["markdown"],
                file_name="report.md",
                mime="text/markdown",
            )

    with col2:
        if "html" in selected_report:
            st.download_button(
                label="Download HTML",
                data=selected_report["html"],
                file_name="report.html",
                mime="text/html",
            )

    with col3:
        if "summary" in selected_report:
            st.download_button(
                label="Download Summary",
                data=selected_report["summary"],
                file_name="summary.txt",
                mime="text/plain",
            )

else:
    st.info("No reports generated yet. Run the batch pipeline to create reports.")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/advanced-project/app.py*

Features:
- **Report selector**: Sidebar navigation when multiple reports exist
- **Executive summary**: Expandable section with key takeaways
- **Tabbed views**: Switch between Markdown and HTML preview
- **Download buttons**: Export in any format

### Generation instructions

The app includes instructions for generating new reports:

```python
st.divider()
st.header("Generate New Reports")
st.write("""
To generate reports, run the batch pipeline:

```bash
uv run generate.py
```

This generates reports for multiple topics in parallel, demonstrating
how ReusePolicy efficiently handles many concurrent LLM calls.
""")

# Show pipeline parameters info
with st.expander("Pipeline Parameters"):
    st.markdown("""
    **Available parameters:**

    | Parameter | Default | Description |
    |-----------|---------|-------------|
    | `topics` | (required) | List of topics to write about |
    | `max_iterations` | 3 | Maximum refinement cycles per topic |
    | `quality_threshold` | 8 | Minimum score (1-10) to accept |

    **Example:**
    CODE5
    """)
CODE6python
if __name__ == "__main__":
    flyte.init_from_config()

    # Deploy the report generator app
    print("Deploying report generator app...")
    deployment = flyte.serve(env)
    print(f"App deployed at: {deployment.url}")
CODE7bash
uv run serve.py
CODE8bash
   uv run generate.py
   CODE9bash
   uv run serve.py
   ```

3. **Access the app** at the provided URL and browse all generated reports

The app automatically picks up the latest pipeline run, so you can generate
new batches and always see the most recent results.

## Automatic updates with RunOutput

The `RunOutput` connection is evaluated at app startup. Each time the app
restarts or redeploys, it fetches the latest batch pipeline output.

For real-time updates without redeployment, you could:
1. Poll for new runs using the Flyte API
2. Implement a webhook that triggers app refresh
3. Use a database to track run status

## Complete example structure

Here's the full project structure:

CODE10

## Running the complete example

1. **Set up the secret**:
   CODE11

2. **Run the pipeline**:
   CODE12

3. **Deploy the app**:
   CODE13

4. **Open the app URL** and view your generated report

## Summary

This example demonstrated:

| Feature | What it does |
|---------|--------------|
| `ReusePolicy` | Keeps containers warm for high-throughput batch processing |
| `@flyte.trace` | Checkpoints LLM calls for recovery and observability |
| `RetryStrategy` | Handles transient API failures gracefully |
| `flyte.group` | Organizes parallel batches and iterations in the UI |
| `asyncio.gather` | Fans out to process multiple topics concurrently |
| Pydantic models | Structured LLM outputs |
| `AppEnvironment` | Deploys interactive Streamlit apps |
| `RunOutput` | Connects apps to pipeline outputs |

These patterns form the foundation for building production-grade AI workflows
that are resilient, observable, and cost-efficient at scale.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/flyte-2 ===

# From Flyte 1 to 2

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

Flyte 2 represents a fundamental shift in how Flyte workflows are written and executed.

## Pure Python execution

Write workflows in pure Python, enabling a more natural development experience and removing the constraints of a
domain-specific language (DSL).

### Sync Python

```
import flyte

env = flyte.TaskEnvironment("sync_example_env")

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

@env.task
def main(name: str) -> str:
    for i in range(10):
        hello_world(name)
    return "Done"

if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(main, name="World")
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/flyte-2/sync_example.py*

### Async Python

```
import asyncio
import flyte

env = flyte.TaskEnvironment("async_example_env")

@env.task
async def hello_world(name: str) -> str:
    return f"Hello, {name}!"

@env.task
async def main(name: str) -> str:
    results = []
    for i in range(10):
        results.append(hello_world(name))
    await asyncio.gather(*results)
    return "Done"

if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(main, name="World")
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/flyte-2/async_example.py*

As you can see in the hello world example, workflows can be constructed at runtime, allowing for more flexible and
adaptive behavior. Flyte 2 supports:

- Python's asynchronous programming model to express parallelism.
- Python's native error handling with `try-except` to overridden configurations, like resource requests.
- Predefined static workflows when compile-time safety is critical.

## Simplified API

The new API is more intuitive, with fewer abstractions to learn and a focus on simplicity.

| Use case                      | Flyte 1                     | Flyte 2                                 |
| ----------------------------- | --------------------------- | --------------------------------------- |
| Environment management        | `N/A`                       | `TaskEnvironment`                       |
| Perform basic computation     | `@task`                     | `@env.task`                             |
| Combine tasks into a workflow | `@workflow`                 | `@env.task`                             |
| Create dynamic workflows      | `@dynamic`                  | `@env.task`                             |
| Fanout parallelism            | `flytekit.map`              | Python `for` loop with `asyncio.gather` |
| Conditional execution         | `flytekit.conditional`      | Python `if-elif-else`                   |
| Catching workflow failures    | `@workflow(on_failure=...)` | Python `try-except`                     |

There is no `@workflow` decorator. Instead, "workflows" are authored through a pattern of tasks calling tasks.
Tasks are defined within environments, which encapsulate the context and resources needed for execution.

## Fine-grained reproducibility and recoverability

As in Flyte 1, Flyte 2 supports caching at the task level (via `@env.task(cache=...)`), but it further enables recovery at the finer-grained, sub-task level through a feature called tracing (via `@flyte.trace`).

```
import flyte

env = flyte.TaskEnvironment(name="trace_example_env")

@flyte.trace
async def call_llm(prompt: str) -> str:
    return "Initial response from LLM"

@env.task
async def finalize_output(output: str) -> str:
    return "Finalized output"

@env.task(cache=flyte.Cache(behavior="auto"))
async def main(prompt: str) -> str:
    output = await call_llm(prompt)
    output = await finalize_output(output)
    return output

if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(main, prompt="Prompt to LLM")
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/flyte-2/trace.py*

Here `call_llm` runs in the same container as `main` and acts as an automated checkpoint with full observability in the UI.
If the task fails due to a system error (e.g., node preemption or infrastructure failure), Flyte can recover and replay from the
last successful trace rather than restarting from the beginning.

Note that tracing is distinct from caching: traces are recovered only if there is a system failure
whereas with cached outputs are persisted for reuse across separate runs.

## Improved remote functionality

Flyte 2 provides full management of the workflow lifecycle through a standardized API through the CLI and the Python SDK.

| Use case      | CLI                | Python SDK          |
| ------------- | ------------------ | ------------------- |
| Run a task    | `flyte run ...`    | `flyte.run(...)`    |
| Deploy a task | `flyte deploy ...` | `flyte.deploy(...)` |

You can also fetch and run remote (previously deployed) tasks within the course of a running workflow.

```
import flyte
from flyte import remote

env_1 = flyte.TaskEnvironment(name="env_1")
env_2 = flyte.TaskEnvironment(name="env_2")
env_1.add_dependency(env_2)

@env_2.task
async def remote_task(x: str) -> str:
    return "Remote task processed: " + x

@env_1.task
async def main() -> str:
    remote_task_ref = remote.Task.get("env_2.remote_task", auto_version="latest")
    r = await remote_task_ref(x="Hello")
    return "main called remote and recieved: " + r

if __name__ == "__main__":
    flyte.init_from_config()
    d = flyte.deploy(env_1)
    print(d[0].summary_repr())
    r = flyte.run(main)
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/flyte-2/remote.py*

## Native Notebook support

Author and run workflows and fetch workflow metadata (I/O and logs) directly from Jupyter notebooks.

![Native Notebook](https://raw.githubusercontent.com/unionai/unionai-docs-static/main/images/user-guide/notebook.png)

## High performance engine

When running on a Union.ai backend, Flyte 2 enables you to schedule tasks in milliseconds with reusable containers, which massively increases the throughput of containerized tasks.

```
# Currently required to enable resuable containers
reusable_image = flyte.Image.from_debian_base().with_pip_packages("unionai-reuse>=0.1.10")

env = flyte.TaskEnvironment(
    name="reusable-env",
    resources=flyte.Resources(memory="1Gi", cpu="500m"),
    reusable=flyte.ReusePolicy(replicas=2, concurrency=1), # Specify reuse policy
    image=reusable_image  # Use the container image augmented with the unionai-reuse library.
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/flyte-2/reuse.py*

Coupled with multi-cluster, multi-cloud, and multi-region support, Flyte 2 on Union.ai can scale to handle even the most demanding workflows.

## Enhanced UI

The Union.ai backend also offers a new UI with a streamlined and user-friendly experience for authoring and managing workflows.

![New UI](https://raw.githubusercontent.com/unionai/unionai-docs-static/main/images/user-guide/v2ui.png)

This UI improves the visualization of workflow execution and monitoring, simplifying access to logs, metadata, and other important information.

## Subpages
- **From Flyte 1 to 2 > Pure Python**
- **From Flyte 1 to 2 > Asynchronous model**
- **From Flyte 1 to 2 > Migration from Flyte 1 to Flyte 2**
- **From Flyte 1 to 2 > Considerations**


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/flyte-2/pure-python ===

# Pure Python

Flyte 2 introduces a new way of writing workflows that is based on pure Python, removing the constraints of a domain-specific language (DSL) and enabling full use of Python's capabilities.

## From `@workflow` DSL to pure Python

| Flyte 1 | Flyte 2 |
| --- | --- |
| `@workflow`-decorated functions are constrained to a subset of Python for defining a static directed acyclic graph (DAG) of tasks. | **No more `@workflow` decorator**: Everything is a `@env.task`, so your top-level “workflow” is simply a task that calls other tasks. |
| `@task`-decorated functions could leverage the full power of Python, but only within individual container executions. | `@env.task`s can call other `@env.task`s and be used to construct workflows with dynamic structures using loops, conditionals, try/except, and any Python construct anywhere. |
| Workflows were compiled into static DAGs at registration time, with tasks as the nodes and the DSL defining the structure. | Workflows are simply tasks that call other tasks. Compile-time safety will be available in the future as `compiled_task`. |

### Flyte 1

```python
import flytekit

image = flytekit.ImageSpec(
    name="hello-world-image",
    packages=["requests"],
)

@flytekit.task(container_image=image)
def mean(data: list[float]) -> float:
    return sum(list) / len(list)

@flytekit.workflow
def main(data: list[float]) -> float:
    output = mean(data)

    # ❌ performing trivial operations in a workflow is not allowed
    # output = output / 100

    # ❌ if/else is not allowed
    # if output < 0:
    #     raise ValueError("Output cannot be negative")

    return output
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/flyte-2/pure-python/flyte_1.py*

### Flyte 2

```
import flyte

env = flyte.TaskEnvironment(
    "hello_world",
    image=flyte.Image.from_debian_base().with_pip_packages("requests"),
)

@env.task
def mean(data: list[float]) -> float:
    return sum(data) / len(data)

@env.task
def main(data: list[float]) -> float:
    output = mean(data)

    # ✅ performing trivial operations in a workflow is allowed
    output = output / 100

    # ✅ if/else is allowed
    if output < 0:
        raise ValueError("Output cannot be negative")

    return output
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/flyte-2/pure-python/flyte_2.py*

These fundamental changes bring several transformative benefits:

- **Flexibility**: Harness the complete Python language for workflow definition, including all control flow constructs previously forbidden in workflows.
- **Dynamic workflows**: Create workflows that adapt to runtime conditions, handle variable data structures, and make decisions based on intermediate results.
- **Natural error handling**: Use standard Python `try`/`except` patterns throughout your workflows, making them more robust and easier to debug.
- **Intuitive composability**: Build complex workflows by naturally composing Python functions, following familiar patterns that any Python developer understands.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/flyte-2/async ===

# Asynchronous model

## Why we need an async model

The shift to an asynchronous model in Flyte 2 is driven by the need for more efficient and flexible workflow execution.

We believe, in particular, that with the rise of the agentic AI pattern, asynchronous programming has become an essential part of AI/ML engineering and data science toolkit.

With Flyte 2, the entire framework is now written with async constructs, allowing for:

- Seamless overlapping of I/O and independent external operations.
- Composing multiple tasks and external tool invocations within the same Python process.
- Native support of streaming operations for data, observability and downstream invocations.

It is also a natural fit for the expression parallelism in workflows.

### Understanding concurrency vs. parallelism

**Concurrency** means running multiple tasks at once. This can be achieved by interleaving execution on a single thread (switching between tasks when one is waiting) or by true **parallelism**—executing tasks truly simultaneously across multiple cores or machines. Parallelism is a form of concurrency, but concurrency doesn't require parallelism.

### Python's async evolution

Python's asynchronous programming capabilities have evolved significantly:

- **The GIL challenge**: Python's Global Interpreter Lock (GIL) traditionally prevented true parallelism for CPU-bound tasks, limiting threading effectiveness to I/O-bound operations.
- **Traditional solutions**:
  - `multiprocessing`: Created separate processes to sidestep the GIL, effective but resource-intensive
  - `threading`: Useful for I/O-bound tasks where the GIL could be released during external operations
- **The async revolution**: The `asyncio` library introduced cooperative multitasking within a single thread, using an event loop to manage multiple tasks efficiently.

### Parallelism in Flyte 1 vs Flyte 2

| | Flyte 1 | Flyte 2 |
| --- | --- | --- |
| Parallelism | The workflow DSL automatically parallelized tasks that weren't dependent on each other. The `map` operator allowed running a task multiple times in parallel with different inputs. | Leverages Python's `asyncio` as the primary mechanism for expressing parallelism, but with a crucial difference: **the Flyte orchestrator acts as the event loop**, managing task execution across distributed infrastructure. |

### Core async concepts

- **`async def`**: Declares a function as a coroutine. When called, it returns a coroutine object managed by the event loop rather than executing immediately.
- **`await`**: Pauses coroutine execution and passes control back to the event loop.
  In standard Python, this enables other tasks to run while waiting for I/O operations.
  In Flyte 2, it signals where tasks can be executed in parallel.
- **`asyncio.gather`**: The primary tool for concurrent execution.
  In standard Python, it schedules multiple awaitable objects to run concurrently within a single event loop.
  In Flyte 2, it signals to the orchestrator that these tasks can be distributed across separate compute resources.

#### A practical example

Consider this pattern for parallel data processing:

```
import asyncio
import flyte

env = flyte.TaskEnvironment("data_pipeline")

@env.task
async def process_chunk(chunk_id: int, data: str) -> str:
    # This could be any computational work - CPU or I/O bound
    await asyncio.sleep(1)  # Simulating work
    return f"Processed chunk {chunk_id}: {data}"

@env.task
async def parallel_pipeline(data_chunks: list[str]) -> list[str]:
    # Create coroutines for all chunks
    tasks = []
    for i, chunk in enumerate(data_chunks):
        tasks.append(process_chunk(i, chunk))

    # Execute all chunks in parallel
    results = await asyncio.gather(*tasks)
    return results
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/flyte-2/async/async.py*

In standard Python, this would provide concurrency benefits primarily for I/O-bound operations.
In Flyte 2, the orchestrator schedules each `process_chunk` task on separate Kubernetes pods or configured plugins, achieving true parallelism for any type of work.

### True parallelism for all workloads

This is where Flyte 2's approach becomes revolutionary: **async syntax is not just for I/O-bound operations**.
The `async`/`await` syntax becomes a powerful way to declare your workflow's parallel structure for any type of computation.

When Flyte's orchestrator encounters `await asyncio.gather(...)`, it understands that these tasks are independent and can be executed simultaneously across different compute resources.
This means you achieve true parallelism for:

- **CPU-bound computations**: Heavy mathematical operations, model training, data transformations
- **I/O-bound operations**: Database queries, API calls, file operations
- **Mixed workloads**: Any combination of computational and I/O tasks

The Flyte platform handles the complex orchestration while you express parallelism using intuitive `async` syntax.

## Calling sync tasks from async tasks

### Synchronous task support

Since many existing codebases use synchronous functions, Flyte 2 provides synchronous support. Under the hood, Flyte automatically "asyncifies" synchronous functions, wrapping them to participate seamlessly in the async execution model.
You don't need to rewrite existing code, just leverage the `.aio()` method when calling sync tasks from async contexts:

```
@env.task
def legacy_computation(x: int) -> int:
    # Existing synchronous function works unchanged
    return x * x + 2 * x + 1

@env.task
async def modern_workflow(numbers: list[int]) -> list[int]:
    # Call sync tasks from async context using .aio()
    tasks = []
    for num in numbers:
        tasks.append(legacy_computation.aio(num))

    results = await asyncio.gather(*tasks)
    return results
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/flyte-2/async/async.py*

### The `flyte.map` function: Familiar patterns

For scenarios that previously used Flyte 1's `map` operation, Flyte 2 provides `flyte.map` as a direct replacement.
The new `flyte.map` can be used either in synchronous or asynchronous contexts, allowing you to express parallelism without changing your existing patterns.

### Sync Map

```
@env.task
def sync_map_example(n: int) -> list[str]:
    # Synchronous version for easier migration
    results = []
    for result in flyte.map(process_item, range(n)):
        if isinstance(result, Exception):
            raise result
        results.append(result)
    return results
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/flyte-2/async/async.py*

### Async Map

```
@env.task
async def async_map_example(n: int) -> list[str]:
    # Async version using flyte.map - exact pattern from SDK examples
    results = []
    async for result in flyte.map.aio(process_item, range(n), return_exceptions=True):
        if isinstance(result, Exception):
            raise result
        results.append(result)
    return results
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/flyte-2/async/async.py*

The `flyte.map` function provides:

- **Dual interfaces**: `flyte.map.aio()` for async contexts, `flyte.map()` for sync contexts.
- **Built-in error handling**: `return_exceptions` parameter for graceful failure handling. This matches the `asyncio.gather` interface,
  allowing you to decide how to handle errors.
  If you are coming from Flyte 1, it allows you to replace `min_success_ratio` in a more flexible way.
- **Automatic UI grouping**: Creates logical groups for better workflow visualization.
- **Concurrency control**: Optional limits for resource management.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/flyte-2/migration ===

# Migration from Flyte 1 to Flyte 2

> **📝 Note**
>
> For comprehensive migration reference with detailed API mappings, parameter tables, and complete examples, see [Migration from Flyte 1](../../api-reference/migration/_index) in the Reference section.
> An LLM-optimized bundle of the full migration reference is available at [`section.md`](../../api-reference/migration/section.md).

You can migrate from Flyte 1 to Flyte 2 by following the steps below:

### 1. Move task configuration to a `TaskEnvironment` object

Instead of configuring the image, hardware resources, and so forth, directly in the task decorator. You configure it in `TaskEnvironment` object. For example:

```python
env = flyte.TaskEnvironment(name="my_task_env")
```

### 2. Replace workflow decorators

Then, you replace the `@workflow` and `@task` decorators with `@env.task` decorators.

### Flyte 1

Here's a simple hello world example with fanout.

```python
import flytekit

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

@flytekit.workflow
def main(names: list[str]) -> list[str]:
    return flytekit.map(hello_world)(names)
```

### Flyte 2 Sync

Change all the decorators to `@env.task` and swap out `flytekit.map` with `flyte.map`.
Notice that `flyte.map` is a drop-in replacement for Python's built-in `map` function.

```diff
-@flytekit.task
+@env.task
def hello_world(name: str) -> str:
    return f"Hello, {name}!"

-@flytekit.workflow
+@env.task
def main(names: list[str]) -> list[str]:
    return flyte.map(hello_world, names)
```

> **📝 Note**
>
> Note that the reason our task decorator uses `env` is simply because that is the variable to which we assigned the `TaskEnvironment` above.

### Flyte 2 Async

To take advantage of full concurrency (not just parallelism), use Python async
syntax and the `asyncio` standard library to implement fa-out.

```diff
+import asyncio

@env.task
-def hello_world(name: str) -> str:
+async def hello_world(name: str) -> str:
    return f"Hello, {name}!"

@env.task
-def main(names: list[str]) -> list[str]:
+async def main(names: list[str]) -> list[str]:
-    return flyte.map(hello_world, names)
+    return await asyncio.gather(*[hello_world(name) for name in names])
```

> **📝 Note**
>
> To use Python async syntax, you need to:
> - Use `asyncio.gather()` or `flyte.map()` for parallel execution
> - Add `async`/`await` keywords where you want parallelism
> - Keep existing sync task functions unchanged
>
> Learn more about about the benefits of async in the [Asynchronous Model](./async) guide.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/flyte-2/considerations ===

# Considerations

Flyte 2 represents a substantial change from Flyte 1.
Each Python-based task action has the ability to act as its own engine, kicking off sub-actions, and assembling the outputs, passing them to yet other sub-actions and such.

While this model of execution comes with an enormous amount of flexibility, that flexibility does warrant some caveats to keep in mind when authoring your tasks.

## Non-deterministic behavior

When a task launches another task, a new Action ID is determined.
This ID is a hash of the inputs to the task, the task definition itself, along with some other information.
The fact that this ID is consistently hashed is important when it comes to things like recovery and replay.

For example, assume you have the following tasks

```python
@env.task
async def t1():
    val = get_int_input()
    await t2(int=val)

@env.task
async def t2(val: int): ...
```

If you run `t1`, and it launches the downstream `t2` task, and then the pod executing `t1` fails, when Flyte restarts `t1` it will automatically detect that `t2` is still running and will just use that.
If `t2` ends up finishing in the interim, those results would just be used.

However, if you introduce non-determinism into the picture, then that guarantee is no longer there.
To give a contrived example:

```python
@env.task
async def t1():
    val = get_int_input()
    now = datetime.now()

    if now.second % 2 == 0:
        await t2(int=val)
    else:
        await t3(int=val)
```

Here, depending on what time it is, either `t2` or `t3` may end up running.
In the earlier scenario, if `t1` crashes unexpectedly, and Flyte retries the execution, a different downstream task may get kicked off instead.

### Dealing with non-determinism

As a developer, the best way to manage non-deterministic behavior (if it is unavoidable) is to be able to observe it and see exactly what is happening in your code. Flyte 2 provides precisely the tool needed to enable this: Traces.

With this feature you decorate the sub-task functions in your code with `@trace`, enabling checkpointing, reproducibility and recovery at a fine-grained level. See [Traces](../task-programming/traces) for more details.

## Type safety

In Flyte 1, the top-level workflow was defined by a Python-like DSL that was compiled into a static DAG composed of tasks, each of which was, internally, defined in real Python.
The system was able to guarantee type safety across task boundaries because the task definitions were static and the inputs and outputs were defined in a way that Flytekit could validate them.

In Flyte 2, the top-level workflow is defined by Python code that runs at runtime (unless using a compiled task).
This means that the system can no longer guarantee type safety at the workflow level.

Happily, the Python ecosystem has evolved considerably since Flyte 1, and Python type hints are now a standard way to define types.

Consequently, in Flyte 2, developers should use Python type hints and type checkers like `mypy` to ensure type safety at all levels, including the top-most task (i.e., the "workflow" level).

## No global state

A core principle of Flyte 2 (that is also shared with Flyte 1) is that you should not try to maintain global state across your workflow.
It will not be translated across tasks containers,

In a single process Python program, global variables are available across functions.
In the distributed execution model of Flyte, each task runs in its own container, and each container is isolated from the others.

If there is some state that needs to be preserved, it must be reconstructable through repeated deterministic execution.

## Driver pod requirements

Tasks don't have to kick off downstream tasks of course and may themselves represent a leaf level atomic unit of compute.
However, when tasks do run other tasks, and more so if they assemble the outputs of those other tasks, then that parent task becomes a driver
pod of sorts.
In Flyte 1, this assembling of intermediate outputs was done by Flyte Propeller.
In 2, it's done by the parent task.

This means that the pod running your parent task must be appropriately sized, and should ideally not be CPU-bound, otherwise it slow down downstream evaluation and kickoff of tasks.

For example, if you had this also scenario,

```python
@env.task
async def t_main():
    await t1()
    local_cpu_intensive_function()
    await t2()
```
The pod running `t_main` will hang in between tasks `t1` and `t2`. Your parent tasks should ideally focus only on orchestration.

## OOM risk from materialized I/O

Something maybe more nuanced to keep in mind is that if you're not using the soon-to-be-released ref mode, outputs are actually
materialized. That is, if you have the following scenario,

```python
@env.task
async def produce_1gb_list() -> List[float]: ...

@env.task
async def t1():
    list_floats = produce_1gb_list()
    t2(floats=list_floats)
```

The pod running `t1` needs to have memory to handle that 1 GB of floats. Those numbers will be materialized in that pod's memory.
This can lead to out of memory issues.

Note that `flyte.io.File`, `flyte.io.Dir` and `flyte.io.DataFrame` will not suffer from this because while those are materialized, they're only materialized as pointers to offloaded data, so their memory footprint is much lower.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-configuration ===

# Configure tasks

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

As we saw in **Quickstart**, you can run any Python function as a task in Flyte just by decorating it with `@env.task`.

This allows you to run your Python code in a distributed manner, with each function running in its own container.
Flyte manages the spinning up of the containers, the execution of the code, and the passing of data between the tasks.

The simplest possible case is a `TaskEnvironment` with only a `name` parameter, and an `env.task` decorator, with no parameters:

```
env = flyte.TaskEnvironment(name="my_env")

@env.task
async def my_task(name:str) -> str:
    return f"Hello {name}!"
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/task_config.py*

> [!NOTE]
> Notice how the `TaskEnvironment` is assigned to the variable `env` and then that variable is
> used in the `@env.task`. This is what connects the `TaskEnvironment` to the task definition.
>
> In the following we will often use `@env.task` generically to refer to the decorator,
> but it is important to remember that it is actually a decorator attached to a specific
> `TaskEnvironment` object, and the `env` part can be any variable name you like.

This will run your task in the default container environment with default settings.

But, of course, one of the key advantages of Flyte is the ability to control the software environment, hardware environment, and other execution parameters for each task, right in your Python code.
In this section we will explore the various configuration options available for tasks in Flyte.

## Task configuration levels

Task configuration is done at three levels. From most general to most specific, they are:

* The `TaskEnvironment` level: setting parameters when defining the `TaskEnvironment` object.
* The `@env.task` decorator level: Setting parameters in the `@env.task` decorator when defining a task function.
* The task invocation level: Using the `task.override()` method when invoking task execution.

Each level has its own set of parameters, and some parameters are shared across levels.
For shared parameters, the more specific level will override the more general one.

### Example

Here is an example of how these levels work together, showing each level with all available parameters:

```
# Level 1: TaskEnvironment - Base configuration
env_2 = flyte.TaskEnvironment(
    name="data_processing_env",
    image=flyte.Image.from_debian_base(),
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    env_vars={"MY_VAR": "value"},
    # secrets=flyte.Secret(key="openapi_key", as_env_var="MY_API_KEY"),
    cache="disable",
    # pod_template=my_pod_template,
    # reusable=flyte.ReusePolicy(replicas=2, idle_ttl=300),
    depends_on=[another_env],
    description="Data processing task environment",
    # plugin_config=my_plugin_config
)

# Level 2: Decorator - Override some environment settings
@env_2.task(
    short_name="process",
    # secrets=flyte.Secret(key="openapi_key", as_env_var="MY_API_KEY_2"),
    cache="auto",
    # pod_template=my_pod_template,
    report=True,
    max_inline_io_bytes=100 * 1024,
    retries=3,
    timeout=60,
    docs="This task processes data and generates a report."
)
async def process_data(data_path: str) -> str:
    return f"Processed {data_path}"

@env_2.task
async def invoke_process_data() -> str:
    result = await process_data.override(
        resources=flyte.Resources(cpu=4, memory="2Gi"),
        env_vars={"MY_VAR": "new_value"},
        # secrets=flyte.Secret(key="openapi_key", as_env_var="MY_API_KEY_3"),
        cache="auto",
        max_inline_io_bytes=100 * 1024,
        retries=3,
        timeout=60
    )("input.csv")
    return result
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/task_config.py*

### Parameter interaction

Here is an overview of all task configuration parameters available at each level and how they interact:

| Parameter               | `TaskEnvironment`  | `@env.task` decorator      | `override` on task invocation |
|-------------------------|--------------------|----------------------------|-------------------------------|
| **Configure tasks > Additional task settings**                           | ✅ Yes (required)  | ❌ No                      | ❌ No                         |
| **Configure tasks > Additional task settings**                     | ❌ No              | ✅ Yes                     | ✅ Yes                        |
| **Configure tasks > Container images**                                  | ✅ Yes             | ❌ No                      | ❌ No                         |
| **Configure tasks > Resources**                                     | ✅ Yes             | ❌ No                      | ✅ Yes (if not `reusable`)    |
| **Configure tasks > Additional task settings > Environment variables** | ✅ Yes             | ❌ No                      | ✅ Yes (if not `reusable`)    |
| **Configure tasks > Secrets**                                         | ✅ Yes             | ❌ No                      | ✅ Yes (if not `reusable`)    |
| **Configure tasks > Caching**                                           | ✅ Yes             | ✅ Yes                     | ✅ Yes                        |
| **Configure tasks > Pod templates**                              | ✅ Yes             | ✅ Yes                     | ✅ Yes                        |
| **Configure tasks > Reusable containers**                            | ✅ Yes             | ❌ No                      | ✅ Yes                        |
| **Configure tasks > Multiple environments**                        | ✅ Yes             | ❌ No                      | ❌ No                         |
| **Configure tasks > Additional task settings**                    | ✅ Yes             | ❌ No                      | ❌ No                         |
| **Configure tasks > Task plugins**                              | ✅ Yes             | ❌ No                      | ❌ No                         |
| **Configure tasks > Additional task settings > Naming and metadata > `report`**                  | ❌ No              | ✅ Yes                     | ❌ No                         |
| **Configure tasks > Additional task settings > Inline I/O threshold** | ❌ No    | ✅ Yes                     | ✅ Yes                        |
| **Configure tasks > Retries and timeouts**                            | ❌ No              | ✅ Yes                     | ✅ Yes                        |
| **Configure tasks > Retries and timeouts**                            | ❌ No              | ✅ Yes                     | ✅ Yes                        |
| **Configure tasks > Triggers**                                       | ❌ No              | ✅ Yes                     | ❌ No                         |
| **Configure tasks > Additional task settings > Naming and metadata > `links`**                    | ❌ No              | ✅ Yes                     | ✅ Yes                        |
| **Configure tasks > Interruptible tasks and queues**            | ✅ Yes             | ✅ Yes                     | ✅ Yes                        |
| **Configure tasks > Interruptible tasks and queues**                    | ✅ Yes             | ✅ Yes                     | ✅ Yes                        |
| **Configure tasks > Additional task settings > Naming and metadata > `docs`**                      | ❌ No              | ✅ Yes                     | ❌ No                         |

## Task configuration parameters

Each parameter is documented in detail on its dedicated page or in the API reference. For full type signatures and constraints, see the **Flyte SDK > Packages > flyte > TaskEnvironment**.

| Parameter | Details |
|-----------|---------|
| **name**, **short_name**, **description**, **docs** | **Configure tasks > Additional task settings** |
| **image** | **Configure tasks > Container images** &bull; **Flyte SDK > Packages > flyte > Image** |
| **resources** | **Configure tasks > Resources** &bull; **Flyte SDK > Packages > flyte > Resources** |
| **env_vars** | **Configure tasks > Additional task settings > Environment variables** |
| **secrets** | **Configure tasks > Secrets** &bull; **Flyte SDK > Packages > flyte > Secret** |
| **cache** | **Configure tasks > Caching** &bull; **Flyte SDK > Packages > flyte > Cache** |
| **pod_template** | **Configure tasks > Pod templates** &bull; **Flyte SDK > Packages > flyte > PodTemplate** |
| **reusable** | **Configure tasks > Reusable containers** &bull; **Flyte SDK > Packages > flyte > ReusePolicy** |
| **depends_on** | **Configure tasks > Multiple environments** |
| **plugin_config** | **Configure tasks > Task plugins** |
| **report** | **Configure tasks > Additional task settings > Naming and metadata > `report`** |
| **max_inline_io_bytes** | **Configure tasks > Additional task settings > Inline I/O threshold** |
| **retries**, **timeout** | **Configure tasks > Retries and timeouts** &bull; **Flyte SDK > Packages > flyte > RetryStrategy**, **Flyte SDK > Packages > flyte > Timeout** API refs |
| **triggers** | **Configure tasks > Triggers** &bull; **Flyte SDK > Packages > flyte > Trigger** |
| **links** | **Configure tasks > Additional task settings > Naming and metadata > `links`** |
| **interruptible**, **queue** | **Configure tasks > Interruptible tasks and queues** |

## Subpages
- **Configure tasks > Container images**
- **Configure tasks > Resources**
- **Configure tasks > Secrets**
- **Configure tasks > Caching**
- **Configure tasks > Reusable containers**
- **Configure tasks > Pod templates**
- **Configure tasks > Multiple environments**
- **Configure tasks > Retries and timeouts**
- **Configure tasks > Triggers**
- **Configure tasks > Interruptible tasks and queues**
- **Configure tasks > Task plugins**
- **Configure tasks > Additional task settings**


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-configuration/container-images ===

# Container images

The `image` parameter of the [`TaskEnvironment`](../../api-reference/flyte-sdk/packages/flyte/taskenvironment) is used to specify a container image.
Every task defined using that `TaskEnvironment` will run in a container based on that image.

If a `TaskEnvironment` does not specify an `image`, it will use the default Flyte image ([`ghcr.io/flyteorg/flyte:py{python-version}-v{flyte_version}`](https://github.com/orgs/flyteorg/packages/container/package/flyte)).

## Specifying your own image directly

You can directly reference an image by URL in the `image` parameter, like this:

```python
env = flyte.TaskEnvironment(
    name="my_task_env",
    image="docker.io/myorg/myimage:mytag"
)
```

This works well if you have a pre-built image available in a public registry like Docker Hub or in a private registry that your Union/Flyte instance can access.

## Specifying your own image with the `flyte.Image` object

You can also construct an image programmatically using the `flyte.Image` object.

The `flyte.Image` object provides a fluent interface for building container images: start with a `from_*` base constructor, then customize with `with_*` methods. Each method returns a new immutable `Image`.

For a complete list of all available methods and their parameters, see the [`Image` API reference](../../api-reference/flyte-sdk/packages/flyte/image).

Here are some examples of the most common patterns for building images with `flyte.Image`.

## Example: Defining a custom image with `Image.from_debian_base`

The `[[Image.from_debian_base()]]` provides the default Flyte image as the base.
This image is itself based on the official Python Docker image (specifically `python:{version}-slim-bookworm`) with the addition of the Flyte SDK pre-installed.
Starting there, you can layer additional features onto your image.
For example:

```python
import flyte
import numpy as np

# Define the task environment
env = flyte.TaskEnvironment(
    name="my_env",
    image = (
        flyte.Image.from_debian_base(
            name="my-image",
            python_version=(3, 13)
            # registry="registry.example.com/my-org" # Only needed for local builds
        )
        .with_apt_packages("libopenblas-dev")
        .with_pip_packages("numpy")
        .with_env_vars({"OMP_NUM_THREADS": "4"})
    )
)

@env.task
def main(x_list: list[int]) -> float:
    arr = np.array(x_list)
    return float(np.mean(arr))

if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(main, x_list=list(range(10)))
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/container-images/from_debian_base.py*

> [!NOTE]
> The `registry` parameter is only needed if you are building the image locally. It is not required when using the Union backend `ImageBuilder`.
> See **Configure tasks > Container images > Image building** for more details.

> [!NOTE]
> Images built with `[[Image.from_debian_base()]]` do not include CA certificates by default, which can cause TLS
> validation errors and block access to HTTPS-based storage such as Amazon S3. Libraries like Polars (e.g., `polars.scan_parquet()`) are particularly affected.
> **Solution:** Add `"ca-certificates"` using `.with_apt_packages()` in your image definition.

## Example: Defining an image based on uv script metadata

Another common technique for defining an image is to use [`uv` inline script metadata](https://docs.astral.sh/uv/guides/scripts/#declaring-script-dependencies) to specify your dependencies right in your Python file and then use the `flyte.Image.from_uv_script()` method to create a `flyte.Image` object.
The `from_uv_script` method starts with the default Flyte image and adds the dependencies specified in the `uv` metadata.
For example:

```python
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "numpy"
# ]
# main = "main"
# params = "x_list=[1,2,3,4,5,6,7,8,9,10]"
# ///

import flyte
import numpy as np

env = flyte.TaskEnvironment(
    name="my_env",
    image=flyte.Image.from_uv_script(
            __file__,
            name="my-image"
            # registry="registry.example.com/my-org" # Only needed for local builds
        )
)

@env.task
def main(x_list: list[int]) -> float:
    arr = np.array(x_list)
    return float(np.mean(arr))

if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(main, x_list=list(range(10)))
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/container-images/from_uv_script.py*

The advantage of this approach is that the dependencies used when running a script locally and when running it on the Flyte/Union backend are always the same (as long as you use `uv` to run your scripts locally).
This means you can develop and test your scripts in a consistent environment, reducing the chances of encountering issues when deploying to the backend.

In the above example you can see how to use `flyte.init_from_config()` for remote runs and `flyte.init()` for local runs.
Uncomment the `flyte.init()` line (and comment out `flyte.init_from_config()`) to enable local runs.
Do the opposite to enable remote runs.

> [!NOTE]
> When using `uv` metadata in this way, be sure to include the `flyte` package in your `uv` script dependencies.
> This will ensure that `flyte` is installed when running the script locally using `uv run`.
> When running on the Flyte/Union backend, the `flyte` package from the uv script dependencies will overwrite the one included automatically from the default Flyte image.

## Image building

There are two ways that the image can be built:

* If you are running a Flyte OSS instance then the image will be built locally on your machine and pushed to the container registry you specified in the `Image` definition.
* If you are running a Union instance, the image can be built locally, as with Flyte OSS, or using the Union `ImageBuilder`, which runs remotely on Union's infrastructure.

### Configuring the `builder`

[Earlier](../connecting-to-a-cluster), we discussed the `image.builder` property in the `config.yaml`.

For Flyte OSS instances, this property must be set to `local`.

For Union instances, this property can be set to `remote` to use the Union `ImageBuilder`, or `local` to build the image locally on your machine.

### Local image building

When `image.builder` in the `config.yaml` is set to `local`, `flyte.run()` does the following:

* Builds the Docker image using your local Docker installation, installing the dependencies specified in the `uv` inline script metadata.
* Pushes the image to the container registry you specified.
* Deploys your code to the backend.
* Kicks off the execution of your workflow
* Before the task that uses your custom image is executed, the backend pulls the image from the registry to set up the container.

> [!NOTE]
> Above, we used `registry="ghcr.io/my_gh_org"`.
>
> Be sure to change `ghcr.io/my_gh_org` to the URL of your actual container registry.

You must ensure that:

* Docker is running on your local machine.
* You have successfully run `docker login` to that registry from your local machine (For example GitHub uses the syntax `echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin`)
* Your Union/Flyte installation has read access to that registry.

> [!NOTE]
> If you are using the GitHub container registry (`ghcr.io`)
> note that images pushed there are private by default.
> You may need to go to the image URI, click **Package Settings**, and change the visibility to public in order to access the image.
>
> Other registries (such as Docker Hub) require that you pre-create the image repository before pushing the image.
> In that case you can set it to public when you create it.
>
> Public images are on the public internet and should only be used for testing purposes.
> Do not place proprietary code in public images.

### Remote `ImageBuilder`

`ImageBuilder` is a service provided by Union that builds container images on Union's infrastructure and provides an internal container registry for storing the built images.

When `image.builder` in the `config.yaml` is set to `remote` (and you are running Union.ai), `flyte.run()` does the following:

* Builds the Docker image on your Union instance with `ImageBuilder`.
* Pushes the image to a registry
  * If you did not specify a `registry` in the `Image` definition, it pushes to the internal registry in your Union instance.
  * If you did specify a `registry`, it pushes to that registry. Be sure to also set the `registry_secret` parameter in the `Image` definition to enable `ImageBuilder` to authenticate to that registry (see **Configure tasks > Container images > Image building > Remote `ImageBuilder` > ImageBuilder with external registries**).
* Deploys your code to the backend.
* Kicks off the execution of your workflow.
* Before the task that uses your custom image is executed, the backend pulls the image from the registry to set up the container.

There is no set up of Docker nor any other local configuration required on your part.

> [!NOTE]
> The Flyte SDK checks whether the image builder is enabled for your cluster by verifying that the `image_build` task is deployed in the `system` project within the `production` domain.
> If you are using custom roles and policies, ensure that users are granted the `view_flyte_inventory` action for the `production/system` project-domain pair.
> See the [V1 user management documentation](/docs/v1/union//user-guide/administration/user-management) for more details on creating and assigning custom roles and policies (V2 user management currently works identically to V1).

#### ImageBuilder with external registries

If you are want to push the images built by `ImageBuilder` to an external registry, you can do this by setting the `registry` parameter in the `Image` object.
You will also need to set the `registry_secret` parameter to provide the secret needed to push and pull images to the private registry.
For example:

```python
# Add registry credentials so the Union remote builder can pull the base image
# and push the resulting image to your private registry.
image=flyte.Image.from_debian_base(
    name="my-image",
    base_image="registry.example.com/my-org/my-private-image:latest",
    registry="registry.example.com/my-org"
    registry_secret="my-secret"
)

# Reference the same secret in the TaskEnvironment so Flyte can pull the image at runtime.
env = flyte.TaskEnvironment(
    name="my_task_env",
    image=image,
    secrets="my-secret"
)
```

The value of the `registry_secret` parameter must be the name of a Flyte secret of type `image_pull` that contains the credentials needed to access the private registry. It must match the name specified in the `secrets` parameter of the `TaskEnvironment` so that Flyte can use it to pull the image at runtime.

To create an `image_pull` secret for the remote builder and the task environment, run the following command:

```bash
flyte create secret --type image_pull my-secret --from-file ~/.docker/config.json
```

The format of this secret matches the standard Kubernetes [image pull secret](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#log-in-to-docker-hub), and should look like this:

```json
{
  "auths": {
    "registry.example.com": {
      "auth": "base64-encoded-auth"
    }
  }
}
```

> [!NOTE]
> The `auth` field contains the base64-encoded credentials for your registry (username and password or token).

### Install private PyPI packages

To install Python packages from a private PyPI index (for example, from GitHub), you can mount a secret to the image layer.
This allows your build to authenticate securely during dependency installation.
For example:

```python
private_package = "git+https://$GITHUB_PAT@github.com/pingsutw/flytex.git@2e20a2acebfc3877d84af643fdd768edea41d533"
image = (
    Image.from_debian_base()
    .with_apt_packages("git")
    .with_pip_packages(private_package, pre=True, secret_mounts=Secret("GITHUB_PAT"))
)
```


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-configuration/resources ===

# Resources

Task resources specify the computational limits and requests (CPU, memory, GPU, storage) that will be allocated to each task's container during execution.

To specify resource requirements for your task, instantiate a `Resources` object with the desired parameters and assign it to either
the `resources` parameter of the `TaskEnvironment` or the `resources` parameter of the `override` function (for invocation overrides).

Every task defined using that `TaskEnvironment` will run with the specified resources.
If a specific task has its own `resources` defined in the decorator, it will override the environment's resources for that task only.

If neither `TaskEnvironment` nor the task decorator specifies `resources`, the default resource allocation will be used.

## Resources data class

For the full class definition, parameter types, and accepted formats, see the [`Resources` API reference](../../api-reference/flyte-sdk/packages/flyte/resources).

The main parameters are:

- **`cpu`**: CPU allocation — number, string (`"500m"`), or `(request, limit)` tuple.
- **`memory`**: Memory with Kubernetes units — `"4Gi"`, or `(request, limit)` tuple.
- **`gpu`**: GPU allocation — `"A100:2"`, integer count, or `GPU()`/`TPU()`/`Device()` for advanced config.
- **`disk`**: Ephemeral storage — `"10Gi"`.
- **`shm`**: Shared memory — `"1Gi"` or `"auto"`.

## Examples

### Usage in TaskEnvironment

Here's a complete example of defining a TaskEnvironment with resource specifications for a machine learning training workload:

```
import flyte

# Define a TaskEnvironment for ML training tasks
env = flyte.TaskEnvironment(
    name="ml-training",
    resources=flyte.Resources(
        cpu=("2", "4"),        # Request 2 cores, allow up to 4 cores for scaling
        memory=("2Gi", "12Gi"), # Request 2 GiB, allow up to 12 GiB for large datasets
        disk="50Gi",           # 50 GiB ephemeral storage for checkpoints
        shm="8Gi"              # 8 GiB shared memory for efficient data loading
    )
)

# Use the environment for tasks
@env.task
async def train_model(dataset_path: str) -> str:
    # This task will run with flexible resource allocation
    return "model trained"
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/resources/resources.py*

### Usage in a task-specific override

```
# Demonstrate resource override at task invocation level
@env.task
async def heavy_training_task() -> str:
    return "heavy model trained with overridden resources"

@env.task
async def main():
    # Task using environment-level resources
    result = await train_model("data.csv")
    print(result)

    # Task with overridden resources at invocation time
    result = await heavy_training_task.override(
        resources=flyte.Resources(
            cpu="4",
            memory="24Gi",
            disk="100Gi",
            shm="16Gi"
        )
    )()
    print(result)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/resources/resources.py*

## Resource types

### CPU resources

CPU can be specified in several formats:

```python
# String formats (Kubernetes-style)
flyte.Resources(cpu="500m")        # 500 milliCPU (0.5 cores)
flyte.Resources(cpu="2")           # 2 CPU cores
flyte.Resources(cpu="1.5")         # 1.5 CPU cores

# Numeric formats
flyte.Resources(cpu=1)             # 1 CPU core
flyte.Resources(cpu=0.5)           # 0.5 CPU cores

# Request and limit ranges
flyte.Resources(cpu=("1", "2"))    # Request 1 core, limit to 2 cores
flyte.Resources(cpu=(1, 4))        # Request 1 core, limit to 4 cores
```

### Memory resources

Memory specifications follow Kubernetes conventions:

```python
# Standard memory units
flyte.Resources(memory="512Mi")    # 512 MiB
flyte.Resources(memory="1Gi")      # 1 GiB
flyte.Resources(memory="2Gi")      # 2 GiB
flyte.Resources(memory="500M")     # 500 MB (decimal)
flyte.Resources(memory="1G")       # 1 GB (decimal)

# Request and limit ranges
flyte.Resources(memory=("1Gi", "4Gi"))  # Request 1 GiB, limit to 4 GiB
```

### GPU resources

Flyte supports various GPU types and configurations:

#### Simple GPU allocation

```python
# Basic GPU count
flyte.Resources(gpu=1)             # 1 GPU (any available type)
flyte.Resources(gpu=4)             # 4 GPUs

# Specific GPU types with quantity
flyte.Resources(gpu="T4:1")        # 1 NVIDIA T4 GPU
flyte.Resources(gpu="A100:2")      # 2 NVIDIA A100 GPUs
flyte.Resources(gpu="H100:8")      # 8 NVIDIA H100 GPUs
```

#### Advanced GPU configuration

You can also use the `GPU` helper class for more detailed configurations:

```python
# Using the GPU helper function
gpu_config = flyte.GPU(device="A100", quantity=2)
flyte.Resources(gpu=gpu_config)

# GPU with memory partitioning (A100 only)
partitioned_gpu = flyte.GPU(
    device="A100",
    quantity=1,
    partition="1g.5gb"  # 1/7th of A100 with 5GB memory
)
flyte.Resources(gpu=partitioned_gpu)

# A100 80GB with partitioning
large_partition = flyte.GPU(
    device="A100 80G",
    quantity=1,
    partition="7g.80gb"  # Full A100 80GB
)
flyte.Resources(gpu=large_partition)
```

#### Supported GPU types
- **T4**: Entry-level training and inference
- **L4**: Optimized for AI inference
- **L40s**: High-performance compute
- **A100**: High-end training and inference (40GB)
- **A100 80G**: High-end training with more memory (80GB)
- **H100**: Latest generation, highest performance

### Custom device specifications

You can also define custom devices if your infrastructure supports them:

```python
# Custom device configuration
custom_device = flyte.Device(
    device="custom_accelerator",
    quantity=2,
    partition="large"
)

resources = flyte.Resources(gpu=custom_device)
```

### TPU resources

For Google Cloud TPU workloads you can specify TPU resources using the `TPU` helper class:

```python
# TPU v5p configuration
tpu_config = flyte.TPU(device="V5P", partition="2x2x1")
flyte.Resources(gpu=tpu_config)  # Note: TPUs use the gpu parameter

# TPU v6e configuration
tpu_v6e = flyte.TPU(device="V6E", partition="4x4")
flyte.Resources(gpu=tpu_v6e)
```

### Storage resources

Flyte provides two types of storage resources for tasks: ephemeral disk storage and shared memory.
These resources are essential for tasks that need temporary storage for processing data, caching intermediate results, or sharing data between processes.

#### Disk storage

Ephemeral disk storage provides temporary space for your tasks to store intermediate files, downloaded datasets, model checkpoints, and other temporary data. This storage is automatically cleaned up when the task completes.

```python
flyte.Resources(disk="10Gi")       # 10 GiB ephemeral storage
flyte.Resources(disk="100Gi")      # 100 GiB ephemeral storage
flyte.Resources(disk="1Ti")        # 1 TiB for large-scale data processing

# Common use cases
flyte.Resources(disk="50Gi")       # ML model training with checkpoints
flyte.Resources(disk="200Gi")      # Large dataset preprocessing
flyte.Resources(disk="500Gi")      # Video/image processing workflows
```

#### Shared memory

Shared memory (`/dev/shm`) is a high-performance, RAM-based storage area that can be shared between processes within the same container. It's particularly useful for machine learning workflows that need fast data loading and inter-process communication.

```python
flyte.Resources(shm="1Gi")         # 1 GiB shared memory (/dev/shm)
flyte.Resources(shm="auto")        # Auto-sized shared memory
flyte.Resources(shm="16Gi")        # Large shared memory for distributed training
```


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-configuration/secrets ===

# Secrets

Flyte secrets enable you to securely store and manage sensitive information, such as API keys, passwords, and other credentials.
Secrets reside in a secret store on the data plane of your Union/Flyte backend.
You can create, list, and delete secrets in the store using the Flyte CLI or SDK.
Secrets in the store can be accessed and used within your workflow tasks, without exposing any cleartext values in your code.

## Creating a literal string secret

You can create a secret using the [`flyte create secret`](../../api-reference/flyte-cli#flyte-create-secret) command like this:

```bash
flyte create secret MY_SECRET_KEY my_secret_value
```

This will create a secret called `MY_SECRET_KEY` with the value `my_secret_value`.
This secret will be scoped to your entire organization.
It will be available across all projects and domains in your organization.
See the **Configure tasks > Secrets > Scoping secrets** section below for more details.
See **Configure tasks > Secrets > Using a literal string secret** for how to access the secret in your task code.

## Creating a file secret

You can also create a secret by specifying a local file:

```bash
flyte create secret MY_SECRET_KEY --from-file /local/path/to/my_secret_file
```

In this case, when accessing the secret in your task code, you will need to **Configure tasks > Secrets > Using a file secret**.

## Scoping secrets

When you create a secret without specifying a project or domain, as we did above, the secret is scoped to the organization level.
This means that the secret will be available across all projects and domains in the organization.

You can optionally specify either or both of the `--project` and `--domain` flags to restrict the scope of the secret to:
* A specific project (across all domains)
* A specific domain (across all project)
* A specific project and a specific domain.

For example, to create a secret that it is only available in `my_project/development`, you would execute the following command:

```bash
flyte create secret  --project my_project --domain development MY_SECRET_KEY my_secret_value
```

## Listing secrets

You can list existing secrets with the [`flyte get secret`](../../api-reference/flyte-cli#flyte-get-secret) command.
For example, the following command will list all secrets in the organization:

```bash
flyte get secret
```

Specifying either or both of the `--project` and `--domain` flags will list the secrets that are **only** available in that project and/or domain.

For example, to list the secrets that are only available in `my_project` and domain `development`, you would run:

```bash
flyte get secret --project my_project --domain development
```

## Deleting secrets

To delete a secret, use the [`flyte delete secret`](../../api-reference/flyte-cli#flyte-delete-secret) command:

```bash
flyte delete secret MY_SECRET_KEY
```

## Using a literal string secret

To use a literal string secret, specify it in the `TaskEnvironment` along with the name of the environment variable into which it will be injected.
You can then access it using `os.getenv()` in your task code.
For example:

```
env_1 = flyte.TaskEnvironment(
    name="env_1",
    secrets=[
        flyte.Secret(key="my_secret", as_env_var="MY_SECRET_ENV_VAR"),
    ]
)

@env_1.task
def task_1():
    my_secret_value = os.getenv("MY_SECRET_ENV_VAR")
    print(f"My secret value is: {my_secret_value}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/secrets/secrets.py*

## Using a file secret

To use a file secret, specify it in the `TaskEnvironment` along with the `mount="/etc/flyte/secrets"` argument (with that precise value).

The file will be mounted at `/etc/flyte/secrets/<SECRET_KEY>`.

For example:

```
env_2 = flyte.TaskEnvironment(
    name="env_2",
    secrets=[
        flyte.Secret(key="my_secret", mount="/etc/flyte/secrets"),
    ]
)

@env_2.task
def task_2():
    with open("/etc/flyte/secrets/my_secret", "r") as f:
        my_secret_file_content = f.read()
    print(f"My secret file content is: {my_secret_file_content}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/secrets/secrets.py*

> [!NOTE]
> Currently, to access a file secret you must specify a `mount` parameter value of `"/etc/flyte/secrets"`.
> This fixed path is the directory in which the secret file will be placed.
> The name of the secret file will be equal to the key of the secret.

> [!NOTE]
> A `TaskEnvironment` can only access a secret if the scope of the secret includes the project and domain where the `TaskEnvironment` is deployed.

> [!WARNING]
> Do not return secret values from tasks, as this will expose secrets to the control plane.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-configuration/caching ===

# Caching

Flyte 2 provides intelligent **task output caching** that automatically avoids redundant computation by reusing previously computed task results.

> [!NOTE]
> Caching works at the task level and caches complete task outputs.
> For function-level checkpointing and resumption *within tasks*, see [Traces](../task-programming/traces).

## Overview

By default, caching is disabled.

If caching is enabled for a task, then Flyte determines a **cache key** for the task.
The key is composed of the following:

* Final inputs: The set of inputs after removing any specified in the `ignored_inputs`.
* Task name: The fully-qualified name of the task.
* Interface hash: A hash of the task's input and output types.
* Cache version: The cache version string.

If the cache behavior is set to `"auto"`, the cache version is automatically generated using a hash of the task's source code (or according to the custom policy if one is specified).
If the cache behavior is set to `"override"`, the cache version can be specified explicitly using the `version_override` parameter.

When the task runs, Flyte checks if a cache entry exists for the key.
If found, the cached result is returned immediately instead of re-executing the task.

## Basic caching usage

Flyte 2 supports three main cache behaviors:

### `"auto"` - Automatic versioning

```
@env.task(cache=flyte.Cache(behavior="auto"))
async def auto_versioned_task(data: str) -> str:
    return await transform_data(data)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/caching/caching.py*

With `behavior="auto"`, the cache version is automatically generated based on the function's source code.
If you change the function implementation, the cache is automatically invalidated.

- **When to use**: Development and most production scenarios.
- **Cache invalidation**: Automatic when function code changes.
- **Benefits**: Zero-maintenance caching that "just works".

You can also use the direct string shorthand:

```
@env.task(cache="auto")
async def auto_versioned_task_2(data: str) -> str:
    return await transform_data(data)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/caching/caching.py*

### `"override"`

With `behavior="override"`, you can specify a custom cache key in the `version_override` parameter.
Since the cache key is fixed as part of the code, it can be manually changed when you need to invalidate the cache.

```
@env.task(cache=flyte.Cache(behavior="override", version_override="v1.2"))
async def manually_versioned_task(data: str) -> str:
    return await transform_data(data)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/caching/caching.py*

- **When to use**: When you need explicit control over cache invalidation.
- **Cache invalidation**: Manual, by changing `version_override`.
- **Benefits**: Stable caching across code changes that don't affect logic.

### `"disable"` - No caching

To explicitly disable caching, use the `"disable"` behavior.
**This is the default behavior.**

```
@env.task(cache=flyte.Cache(behavior="disable"))
async def always_fresh_task(data: str) -> str:
    return get_current_timestamp() + await transform_data(data)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/caching/caching.py*

- **When to use**: Non-deterministic functions, side effects, or always-fresh data.
- **Cache invalidation**: N/A - never cached.
- **Benefits**: Ensures execution every time.

You can also use the direct string shorthand:

```
@env.task(cache="disable")
async def always_fresh_task_2(data: str) -> str:
    return get_current_timestamp() + await transform_data(data)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/caching/caching.py*

## Advanced caching configuration

### Ignoring specific inputs

Sometimes you want to cache based on some inputs but not others:

```
@env.task(cache=flyte.Cache(behavior="auto", ignored_inputs=("debug_flag",)))
async def selective_caching(data: str, debug_flag: bool) -> str:
    if debug_flag:
        print(f"Debug: transforming {data}")
    return await transform_data(data)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/caching/caching.py*

**This is useful for**:
- Debug flags that don't affect computation
- Logging levels or output formats
- Metadata that doesn't impact results

### Cache serialization

Cache serialization ensures that only one instance of a task runs at a time for identical inputs:

```
@env.task(cache=flyte.Cache(behavior="auto", serialize=True))
async def expensive_model_training(data: str) -> str:
    return await transform_data(data)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/caching/caching.py*

**When to use serialization**:
- Very expensive computations (model training, large data processing)
- Shared resources that shouldn't be accessed concurrently
- Operations where multiple parallel executions provide no benefit

**How it works**:
1. First execution acquires a reservation and runs normally.
2. Concurrent executions with identical inputs wait for the first to complete.
3. Once complete, all waiting executions receive the cached result.
4. If the running execution fails, another waiting execution takes over.

### Salt for cache key variation

Use `salt` to vary cache keys without changing function logic:

```
@env.task(cache=flyte.Cache(behavior="auto", salt="experiment_2024_q4"))
async def experimental_analysis(data: str) -> str:
    return await transform_data(data)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/caching/caching.py*

**`salt` is useful for**:
- A/B testing with identical code.
- Temporary cache namespaces for experiments.
- Environment-specific cache isolation.

## Cache policies

For details on implementing custom cache policies, see the [`CachePolicy` protocol](../../api-reference/flyte-sdk/packages/flyte/cachepolicy) and [`Cache` class](../../api-reference/flyte-sdk/packages/flyte/cache) API references.

For `behavior="auto"`, Flyte uses cache policies to generate version hashes.

### Function body policy (default)

The default `FunctionBodyPolicy` generates cache versions from the function's source code:

```
from flyte._cache import FunctionBodyPolicy

@env.task(cache=flyte.Cache(
    behavior="auto",
    policies=[FunctionBodyPolicy()]  # This is the default. Does not actually need to be specified.
))
async def code_sensitive_task(data: str) -> str:
    return await transform_data(data)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/caching/caching.py*

### Custom cache policies

You can implement custom cache policies by following the `CachePolicy` protocol:

```
from flyte._cache import CachePolicy

class DatasetVersionPolicy(CachePolicy):
    def get_version(self, salt: str, params) -> str:
        # Generate version based on custom logic
        dataset_version = get_dataset_version()
        return f"{salt}_{dataset_version}"

@env.task(cache=flyte.Cache(behavior="auto", policies=[DatasetVersionPolicy()]))
async def dataset_dependent_task(data: str) -> str:
    # Cache invalidated when dataset version changes
    return await transform_data(data)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/caching/caching.py*

## Caching configuration at different levels

You can configure caching at three levels: `TaskEnvironment` definition, `@env.task` decorator, and task invocation.

### `TaskEnvironment` Level

You can configure caching at the `TaskEnvironment` level.
This will set the default cache behavior for all tasks defined using that environment.
For example:

```
cached_env = flyte.TaskEnvironment(
    name="cached_environment",
    cache=flyte.Cache(behavior="auto")  # Default for all tasks
)

@cached_env.task  # Inherits auto caching from environment
async def inherits_caching(data: str) -> str:
    return await transform_data(data)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/caching/caching.py*

### `@env.task` decorator level

By setting the cache parameter in the `@env.task` decorator, you can override the environment's default cache behavior for specific tasks:

```
@cached_env.task(cache=flyte.Cache(behavior="disable"))  # Override environment default
async def decorator_caching(data: str) -> str:
    return await transform_data(data)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/caching/caching.py*

### `task.override` level

By setting the cache parameter in the `task.override` method, you can override the cache behavior for specific task invocations:

```
@env.task
async def override_caching_on_call(data: str) -> str:
    # Create an overridden version and call it
    overridden_task = inherits_caching.override(cache=flyte.Cache(behavior="disable"))
    return await overridden_task(data)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/caching/caching.py*

## Runtime cache control

You can also force cache invalidation for a specific run:

```python
# Disable caching for this specific execution
run = flyte.with_runcontext(overwrite_cache=True).run(my_cached_task, data="test")
```

## Project and domain cache isolation

Caches are automatically isolated by:
- **Project**: Tasks in different projects have separate cache namespaces.
- **Domain**: Development, staging, and production domains maintain separate caches.

## Local development caching

When running locally, Flyte maintains a local cache:

```python
# Local execution uses ~/.flyte/local-cache/
flyte.init()  # Local mode
result = flyte.run(my_cached_task, data="test")
```

Local cache behavior:
- Stored in `~/.flyte/local-cache/` directory
- No project/domain isolation (since running locally)
- Disabled by setting `FLYTE_LOCAL_CACHE_ENABLED=false`


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-configuration/reusable-containers ===

# Reusable containers

By default, each task execution in Flyte and Union runs in a fresh container instance that is created just for that execution and then discarded.
With reusable containers, the same container can be reused across multiple executions and tasks.
This approach reduces start up overhead and improves resource efficiency.

> [!NOTE]
> The reusable container feature is only available when running your Flyte code on a Union backend.

## How It Works

With reusable containers, the system maintains a pool of persistent containers that can handle multiple task executions.
When you configure a `TaskEnvironment` with a `ReusePolicy`, the system does the following:

1. Creates a pool of persistent containers.
2. Routes task executions to available container instances.
3. Manages container lifecycle with configurable timeouts.
4. Supports concurrent task execution within containers (for async tasks).
5. Preserves the Python execution environment across task executions, allowing you to maintain state through global variables.

## Basic Usage

> [!NOTE]
> The reusable containers feature currently requires a dedicated runtime library
> ([`unionai-reuse`](https://pypi.org/project/unionai-reuse/)) to be installed in the task image used by the reusable task.
> You can add this library to your task image using the `flyte.Image.with_pip_packages` method, as shown below.
> This library only needs to be added to the task image.
> It does not need to be installed in your local development environment.

Enable container reuse by adding a `ReusePolicy` to your `TaskEnvironment`:

```python
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# main = "main"
# params = "n=500"
# ///

import flyte
from datetime import timedelta

# {{docs-fragment env}}
# Currently required to enable resuable containers
reusable_image = flyte.Image.from_debian_base().with_pip_packages("unionai-reuse>=0.1.10")

env = flyte.TaskEnvironment(
    name="reusable-env",
    resources=flyte.Resources(memory="1Gi", cpu="500m"),
    reusable=flyte.ReusePolicy(
        replicas=2,                           # Create 2 container instances
        concurrency=1,                        # Process 1 task per container at a time
        scaledown_ttl=timedelta(minutes=10),  # Individual containers shut down after 5 minutes of inactivity
        idle_ttl=timedelta(hours=1)           # Entire environment shuts down after 30 minutes of no tasks
    ),
    image=reusable_image  # Use the container image augmented with the unionai-reuse library.
)
# {{/docs-fragment env}}

@env.task
async def compute_task(x: int) -> int:
    return x * x

@env.task
async def main() -> list[int]:
    # These tasks will reuse containers from the pool
    results = []
    for i in range(10):
        result = await compute_task(i)
        results.append(result)
    return results

if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(main)
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/reusable-containers/reuse.py*

## `ReusePolicy` parameters

For detailed parameter documentation, including capacity math and lifecycle behavior, see the [`ReusePolicy` API reference](../../api-reference/flyte-sdk/packages/flyte/reusepolicy).

The `ReusePolicy` class controls how containers are managed in a reusable environment:

```python
flyte.ReusePolicy(
    replicas: typing.Union[int, typing.Tuple[int, int]],
    concurrency: int,
    scaledown_ttl: typing.Union[int, datetime.timedelta],
    idle_ttl: typing.Union[int, datetime.timedelta]
)
```

### `replicas`: Container pool size

Controls the number of container instances in the reusable pool:

- **Fixed size**: `replicas=3` Creates exactly 3 container instances. These 3 replicas will be shutdown after `idle_ttl` expires.
- **Auto-scaling**: `replicas=(2, 5)` Starts with 2 containers and can scale up to 5 based on demand.
  - If the task is running on 2 replicas and demand drops to zero then these 2 containers will be shutdown after `idle_ttl` expires.
  - If the task is running on 2 replicas and demand increases, new containers will be created up to the maximum of 5.
  - If the task is running on 5 replicas and demand drops, container 5 will be shutdown after `scaledown_ttl` expires.
  - If demand drops again, container 4 will be also shutdown after another period of `scaledown_ttl` expires.
- **Resource impact**: Each replica consumes the full resources defined in `TaskEnvironment.resources`.

```python
# Fixed pool size
fixed_pool_policy = flyte.ReusePolicy(
    replicas=3,
    concurrency=1,
    scaledown_ttl=timedelta(minutes=10),
    idle_ttl=timedelta(hours=1)
)

# Auto-scaling pool
auto_scaling_policy = flyte.ReusePolicy(
    replicas=(1, 10),
    concurrency=1,
    scaledown_ttl=timedelta(minutes=10),
    idle_ttl=timedelta(hours=1)
)
```

### `concurrency`: Tasks per container

Controls how many tasks can execute simultaneously within a single container:

- **Default**: `concurrency=1` (one task per container at a time).
- **Higher concurrency**: `concurrency=5` allows 5 tasks to run simultaneously in each container.
- **Total capacity**: `replicas × concurrency` = maximum concurrent tasks across the entire pool.

```python
# Sequential processing (default)
sequential_policy = flyte.ReusePolicy(
    replicas=2,
    concurrency=1,  # One task per container
    scaledown_ttl=timedelta(minutes=10),
    idle_ttl=timedelta(hours=1)
)

# Concurrent processing
concurrent_policy = flyte.ReusePolicy(
    replicas=2,
    concurrency=5,  # 5 tasks per container = 10 total concurrent tasks
    scaledown_ttl=timedelta(minutes=10),
    idle_ttl=timedelta(hours=1)
)
```

### `idle_ttl` vs `scaledown_ttl`: Container lifecycle

These parameters work together to manage container lifecycle at different levels:

#### `idle_ttl`: Environment timeout

- **Scope**: Controls the entire reusable environment infrastructure.
- **Behavior**: When there are no active or queued tasks, the entire environment scales down after `idle_ttl` expires.
- **Purpose**: Manages the lifecycle of the entire container pool.
- **Typical values**: 1-2 hours, or `None` for always-on environments

#### `scaledown_ttl`: Individual container timeout

- **Scope**: Controls individual container instances.
- **Behavior**: When a container finishes a task and becomes inactive, it will be terminated after `scaledown_ttl` expires.
- **Purpose**: Prevents resource waste from inactive containers.
- **Typical values**: 5-30 minutes for most workloads.

```python
from datetime import timedelta

lifecycle_policy = flyte.ReusePolicy(
    replicas=3,
    concurrency=2,
    scaledown_ttl=timedelta(minutes=10),  # Individual containers shut down after 10 minutes of inactivity
    idle_ttl=timedelta(hours=1)         # Entire environment shuts down after 1 hour of no tasks
)
```

## Understanding parameter relationships

The four `ReusePolicy` parameters work together to control different aspects of container management:

```python
reuse_policy = flyte.ReusePolicy(
    replicas=4,                           # Infrastructure: How many containers?
    concurrency=3,                        # Throughput: How many tasks per container?
    scaledown_ttl=timedelta(minutes=10),  # Individual: When do idle containers shut down?
    idle_ttl=timedelta(hours=1)           # Environment: When does the whole pool shut down?
)
# Total capacity: 4 × 3 = 12 concurrent tasks
# Individual containers shut down after 10 minutes of inactivity
# Entire environment shuts down after 1 hour of no tasks
```

### Key relationships

- **Total throughput** = `replicas × concurrency`
- **Resource usage** = `replicas × TaskEnvironment.resources`
- **Cost efficiency**: Higher `concurrency` reduces container overhead, more `replicas` provides better isolation
- **Lifecycle management**:  `scaledown_ttl` manages individual containers, `idle_ttl` manages the environment

## Simple example

Here is a simple, but complete, example of reuse with concurrency

First, import the needed modules, set upf logging:

```
import asyncio
import logging

import flyte

logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/reusable-containers/reuse_concurrency.py*

Next, we set up the reusable task environment. Note that, currently, the image used for a reusable environment requires an extra package to be installed:

```
env = flyte.TaskEnvironment(
    name="reuse_concurrency",
    resources=flyte.Resources(cpu=1, memory="1Gi"),
    reusable=flyte.ReusePolicy(
        replicas=2,
        idle_ttl=60,
        concurrency=100,
        scaledown_ttl=60,
    ),
    image=flyte.Image.from_debian_base().with_pip_packages("unionai-reuse>=0.1.10"),
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/reusable-containers/reuse_concurrency.py*

Now, we define the `reuse_concurrency` task (the main driver task of the workflow) and the `noop` task that will be executed multiple times reusing the same containers:

```
@env.task
async def noop(x: int) -> int:
    logger.debug(f"Task noop: {x}")
    return x

@env.task
async def main(n: int = 50) -> int:
    coros = [noop(i) for i in range(n)]
    results = await asyncio.gather(*coros)
    return sum(results)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/reusable-containers/reuse_concurrency.py*

Finally, we deploy and run the workflow programmatically, so all you have to do is execute `python reuse_concurrency.py` to see it in action:

```
if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(main, n=500)
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/reusable-containers/reuse_concurrency.py*


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-configuration/pod-templates ===

# Pod templates

Flyte is built on Kubernetes and leverages its powerful container orchestration capabilities. A Kubernetes [pod](https://kubernetes.io/docs/concepts/workloads/pods/) is a group of one or more containers that share storage and network resources. While Flyte automatically runs your task code in a container, pod templates let you customize the entire pod specification for advanced use cases.

The `pod_template` parameter in `TaskEnvironment` allows you to:

- **Add sidecar containers**: Run metrics exporters, service proxies, or specialized services alongside your task
- **Mount volumes**: Attach persistent storage or cloud storage like GCS or S3
- **Configure metadata**: Set custom labels and annotations for monitoring, routing, or cluster policies
- **Manage resources**: Configure resource requests, limits, and affinities
- **Inject configuration**: Add secrets, environment variables, or config maps
- **Access private registries**: Specify image pull secrets

## How it works

When you define a pod template:

1. **Primary container**: Flyte automatically injects your task code into the container specified by `primary_container_name` (default: `"primary"`)
2. **Automatic monitoring**: Flyte watches the primary container and exits the entire pod when it completes
3. **Image handling**: The image for your task environment is built automatically by Flyte; images for sidecar containers must be provided by you
4. **Local execution**: When running locally, only the task code executes—additional containers are not started

## Requirements

To use pod templates, install the Kubernetes Python client:

```bash
pip install kubernetes
```

Or add it to your image dependencies:

```python
image = flyte.Image.from_debian_base().with_pip_packages("kubernetes")
```

## Basic usage

Here's a complete example showing how to configure labels, annotations, environment variables, and image pull secrets:

```
# /// script
# requires-python = "==3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "kubernetes"
# ]
# ///

import flyte
from kubernetes.client import (
    V1Container,
    V1EnvVar,
    V1LocalObjectReference,
    V1PodSpec,
)

# Create a custom pod template
pod_template = flyte.PodTemplate(
    primary_container_name="primary",           # Name of the main container
    labels={"lKeyA": "lValA"},                 # Custom pod labels
    annotations={"aKeyA": "aValA"},            # Custom pod annotations
    pod_spec=V1PodSpec(                        # Kubernetes pod specification
        containers=[
            V1Container(
                name="primary",
                env=[V1EnvVar(name="hello", value="world")]  # Environment variables
            )
        ],
        image_pull_secrets=[                   # Access to private registries
            V1LocalObjectReference(name="regcred-test")
        ],
    ),
)

# Use the pod template in a TaskEnvironment
env = flyte.TaskEnvironment(
    name="hello_world",
    pod_template=pod_template,                 # Apply the custom pod template
    image=flyte.Image.from_uv_script(__file__, name="flyte", pre=True),
)

@env.task
async def say_hello(data: str) -> str:
    return f"Hello {data}"

@env.task
async def say_hello_nested(data: str = "default string") -> str:
    return await say_hello(data=data)

if __name__ == "__main__":
    flyte.init_from_config()
    result = flyte.run(say_hello_nested, data="hello world")
    print(result.url)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/pod-templates/pod_template.py*

## PodTemplate parameters

The `PodTemplate` class provides the following parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| `primary_container_name` | `str` | Name of the container where task code runs (default: `"primary"`). Must match a container in `pod_spec`. |
| `pod_spec` | `V1PodSpec` | Kubernetes pod specification for configuring containers, volumes, security contexts, and more. |
| `labels` | `dict[str, str]` | Pod labels for organization and selection by Kubernetes selectors. |
| `annotations` | `dict[str, str]` | Pod annotations for metadata and integrations (doesn't affect scheduling). |

## Volume mounts

Pod templates are commonly used to mount volumes for persistent storage or cloud storage access:

```python
from kubernetes.client import (
    V1Container,
    V1PodSpec,
    V1Volume,
    V1VolumeMount,
    V1CSIVolumeSource,
)
import flyte

pod_template = flyte.PodTemplate(
    primary_container_name="primary",
    pod_spec=V1PodSpec(
        containers=[
            V1Container(
                name="primary",
                volume_mounts=[
                    V1VolumeMount(
                        name="data-volume",
                        mount_path="/mnt/data",
                        read_only=False,
                    )
                ],
            )
        ],
        volumes=[
            V1Volume(
                name="data-volume",
                csi=V1CSIVolumeSource(
                    driver="your-csi-driver",
                    volume_attributes={"key": "value"},
                ),
            )
        ],
    ),
)

env = flyte.TaskEnvironment(
    name="volume-example",
    pod_template=pod_template,
    image=flyte.Image.from_debian_base(),
)

@env.task
async def process_data() -> str:
    # Access mounted volume
    with open("/mnt/data/input.txt", "r") as f:
        data = f.read()
    return f"Processed {len(data)} bytes"
```

### GCS/S3 volume mounts

Mount cloud storage directly into your pod for efficient data access:

```python
from kubernetes.client import V1Container, V1PodSpec, V1Volume, V1VolumeMount, V1CSIVolumeSource
import flyte

# GCS example with CSI driver
pod_template = flyte.PodTemplate(
    primary_container_name="primary",
    annotations={
        "gke-gcsfuse/volumes": "true",
        "gke-gcsfuse/cpu-limit": "2",
        "gke-gcsfuse/memory-limit": "1Gi",
    },
    pod_spec=V1PodSpec(
        containers=[
            V1Container(
                name="primary",
                volume_mounts=[V1VolumeMount(name="gcs", mount_path="/mnt/gcs")],
            )
        ],
        volumes=[
            V1Volume(
                name="gcs",
                csi=V1CSIVolumeSource(
                    driver="gcsfuse.csi.storage.gke.io",
                    volume_attributes={"bucketName": "my-bucket"},
                ),
            )
        ],
    ),
)
```

## Sidecar containers

Add sidecar containers to run alongside your task. Common use cases include:

- **Metrics exporters**: Prometheus, Datadog agents
- **Service proxies**: Istio, Linkerd sidecars
- **Data services**: Databases, caches, or specialized services like Nvidia NIMs

```python
from kubernetes.client import V1Container, V1PodSpec
import flyte

pod_template = flyte.PodTemplate(
    primary_container_name="primary",
    pod_spec=V1PodSpec(
        containers=[
            # Primary container (where your task code runs)
            V1Container(name="primary"),

            # Sidecar container
            V1Container(
                name="metrics-sidecar",
                image="prom/pushgateway:latest",
                ports=[{"containerPort": 9091}],
            ),
        ],
    ),
)

env = flyte.TaskEnvironment(
    name="sidecar-example",
    pod_template=pod_template,
    image=flyte.Image.from_debian_base().with_pip_packages("requests"),
)

@env.task
async def task_with_metrics() -> str:
    import requests

    # Send metrics to sidecar
    requests.post("http://localhost:9091/metrics", data="my_metric 42")

    # Your task logic
    return "Task completed with metrics"
```

## Image pull secrets

Configure private registry access:

```python
from kubernetes.client import V1Container, V1PodSpec, V1LocalObjectReference
import flyte

pod_template = flyte.PodTemplate(
    primary_container_name="primary",
    pod_spec=V1PodSpec(
        containers=[V1Container(name="primary")],
        image_pull_secrets=[V1LocalObjectReference(name="my-registry-secret")],
    ),
)
```

## Cluster-specific configuration

Pod templates are often used to configure Kubernetes-specific settings required by your cluster, even when not using multiple containers:

```python
import flyte

pod_template = flyte.PodTemplate(
    primary_container_name="primary",
    annotations={
        "iam.amazonaws.com/role": "my-task-role",  # AWS IAM role
        "cluster-autoscaler.kubernetes.io/safe-to-evict": "false",
    },
    labels={
        "cost-center": "ml-team",
        "project": "recommendations",
    },
)
```

## Important notes

1. **Local execution**: Pod templates only apply to remote execution. When running locally, only your task code executes.

2. **Image building**: Flyte automatically builds and manages the image for your task environment. Images for sidecar containers must be pre-built and available in a registry.

3. **Primary container**: Your task code is automatically injected into the container matching `primary_container_name`. This container must be defined in the `pod_spec.containers` list.

4. **Lifecycle management**: Flyte monitors the primary container and terminates the entire pod when it exits, ensuring sidecar containers don't run indefinitely.

## Best practices

1. **Start simple**: Begin with basic labels and annotations before adding complex sidecars
2. **Test locally first**: Verify your task logic works locally before adding pod customizations
3. **Use environment-specific templates**: Different environments (dev, staging, prod) may need different pod configurations
4. **Set resource limits**: Always set resource requests and limits for sidecars to prevent cluster issues
5. **Security**: Use image pull secrets and least-privilege service accounts

## Learn more

- [Kubernetes Pods Documentation](https://kubernetes.io/docs/concepts/workloads/pods/)
- [Kubernetes Python Client](https://github.com/kubernetes-client/python)
- [V1PodSpec Reference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#podspec-v1-core)


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-configuration/multiple-environments ===

# Multiple environments

In many applications, different tasks within your workflow may require different configurations.
Flyte enables you to manage this complexity by allowing multiple environments within a single workflow.

Multiple environments are useful when:
- Different tasks in your workflow need different dependencies.
- Some tasks require specific CPU/GPU or memory configurations.
- A task requires a secret that other tasks do not (and you want to limit exposure of the secret value).
- You're integrating specialized tools that have conflicting requirements.

## Constraints on multiple environments

To use multiple environments in your workflow you define multiple `TaskEnvironment` instances, each with its own configuration, and then assign tasks to their respective environments.

There are, however, two additional constraints that you must take into account.
If `task_1` in environment `env_1` calls a `task_2` in environment `env_2`, then:

1. `env_1` must declare a deployment-time dependency on `env_2` in the `depends_on` parameter of `TaskEnvironment` that defines `env_1`.
2. The image used in the `TaskEnvironment` of `env_1` must include all dependencies of the module containing the `task_2` (unless `task_2` is invoked as a remote task).

<!-- TODO: Link to remote tasks when that page is live
2. The image used in the `TaskEnvironment` of `env_1` must include all dependencies of the module containing the `task_2` (unless [`task_2` is invoked as a remote task](../task-programming/remote-tasks)).
-->

### Task `depends_on` constraints

The `depends_on` parameter in `TaskEnvironment` is used to provide deployment-time dependencies by establishing a relationship between one `TaskEnvironment` and another.
The system uses this information to determine which environments (and, specifically which images) need to be built in order to be able to run the code.

On `flyte run` (or `flyte deploy`), the system walks the tree defined by the `depends_on` relationships, starting with the environment of the task being invoked (or the environment being deployed, in the case of `flyte deploy`), and prepares each required environment.
Most importantly, it ensures that the container images need for all required environments are available (and if not, it builds them).

This deploy-time determination of what to build is important because it means that for any given `run` or `deploy`, only those environments that are actually required are built.
The alternative strategy of building all environments defined in the set of deployed code can lead to unnecessary and expensive builds, especially when iterating on code.

### Dependency inclusion constraints

When a parent task invokes a child task in a different environment, the container image of the parent task environment must include all dependencies used by the child task.
This is necessary because of the way task invocation works in Flyte:

- When a child task is invoked by function name, that function, necessarily, has to be imported into the parent tasks's Python environment.
- This results in all the dependencies of the child task function also being imported.
- But, nonetheless, the actual execution of the child task occurs in its own environment.

To avoid this requirement, you can invoke a task in another environment _remotely_.

<!-- TODO: Link to remote tasks when that page is live
To avoid this requirement, you can [invoke a task in another environment _remotely_](../task-programming/remote-tasks).
-->

## Example

The following example is a (very) simple mock of an AlphaFold2 pipeline.
It demonstrates a workflow with three tasks, each in its own environment.

The example project looks like this:

```bash
├── msa/
│   ├── __init__.py
│   └── run.py
├── fold/
│   ├── __init__.py
│   └── run.py
├── __init__.py
└── main.py
```
(The source code for this example can be found here:[AlphaFold2 mock example](https://github.com/unionai/unionai-examples/tree/main/v2/user-guide/task-configuration/multiple-environments/af2))

In file `msa/run.py` we define the task `run_msa`, which mocks the multiple sequence alignment step of the process:

```python
import flyte
from flyte.io import File

MSA_PACKAGES = ["pytest"]

msa_image = flyte.Image.from_debian_base().with_pip_packages(*MSA_PACKAGES)

msa_env = flyte.TaskEnvironment(name="msa_env", image=msa_image)

@msa_env.task
def run_msa(x: str) -> File:
    f = File.new_remote()
    with f.open_sync("w") as fp:
        fp.write(x)
    return f
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/multiple-environments/af2/msa/run.py*

* A dedicated image (`msa_image`) is built using the `MSA_PACKAGES` dependency list, on top of the standard base image.
* A dedicated environment (`msa_env`) is defined for the task, using `msa_image`.
* The task is defined within the context of the `msa_env` environment.

In file `fold/run.py` we define the task `run_fold`, which mocks the fold step of the process:

```python
import flyte
from flyte.io import File

FOLD_PACKAGES = ["ruff"]

fold_image = flyte.Image.from_debian_base().with_pip_packages(*FOLD_PACKAGES)

fold_env = flyte.TaskEnvironment(name="fold_env", image=fold_image)

@fold_env.task
def run_fold(sequence: str, msa: File) -> list[str]:
    with msa.open_sync("r") as f:
        msa_content = f.read()
    return [msa_content, sequence]
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/multiple-environments/af2/fold/run.py*

* A dedicated image (`fold_image`) is built using the `FOLD_PACKAGES` dependency list, on top of the standard base image.
* A dedicated environment (`fold_env`) is defined for the task, using `fold_image`.
* The task is defined within the context of the `fold_env` environment.

Finally, in file `main.py` we define the task `main` that ties everything together into a workflow.

We import the required modules and functions:

```
import logging
import pathlib

from fold.run import fold_env, fold_image, run_fold
from msa.run import msa_env, MSA_PACKAGES, run_msa

import flyte
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/multiple-environments/af2/main.py*

Notice that we import
* The task functions that we will be calling: `run_fold` and `run_msa`.
* The environments of those tasks: `fold_env` and `msa_env`.
* The dependency list of the `run_msa` task: `MSA_PACKAGES`
* The image of the `run_fold` task: `fold_image`

We then assemble the image and the environment:

```
main_image = fold_image.with_pip_packages(*MSA_PACKAGES)

env = flyte.TaskEnvironment(
    name="multi_env",
    depends_on=[fold_env, msa_env],
    image=main_image,
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/multiple-environments/af2/main.py*

The image for the `main` task (`main_image`) is built by starting with `fold_image` (the image for the `run_fold` task) and adding `MSA_PACKAGES` (the dependency list for the `run_msa` task).
This ensures that `main_image` includes all dependencies needed by both the `run_fold` and `run_msa` tasks.

The environment for the `main` task is defined with:
* The image `main_image`. This ensures that the `main` task has all the dependencies it needs.
* A depends_on list that includes both `fold_env` and `msa_env`. This establishes the deploy-time dependencies on those environments.

Finally, we define the `main` task itself:

```
@env.task
def main(sequence: str) -> list[str]:
    """Given a sequence, outputs files containing the protein structure
    This requires model weights + gpus + large database on aws fsx lustre
    """
    print(f"Running AlphaFold2 for sequence: {sequence}")
    msa = run_msa(sequence)
    print(f"MSA result: {msa}, passing to fold task")
    results = run_fold(sequence, msa)
    print(f"Fold results: {results}")
    return results
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/multiple-environments/af2/main.py*

Here we call, in turn, the `run_msa` and `run_fold` tasks.
Since we call them directly rather than as remote tasks, we had to ensure that `main_image` includes all dependencies needed by both tasks.

<!-- TODO: Link to remote tasks when that page is live
Note that we call them directly, not as [remote tasks](../task-programming/remote-tasks), which is why we had to ensure that `main_image` includes all dependencies needed by both tasks.
-->

The final piece of the puzzle is the `if __name__ == "__main__":` block that allows us to run the `main` task on the configured Flyte backend:

```
if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(main, "AAGGTTCCAA")
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/multiple-environments/af2/main.py*

Now you can run the workflow with:

```bash
python main.py
```


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-configuration/retries-and-timeouts ===

# Retries and timeouts

Flyte provides robust error handling through configurable retry strategies and timeout controls.
These parameters help ensure task reliability and prevent resource waste from runaway processes.

## Retries

The `retries` parameter controls how many times a failed task should be retried before giving up.
A "retry" is any attempt after the initial attempt.
In other words, `retries=3` means the task may be attempted up to 4 times in total (1 initial + 3 retries).

The `retries` parameter can be configured in either the `@env.task` decorator or using `override` when invoking the task.
It cannot be configured in the `TaskEnvironment` definition.

The code for the examples below can be found on [GitHub](https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/retries-and-timeouts/retries.py).

### Retry example

First we import the required modules and set up a task environment:

```
import random
from datetime import timedelta

import flyte

env = flyte.TaskEnvironment(name="my-env")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/retries-and-timeouts/retries.py*

Then we configure our task to retry up to 3 times if it fails (for a total of 4 attempts). We also define the driver task `main` that calls the `retry` task:

```
@env.task(retries=3)
async def retry() -> str:
    if random.random() < 0.7:  # 70% failure rate
        raise Exception("Task failed!")
    return "Success!"

@env.task
async def main() -> list[str]:
    results = []
    try:
        results.append(await retry())
    except Exception as e:
        results.append(f"Failed: {e}")
    try:
        results.append(await retry.override(retries=5)())
    except Exception as e:
        results.append(f"Failed: {e}")
    return results
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/retries-and-timeouts/retries.py*

Note that we call `retry` twice: first without any `override`, and then with an `override` to increase the retries to 5 (for a total of 6 attempts).

Finally, we configure flyte and invoke the `main` task:

```
if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(main)
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/retries-and-timeouts/retries.py*

## Timeouts

The `timeout` parameter sets limits on how long a task can run, preventing resource waste from stuck processes.
It supports multiple formats for different use cases.

The `timeout` parameter can be configured in either the `@env.task` decorator or using `override` when invoking the task.
It cannot be configured in the `TaskEnvironment` definition.

The code for the example below can be found on [GitHub](https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/retries-and-timeouts/timeouts.py).

### Timeout example

First, we import the required modules and set up a task environment:

```
import random
from datetime import timedelta
import asyncio

import flyte
from flyte import Timeout

env = flyte.TaskEnvironment(name="my-env")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/retries-and-timeouts/timeouts.py*

Our first task sets a timeout using seconds as an integer:

```
@env.task(timeout=60)  # 60 seconds
async def timeout_seconds() -> str:
    await asyncio.sleep(random.randint(0, 120))  # Random wait between 0 and 120 seconds
    return "timeout_seconds completed"
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/retries-and-timeouts/timeouts.py*

We can also set a timeout using a `timedelta` object for more readable durations:

```
@env.task(timeout=timedelta(minutes=1))
async def timeout_timedelta() -> str:
    await asyncio.sleep(random.randint(0, 120))  # Random wait between 0 and 120 seconds
    return "timeout_timedelta completed"
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/retries-and-timeouts/timeouts.py*

You can also set separate timeouts for maximum execution time and maximum queue time using the `Timeout` class:

```
@env.task(timeout=Timeout(
    max_runtime=timedelta(minutes=1),      # Max execution time per attempt
    max_queued_time=timedelta(minutes=1)   # Max time in queue before starting
))
async def timeout_advanced() -> str:
    await asyncio.sleep(random.randint(0, 120))  # Random wait between 0 and 120 seconds
    return "timeout_advanced completed"
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/retries-and-timeouts/timeouts.py*

You can also combine retries and timeouts for resilience and resource control:

```
@env.task(
    retries=3,
    timeout=Timeout(
        max_runtime=timedelta(minutes=1),
        max_queued_time=timedelta(minutes=1)
    )
)
async def timeout_with_retry() -> str:
    await asyncio.sleep(random.randint(0, 120))  # Random wait between 0 and 120 seconds
    return "timeout_advanced completed"
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/retries-and-timeouts/timeouts.py*

Here we specify:
- Up to 3 retry attempts.
- Each attempt times out after 1 minute.
- Task fails if queued for more than 1 minute.
- Total possible runtime: 1 minute queue + (1 minute × 3 attempts).

We define the `main` driver task that calls all the timeout tasks concurrently and returns their outputs as a list. The return value for failed tasks will indicate failure:

```
@env.task
async def main() -> list[str]:
    tasks = [
        timeout_seconds(),
        timeout_seconds.override(timeout=120)(),  # Override to 120 seconds
        timeout_timedelta(),
        timeout_advanced(),
        timeout_with_retry(),
    ]
    results = await asyncio.gather(*tasks, return_exceptions=True)
    output = []
    for r in results:
        if isinstance(r, Exception):
            output.append(f"Failed: {r}")
        else:
            output.append(r)
    return output
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/retries-and-timeouts/timeouts.py*

Note that we also demonstrate overriding the timeout for `timeout_seconds` to 120 seconds when calling it.

Finally, we configure Flyte and invoke the `main` task:

```
if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(main)
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/retries-and-timeouts/timeouts.py*

Proper retry and timeout configuration ensures your Flyte workflows are both reliable and efficient, handling transient failures gracefully while preventing resource waste.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-configuration/triggers ===

# Triggers

Triggers allow you to automate and parameterize an execution by scheduling its start time and providing overrides for its task inputs.

Currently, only **schedule triggers** are supported.
This type of trigger runs a task based on a Cron expression or a fixed-rate schedule.

Support is coming for other trigger types, such as:

* Webhook triggers: Hit an API endpoint to run your task.
* Artifact triggers: Run a task when a specific artifact is produced.

## Triggers are set in the task decorator

A trigger is created by setting the `triggers` parameter in the task decorator to a `flyte.Trigger` object or a list of such objects (triggers are not settable at the `TaskEnvironment` definition or `task.override` levels).

Here is a simple example:

```
import flyte
from datetime import datetime, timezone

env = flyte.TaskEnvironment(name="trigger_env")

@env.task(triggers=flyte.Trigger.hourly())  # Every hour
def hourly_task(trigger_time: datetime, x: int = 1) -> str:
    return f"Hourly example executed at {trigger_time.isoformat()} with x={x}"
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

Here we use a predefined schedule trigger to run the `hourly_task` every hour.
Other predefined triggers can be used similarly (see **Configure tasks > Triggers > Predefined schedule triggers** below).

If you want full control over the trigger behavior, you can define a trigger using the `flyte.Trigger` class directly.

## `flyte.Trigger`

For complete parameter documentation, see the [`Trigger`](../../api-reference/flyte-sdk/packages/flyte/trigger), [`Cron`](../../api-reference/flyte-sdk/packages/flyte/cron), and [`FixedRate`](../../api-reference/flyte-sdk/packages/flyte/fixedrate) API references.

The `Trigger` class allows you to define custom triggers with full control over scheduling and execution behavior. It has the following signature:

```
flyte.Trigger(
    name,
    automation,
    description="",
    auto_activate=True,
    inputs=None,
    env_vars=None,
    interruptible=None,
    overwrite_cache=False,
    queue=None,
    labels=None,
    annotations=None
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

### Core Parameters

**`name: str`** (required)
The unique identifier for the trigger within your project/domain.

**`automation: Union[Cron, FixedRate]`** (required)
Defines when the trigger fires. Use `flyte.Cron("expression")` for Cron-based scheduling or `flyte.FixedRate(interval_minutes, start_time=start_time)` for fixed intervals.

### Configuration Parameters

**`description: str = ""`**
Human-readable description of the trigger's purpose.

**`auto_activate: bool = True`**
Whether the trigger should be automatically activated when deployed. Set to `False` to deploy inactive triggers that require manual activation.

**`inputs: Dict[str, Any] | None = None`**
Default parameter values for the task when triggered. Use `flyte.TriggerTime` as a value to inject the trigger execution timestamp into that parameter.

### Runtime Override Parameters

**`env_vars: Dict[str, str] | None = None`**
Environment variables to set for triggered executions, overriding the task's default environment variables.

**`interruptible: bool | None = None`**
Whether triggered executions can be interrupted (useful for cost optimization with spot/preemptible instances). Overrides the task's interruptible setting.

**`overwrite_cache: bool = False`**
Whether to bypass/overwrite task cache for triggered executions, ensuring fresh computation.

**`queue: str | None = None`**
Specific execution queue for triggered runs, overriding the task's default queue.

### Metadata Parameters

**`labels: Mapping[str, str] | None = None`**
Key-value labels for organizing and filtering triggers (e.g., team, component, priority).

**`annotations: Mapping[str, str] | None = None`**
Additional metadata, often used by infrastructure tools for compliance, monitoring, or cost tracking.

Here's a comprehensive example showing all parameters:

```
comprehensive_trigger = flyte.Trigger(
    name="monthly_financial_report",
    automation=flyte.Cron("0 6 1 * *", timezone="America/New_York"),
    description="Monthly financial report generation for executive team",
    auto_activate=True,
    inputs={
        "report_date": flyte.TriggerTime,
        "report_type": "executive_summary",
        "include_forecasts": True
    },
    env_vars={
        "REPORT_OUTPUT_FORMAT": "PDF",
        "EMAIL_NOTIFICATIONS": "true"
    },
    interruptible=False,  # Critical report, use dedicated resources
    overwrite_cache=True,  # Always fresh data
    queue="financial-reports",
    labels={
        "team": "finance",
        "criticality": "high",
        "automation": "scheduled"
    },
    annotations={
        "compliance.company.com/sox-required": "true",
        "backup.company.com/retain-days": "2555"  # 7 years
    }
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

## The `automation` parameter with `flyte.FixedRate`

You can define a fixed-rate schedule trigger by setting the `automation` parameter of the `flyte.Trigger` to an instance of `flyte.FixedRate`.

The `flyte.FixedRate` has the following signature:

```
flyte.FixedRate(
    interval_minutes,
    start_time=None
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

### Parameters

**`interval_minutes: int`** (required)
The interval between trigger executions in minutes.

**`start_time: datetime | None`**
When to start the fixed rate schedule. If not specified, starts when the trigger is deployed and activated.

### Examples

```
# Every 90 minutes, starting when deployed
every_90_min = flyte.Trigger(
    "data_processing",
    flyte.FixedRate(interval_minutes=90)
)

# Every 6 hours (360 minutes), starting at a specific time
specific_start = flyte.Trigger(
    "batch_job",
    flyte.FixedRate(
        interval_minutes=360,  # 6 hours
        start_time=datetime(2025, 12, 1, 9, 0, 0)  # Start Dec 1st at 9 AM
    )
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

## The `automation` parameter with `flyte.Cron`

You can define a Cron-based schedule trigger by setting the `automation` parameter to an instance of `flyte.Cron`.

The `flyte.Cron` has the following signature:

```
flyte.Cron(
    cron_expression,
    timezone=None
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

### Parameters

**`cron_expression: str`** (required)
The cron expression defining when the trigger should fire. Uses standard Unix cron format with five fields: minute, hour, day of month, month, and day of week.

**`timezone: str | None`**
The timezone for the cron expression. If not specified, it defaults to UTC. Uses standard timezone names like "America/New_York" or "Europe/London".

### Examples

```
# Every day at 6 AM UTC
daily_trigger = flyte.Trigger(
    "daily_report",
    flyte.Cron("0 6 * * *")
)

# Every weekday at 9:30 AM Eastern Time
weekday_trigger = flyte.Trigger(
    "business_hours_task",
    flyte.Cron("30 9 * * 1-5", timezone="America/New_York")
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

#### Cron Expressions

Here are some common cron expressions you can use:

| Expression     | Description                          |
|----------------|--------------------------------------|
| `0 0 * * *`    | Every day at midnight                |
| `0 9 * * 1-5`  | Every weekday at 9 AM                |
| `30 14 * * 6`  | Every Saturday at 2:30 PM            |
| `0 0 1 * *`    | First day of every month at midnight |
| `0 0 25 * *`   | 25th day of every month at midnight  |
| `0 0 * * 0`    | Every Sunday at midnight             |
| `*/10 * * * *` | Every 10 minutes                     |
| `0 */2 * * *`  | Every 2 hours                        |

For a full guide on Cron syntax, refer to [Crontab Guru](https://crontab.guru/).

## The `inputs` parameter

The `inputs` parameter allows you to provide default values for your task's parameters when the trigger fires.
This is essential for parameterizing your automated executions and passing trigger-specific data to your tasks.

### Basic Usage

```
trigger_with_inputs = flyte.Trigger(
    "data_processing",
    flyte.Cron("0 6 * * *"),  # Daily at 6 AM
    inputs={
        "batch_size": 1000,
        "environment": "production",
        "debug_mode": False
    }
)

@env.task(triggers=trigger_with_inputs)
def process_data(batch_size: int, environment: str, debug_mode: bool = True) -> str:
    return f"Processing {batch_size} items in {environment} mode"
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

### Using `flyte.TriggerTime`

The special `flyte.TriggerTime` value is used in the `inputs` to indicate the task parameter into which Flyte will inject the trigger execution timestamp:

```
timestamp_trigger = flyte.Trigger(
    "daily_report",
    flyte.Cron("0 0 * * *"),  # Daily at midnight
    inputs={
        "report_date": flyte.TriggerTime,  # Receives trigger execution time
        "report_type": "daily_summary"
    }
)

@env.task(triggers=timestamp_trigger)
def generate_report(report_date: datetime, report_type: str) -> str:
    return f"Generated {report_type} for {report_date.strftime('%Y-%m-%d')}"
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

### Required vs optional parameters

> [!IMPORTANT]
> If your task has parameters without default values, you **must** provide values for them in the trigger inputs, otherwise the trigger will fail to execute.

```python
# ❌ This will fail - missing required parameter 'data_source'
bad_trigger = flyte.Trigger(
    "bad_trigger",
    flyte.Cron("0 0 * * *")
    # Missing inputs for required parameter 'data_source'
)

@env.task(triggers=bad_trigger)
def bad_trigger_taska(data_source: str, batch_size: int = 100) -> str:
    return f"Processing from {data_source} with batch size {batch_size}"

# ✅ This works - all required parameters provided
good_trigger = flyte.Trigger(
    "good_trigger",
    flyte.Cron("0 0 * * *"),
    inputs={
        "data_source": "prod_database",  # Required parameter
        "batch_size": 500  # Override default
    }
)

@env.task(triggers=good_trigger)
def good_trigger_task(data_source: str, batch_size: int = 100) -> str:
    return f"Processing from {data_source} with batch size {batch_size}"
```

### Complex input types

You can pass various data types through trigger inputs:

```
complex_trigger = flyte.Trigger(
    "ml_training",
    flyte.Cron("0 2 * * 1"),  # Weekly on Monday at 2 AM
    inputs={
        "model_config": {
            "learning_rate": 0.01,
            "batch_size": 32,
            "epochs": 100
        },
        "feature_columns": ["age", "income", "location"],
        "validation_split": 0.2,
        "training_date": flyte.TriggerTime
    }
)

@env.task(triggers=complex_trigger)
def train_model(
    model_config: dict,
    feature_columns: list[str],
    validation_split: float,
    training_date: datetime
) -> str:
    return f"Training model with {len(feature_columns)} features on {training_date}"
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

## Predefined schedule triggers

For common scheduling needs, Flyte provides predefined trigger methods that create Cron-based schedules without requiring you to specify cron expressions manually.
These are convenient shortcuts for frequently used scheduling patterns.

### Available Predefined Triggers

```
minutely_trigger = flyte.Trigger.minutely()    # Every minute
hourly_trigger = flyte.Trigger.hourly()        # Every hour
daily_trigger = flyte.Trigger.daily()          # Every day at midnight
weekly_trigger = flyte.Trigger.weekly()        # Every week (Sundays at midnight)
monthly_trigger = flyte.Trigger.monthly()      # Every month (1st day at midnight)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

For reference, here's what each predefined trigger is equivalent to:

```python
# These are functionally identical:
flyte.Trigger.minutely() == flyte.Trigger("minutely", flyte.Cron("* * * * *"))
flyte.Trigger.hourly() == flyte.Trigger("hourly", flyte.Cron("0 * * * *"))
flyte.Trigger.daily() == flyte.Trigger("daily", flyte.Cron("0 0 * * *"))
flyte.Trigger.weekly() == flyte.Trigger("weekly", flyte.Cron("0 0 * * 0"))
flyte.Trigger.monthly() == flyte.Trigger("monthly", flyte.Cron("0 0 1 * *"))
```

### Predefined Trigger Parameters

All predefined trigger methods (`minutely()`, `hourly()`, `daily()`, `weekly()`, `monthly()`) accept the same set of parameters:

```
flyte.Trigger.daily(
    trigger_time_input_key="trigger_time",
    name="daily",
    description="A trigger that runs daily at midnight",
    auto_activate=True,
    inputs=None,
    env_vars=None,
    interruptible=None,
    overwrite_cache=False,
    queue=None,
    labels=None,
    annotations=None
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

#### Core Parameters

**`trigger_time_input_key: str = "trigger_time"`**
The name of the task parameter that will receive the execution timestamp.
If no `trigger_time_input_key` is provided, the default is `trigger_time`.
In this case, if the task does not have a parameter named `trigger_time`, the task will still be executed, but, obviously, the timestamp will not be passed.
However, if you do specify a `trigger_time_input_key`, but your task does not actually have the specified parameter, an error will be raised at trigger deployment time.

**`name: str`**
The unique identifier for the trigger. Defaults to the method name (`"daily"`, `"hourly"`, etc.).

**`description: str`**
Human-readable description of the trigger's purpose. Each method has a sensible default.

#### Configuration Parameters

**`auto_activate: bool = True`**
Whether the trigger should be automatically activated when deployed. Set to `False` to deploy inactive triggers that require manual activation.

**`inputs: Dict[str, Any] | None = None`**
Additional parameter values for your task when triggered. The `trigger_time_input_key` parameter is automatically included with `flyte.TriggerTime` as its value.

#### Runtime Override Parameters

**`env_vars: Dict[str, str] | None = None`**
Environment variables to set for triggered executions, overriding the task's default environment variables.

**`interruptible: bool | None = None`**
Whether triggered executions can be interrupted (useful for cost optimization with spot/preemptible instances). Overrides the task's interruptible setting.

**`overwrite_cache: bool = False`**
Whether to bypass/overwrite task cache for triggered executions, ensuring fresh computation.

**`queue: str | None = None`**
Specific execution queue for triggered runs, overriding the task's default queue.

#### Metadata Parameters

**`labels: Mapping[str, str] | None = None`**
Key-value labels for organizing and filtering triggers (e.g., team, component, priority).

**`annotations: Mapping[str, str] | None = None`**
Additional metadata, often used by infrastructure tools for compliance, monitoring, or cost tracking.

### Trigger time in predefined triggers

By default, predefined triggers will pass the execution time to the parameter `trigger_time` of type `datetime`,if that parameter exists on the task.
If no such parameter exists, the task will still be executed without error.

Optionally, you can customize the parameter name that receives the trigger execution timestamp by setting the `trigger_time_input_key` parameter (in this case the absence of this custom parameter on the task will raise an error at trigger deployment time):

```
@env.task(triggers=flyte.Trigger.daily(trigger_time_input_key="scheduled_at"))
def task_with_custom_trigger_time_input(scheduled_at: datetime) -> str:
    return f"Executed at {scheduled_at}"
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

## Multiple triggers per task

You can attach multiple triggers to a single task by providing a list of triggers. This allows you to run the same task on different schedules or with different configurations:

```
@env.task(triggers=[
    flyte.Trigger.hourly(),  # Predefined trigger
    flyte.Trigger.daily(),   # Another predefined trigger
    flyte.Trigger("custom", flyte.Cron("0 */6 * * *"))  # Custom trigger every 6 hours
])
def multi_trigger_task(trigger_time: datetime = flyte.TriggerTime) -> str:
    # Different logic based on execution timing
    if trigger_time.hour == 0:  # Daily run at midnight
        return f"Daily comprehensive processing at {trigger_time}"
    else:  # Hourly or custom runs
        return f"Regular processing at {trigger_time.strftime('%H:%M')}"
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

You can mix and match trigger types, combining predefined triggers with those that use `flyte.Cron`, and `flyte.FixedRate` automations (see below for explanations of these concepts).

## Deploying a task with triggers

We recommend that you define your triggers in code together with your tasks and deploy them together.

The Union UI displays:

* `Owner` - who last deployed the trigger.

* `Last updated` - who last activated or deactivated the trigger and when. Note: If you deploy a trigger with `auto_activate=True`(default), this will match the `Owner`.

* `Last Run` - when was the last run created by this trigger.

For development and debugging purposes, you can adjust and deploy individual triggers from the UI.

To deploy a task with its triggers, you can either use Flyte CLI:

```bash
flyte deploy -p <project> -d <domain> <file_with_tasks_and_triggers.py> env
```

Or in Python:

```python
flyte.deploy(env)
```

Upon deploy, all triggers that are associated with a given task `T` will be automatically switched to apply to the latest version of that task. Triggers on task `T` which are defined elsewhere (i.e. in the UI) will be deleted unless they have been referenced in the task definition of `T`

<!-- TODO
Add link to workflow deployment docs when available.
-->

## Activating and deactivating triggers

By default, triggers are automatically activated upon deployment (`auto_activate=True`).
Alternatively, you can set `auto_activate=False` to deploy inactive triggers.
An inactive trigger will not create runs until activated.

```
env = flyte.TaskEnvironment(name="my_task_env")

custom_cron_trigger = flyte.Trigger(
    "custom_cron",
    flyte.Cron("0 0 * * *"),
    auto_activate=False # Dont create runs yet
)

@env.task(triggers=custom_cron_trigger)
def custom_task() -> str:
    return "Hello, world!"
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

This trigger won't create runs until it is explicitly activated.
You can activate a trigger via the Flyte CLI:

```bash
flyte update trigger custom_cron my_task_env.custom_task --activate --project <project> --domain <domain>
```

If you want to stop your trigger from creating new runs, you can deactivate it:

```bash
flyte update trigger custom_cron my_task_env.custom_task --deactivate --project <project> --domain <domain>
```

You can also view and manage your deployed triggers in the Union UI.

## Trigger run timing

The timing of the first run created by a trigger depends on the type of trigger used (Cron-based or Fixed-rate) and whether the trigger is active upon deployment.

### Cron-based triggers

For Cron-based triggers, the first run will be created at the next scheduled time according to the cron expression after trigger activation and similarly thereafter.

* `0 0 * * *` If deployed at 17:00 today, the trigger will first fire 7 hours later (0:00 of the following day) and then every day at 0:00 thereafter.

* `*/15 14 * * 1-5` if today is Tuesday at 17:00, the trigger will fire the next day (Wednesday) at 14:00, 14:15, 14:30, and 14:45 and then the same for every subsequent weekday thereafter.

### Fixed-rate triggers without `start_time`

If no `start_time` is specified, then the first run will be created after the specified interval from the time of activation. No run will be created immediately upon activation, but the activation time will be used as the reference point for future runs.

#### No `start_time`, auto_activate: True

Let's say you define a fixed rate trigger with automatic activation like this:

```
my_trigger = flyte.Trigger("my_trigger", flyte.FixedRate(60))
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

In this case, the first run will occur 60 minutes after the successful deployment of the trigger.
So, if you deployed this trigger at 13:15, the first run will occur at 14:15 and so on thereafter.

#### No `start_time`, auto_activate: False

On the other hand, let's say you define a fixed rate trigger without automatic activation like this:

```
my_trigger = flyte.Trigger("my_trigger", flyte.FixedRate(60), auto_activate=False)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

Then you activate it after about 3 hours. In this case the first run will kick off 60 minutes after trigger activation.
If you deployed the trigger at 13:15 and activated it at 16:07, the first run will occur at 17:07.

### Fixed-rate triggers with `start_time`

If a `start_time` is specified, the timing of the first run depends on whether the trigger is active at `start_time` or not.

#### Fixed-rate with `start_time` while active

If a `start_time` is specified, and the trigger is active at `start_time` then the first run will occur at `start_time` and then at the specified interval thereafter.
For example:

```
my_trigger = flyte.Trigger(
    "my_trigger",
    # Runs every 60 minutes starting from October 26th, 2025, 10:00am
    flyte.FixedRate(60, start_time=datetime(2025, 10, 26, 10, 0, 0)),
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

If you deploy this trigger on October 24th, 2025, the trigger will wait until October 26th 10:00am and will create the first run at exactly 10:00am.

#### Fixed-rate with `start_time` while inactive

If a start time is specified, but the trigger is activated after `start_time`, then the first run will be created when the next time point occurs that aligns with the recurring trigger interval using `start_time` as the initial reference point.
For example:

```
custom_rate_trigger = flyte.Trigger(
    "custom_rate",
    # Runs every 60 minutes starting from October 26th, 2025, 10:00am
    flyte.FixedRate(60, start_time=datetime(2025, 10, 26, 10, 0, 0)),
    auto_activate=False
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

If activated later than the `start_time`, say on October 28th 12:35pm for example, the first run will be created at October 28th at 1:00pm.

## Deleting triggers

If you decide that you don't need a trigger anymore, you can remove the trigger from the task definition and deploy the task again.

Alternatively, you can use Flyte CLI:

```bash
flyte delete trigger custom_cron my_task_env.custom_task --project <project> --domain <domain>
```

## Schedule time zones

### Setting time zone for a Cron schedule

Cron expressions are by default in UTC, but it's possible to specify custom time zones like so:

```
sf_trigger = flyte.Trigger(
    "sf_tz",
    flyte.Cron(
        "0 9 * * *", timezone="America/Los_Angeles"
    ), # Every day at 9 AM PT
    inputs={"start_time": flyte.TriggerTime, "x": 1},
)

nyc_trigger = flyte.Trigger(
    "nyc_tz",
    flyte.Cron(
        "1 12 * * *", timezone="America/New_York"
    ), # Every day at 12:01 PM ET
    inputs={"start_time": flyte.TriggerTime, "x": 1},
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

The above two schedules will fire 1 minute apart, at 9 AM PT and 12:01 PM ET respectively.

### `flyte.TriggerTime` is always in UTC

The `flyte.TriggerTime` value is always in UTC. For timezone-aware logic, convert as needed:

```
@env.task(triggers=flyte.Trigger.minutely(trigger_time_input_key="utc_trigger_time", name="timezone_trigger"))
def timezone_task(utc_trigger_time: datetime) -> str:
    local_time = utc_trigger_time.replace(tzinfo=timezone.utc).astimezone()
    return f"Task fired at {utc_trigger_time} UTC ({local_time} local)"
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-configuration/triggers/triggers.py*

### Daylight Savings Time behavior

When Daylight Savings Time (DST) begins and ends, it can impact when the scheduled execution begins.

On the day DST begins, time jumps from 2:00AM to 3:00AM, which means the time of 2:30AM won't exist. In this case, the trigger will not fire until the next 2:30AM, which is the next day.

On the day DST ends, the hour from 1:00AM to 2:00AM repeats, which means the time of 1:30AM will exist twice. If the schedule above was instead set for 1:30AM, it would only run once, on the first occurrence of 1:30AM.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-configuration/interruptible-tasks-and-queues ===

# Interruptible tasks and queues

## Interruptible tasks

Cloud providers offer discounted compute instances (AWS Spot Instances, GCP Preemptible VMs)
that can be reclaimed at any time. These instances are significantly cheaper than on-demand
instances but come with the risk of preemption.

Setting `interruptible=True` allows Flyte to schedule the task on these spot/preemptible instances
for cost savings:

```python
import flyte

env = flyte.TaskEnvironment(
    name="my_env",
    interruptible=True,
)

@env.task
def train_model(data: list) -> dict:
    return {"accuracy": 0.95}
```

### Setting at different levels

`interruptible` can be set at the `TaskEnvironment` level, the `@env.task` decorator level,
and at the `task.override()` invocation level. The more specific level always takes precedence.

This lets you set a default at the environment level and override per-task:

```python
import flyte

# All tasks in this environment are interruptible by default
env = flyte.TaskEnvironment(
    name="my_env",
    interruptible=True,
)

# This task uses the environment default (interruptible)
@env.task
def preprocess(data: list) -> list:
    return [x * 2 for x in data]

# This task overrides to non-interruptible (critical, should not be preempted)
@env.task(interruptible=False)
def save_results(results: dict) -> str:
    return "saved"
```

You can also override at invocation time:

```python
@env.task
async def main(data: list) -> str:
    processed = preprocess(data=data)
    # Run this specific invocation as non-interruptible
    return save_results.override(interruptible=False)(results={"data": processed})
```

### Behavior on preemption

When a spot instance is reclaimed, the task is terminated and rescheduled.
Combine `interruptible=True` with [retries](./retries-and-timeouts) to handle preemptions gracefully:

```python
@env.task(interruptible=True, retries=3)
def train_model(data: list) -> dict:
    return {"accuracy": 0.95}
```

> [!NOTE]
> Retries due to spot preemption do not count against the user-configured retry budget.
> System retries (for preemptions and other system-level failures) are tracked separately.

## Queues

Queues are named routing labels that map tasks to specific resource pools or execution clusters
in your infrastructure.

Setting a queue directs the task to the corresponding compute partition:

```python
import flyte

env = flyte.TaskEnvironment(
    name="my_env",
    queue="gpu-pool",
)

@env.task
def train_model(data: list) -> dict:
    return {"accuracy": 0.95}
```

### Setting at different levels

`queue` can be set at the `TaskEnvironment` level, the `@env.task` decorator level,
and at the `task.override()` invocation level. The more specific level takes precedence.

```python
import flyte

env = flyte.TaskEnvironment(
    name="my_env",
    queue="default-pool",
)

# Uses environment-level queue ("default-pool")
@env.task
def preprocess(data: list) -> list:
    return [x * 2 for x in data]

# Overrides to a different queue
@env.task(queue="gpu-pool")
def train_model(data: list) -> dict:
    return {"accuracy": 0.95}
```

If no queue is specified at any level, the default queue is used.

> [!NOTE]
> Queues are configured as part of your Union.ai deployment by your platform administrator.
> The available queue names depend on your infrastructure setup.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-configuration/task-plugins ===

# Task plugins

Flyte tasks are pluggable by design, allowing you to extend task execution beyond simple containers to support specialized compute frameworks and integrations.

## Default Execution: Containers

By default, Flyte tasks execute as single containers in Kubernetes. When you decorate a function with `@env.task`, Flyte packages your code into a container and runs it on the cluster. For more advanced scenarios requiring multiple containers in a single pod (such as sidecars for logging or data mounting), you can use [pod templates](./pod-templates), which allow you to customize the entire Kubernetes pod specification.

## Compute Plugins

Beyond native container execution, Flyte provides **compute plugins** that enable you to run distributed computing frameworks directly on Kubernetes. These plugins create ephemeral clusters specifically for your task execution, spinning them up on-demand and tearing them down when complete.

### Available Compute Plugins

Flyte supports several popular distributed computing frameworks through compute plugins:

- **Spark**: Run Apache Spark jobs using the Spark operator
- **Ray**: Execute Ray workloads for distributed Python applications and ML training
- **Dask**: Scale Python workflows with Dask distributed
- **PyTorch**: Run distributed training jobs using PyTorch and Kubeflow's training operator

### How Compute Plugins Work

Compute plugins create temporary, isolated clusters within the same Kubernetes environment as Flyte:

1. **Ephemeral clusters**: Each task execution gets its own cluster, spun up on-demand
2. **Kubernetes operators**: Flyte leverages specialized Kubernetes operators (Spark operator, Ray operator, etc.) to manage cluster lifecycle
3. **Native containerization**: The same container image system used for regular tasks works seamlessly with compute plugins
4. **Per-environment configuration**: You can define the cluster shape (number of workers, resources, etc.) using `plugin_config` in your `TaskEnvironment`

### Using Compute Plugins

To use a compute plugin, you need to:

1. **Install the plugin package**: Each plugin has a corresponding Python package (e.g., `flyteplugins-ray` for Ray)
2. **Configure the TaskEnvironment**: Set the `plugin_config` parameter with the plugin-specific configuration
3. **Write your task**: Use the framework's native APIs within your task function

#### Example: Ray Plugin

Here's how to run a distributed Ray task:

```python
import ray
from flyteplugins.ray.task import HeadNodeConfig, RayJobConfig, WorkerNodeConfig
import flyte

# Define your Ray computation
@ray.remote
def compute_square(x):
    return x * x

# Configure the Ray cluster
ray_config = RayJobConfig(
    head_node_config=HeadNodeConfig(ray_start_params={"log-color": "True"}),
    worker_node_config=[WorkerNodeConfig(group_name="ray-workers", replicas=2)],
    runtime_env={"pip": ["numpy", "pandas"]},
    enable_autoscaling=False,
    shutdown_after_job_finishes=True,
    ttl_seconds_after_finished=300,
)

# Create a task environment with Ray plugin configuration
image = (
    flyte.Image.from_debian_base(name="ray")
    .with_pip_packages("ray[default]==2.46.0", "flyteplugins-ray")
)

ray_env = flyte.TaskEnvironment(
    name="ray_env",
    plugin_config=ray_config,
    image=image,
    resources=flyte.Resources(cpu=(3, 4), memory=("3000Mi", "5000Mi")),
)

# Use the Ray cluster in your task
@ray_env.task
async def distributed_compute(n: int = 10) -> list[int]:
    futures = [compute_square.remote(i) for i in range(n)]
    return ray.get(futures)
```

When this task runs, Flyte will:
1. Spin up a Ray cluster with 1 head node and 2 worker nodes
2. Execute your task code in the Ray cluster
3. Tear down the cluster after completion

### Using Plugins on Union

Most compute plugins are enabled by default on Union or can be enabled upon request. Contact your Account Manager to confirm plugin availability or request specific plugins for your deployment.

## Backend Integrations

Beyond compute plugins, Flyte also supports **integrations** with external SaaS services and internal systems through **connectors**. These allow you to seamlessly interact with:

- **Data warehouses**: Snowflake, BigQuery, Redshift
- **Data platforms**: Databricks
- **Custom services**: Your internal APIs and services

Connectors enable Flyte to delegate task execution to these external systems while maintaining Flyte's orchestration, observability, and data lineage capabilities. See the **Configure tasks > Task plugins > connectors documentation** for more details on available integrations.

## Next Steps

For detailed guides on each compute plugin, including configuration options, best practices, and advanced examples, see the **Configure tasks > Task plugins > Plugins section** of the documentation. Each plugin guide covers:

- Installation and setup
- Configuration options
- Resource management
- Advanced use cases
- Troubleshooting tips


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-configuration/additional-task-settings ===

# Additional task settings

This page covers task configuration parameters that do not have their own dedicated page:
naming and metadata, default inputs, environment variables, and inline I/O thresholds.

For the full list of all task configuration parameters, see [Configure tasks](./_index).

## Naming and metadata

### `name`

The `name` parameter on `TaskEnvironment` is required.
It is combined with each task function name to form the fully-qualified task name.
For example, if you define a `TaskEnvironment` with `name="my_env"` and a task function `my_task`,
the fully-qualified task name is `my_env.my_task`.

The `name` must use `snake_case` or `kebab-case` and is immutable once set.

### `short_name`

The `short_name` parameter on `@env.task` (and `override()`) overrides the display name of a task in the UI graph view.
By default, the display name is the Python function name.
Overriding `short_name` does not change the fully-qualified task name.

```python
import flyte

env = flyte.TaskEnvironment(name="my_env")

@env.task(short_name="Train Model")
def train(data: list) -> dict:
    return {"accuracy": 0.95}
```

### `description`

The `description` parameter on `TaskEnvironment` provides a description of the task environment (max 255 characters).
It is used for organizational purposes and can be viewed in the UI.

### `docs`

The `docs` parameter on `@env.task` accepts a `Documentation` object.
If not set explicitly, the documentation is auto-extracted from the task function's docstring.

```python
import flyte
from flyte import Documentation

env = flyte.TaskEnvironment(name="my_env")

@env.task(docs=Documentation(description="Trains a model on the given dataset."))
def train(data: list) -> dict:
    """This docstring is used if docs is not set explicitly."""
    return {"accuracy": 0.95}
```

### `report`

The `report` parameter on `@env.task` controls whether an HTML report is generated for the task.
See [Reports](../task-programming/reports) for details.

### `links`

The `links` parameter on `@env.task` (and `override()`) attaches clickable URLs to tasks in the UI.
Use links to connect tasks to external tools like experiment trackers, monitoring dashboards, or logging systems.

Links are defined by implementing the [`Link`](../../api-reference/flyte-sdk/packages/flyte/link) protocol.
See [Links](../task-programming/links) for full details on creating and using links.

## Default inputs

Task functions support Python default parameter values. When a task parameter has a default, callers can omit it and the default is used.

```python
import flyte

env = flyte.TaskEnvironment(name="my_env")

@env.task
async def process(data: list, batch_size: int = 32, verbose: bool = False) -> dict:
    # batch_size defaults to 32, verbose defaults to False
    ...
```

When running via `flyte run`, parameters with defaults are optional:

```bash
# Uses defaults for batch_size and verbose
flyte run my_file.py process --data '[1, 2, 3]'

# Override a default
flyte run my_file.py process --data '[1, 2, 3]' --batch-size 64
```

When invoking programmatically, Python's normal default argument rules apply:

```python
result = flyte.run(process, data=[1, 2, 3])          # batch_size=32, verbose=False
result = flyte.run(process, data=[1, 2, 3], batch_size=64)  # override
```

Defaults are part of the task's input schema and are visible in the UI when viewing the task.

## Environment variables

The `env_vars` parameter on `TaskEnvironment` injects plain-text environment variables into the task container.
It accepts a `Dict[str, str]`.

```python
import flyte

env = flyte.TaskEnvironment(
    name="my_env",
    env_vars={
        "LOG_LEVEL": "DEBUG",
        "API_ENDPOINT": "https://api.example.com",
    },
)

@env.task
def my_task() -> str:
    import os
    return os.environ["API_ENDPOINT"]
```

Environment variables can be overridden at the `task.override()` invocation level
(unless `reusable` is in effect).

Use `env_vars` for non-sensitive configuration values.
For sensitive values like API keys and credentials, use [`secrets`](./secrets) instead.

## Inline I/O threshold

The `max_inline_io_bytes` parameter on `@env.task` (and `override()`) controls the maximum
size for data passed directly in the task request and response
(e.g., primitives, strings, dictionaries).

Data exceeding this threshold raises an `InlineIOMaxBytesBreached` error.

The default value is 10 MiB (`10 * 1024 * 1024` bytes).

This setting does **not** affect [`flyte.io.File`, `flyte.io.Dir`](../task-programming/files-and-directories),
or [`flyte.DataFrame`](../task-programming/dataclasses-and-structures),
which are always offloaded to object storage regardless of size.

```python
import flyte

env = flyte.TaskEnvironment(name="my_env")

# Allow up to 50 MiB of inline data
@env.task(max_inline_io_bytes=50 * 1024 * 1024)
def process_large_dict(data: dict) -> dict:
    return {k: v * 2 for k, v in data.items()}
```


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-programming ===

# Build tasks

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

This section covers the essential programming patterns and techniques for developing robust Flyte workflows. Once you understand the basics of task configuration, these guides will help you build sophisticated, production-ready data pipelines and machine learning workflows.

## What you'll learn

The task programming section covers key patterns for building effective Flyte workflows:

**Data handling and types**
- **Build tasks > Files and directories**: Work with large datasets using Flyte's efficient file and directory types that automatically handle data upload, storage, and transfer between tasks.
- **Build tasks > DataFrames**: Pass DataFrames between tasks without downloading data into memory, with support for Pandas, Polars, PyArrow, Dask, and other DataFrame backends.
- **Build tasks > Data classes and structures**: Use Python data classes and Pydantic models as task inputs and outputs to create well-structured, type-safe workflows.
- **Build tasks > Custom context**: Use custom context to pass metadata through your task execution hierarchy without adding parameters to every task.

**Execution patterns**
- **Build tasks > Fanout**: Scale your workflows by running many tasks in parallel, perfect for processing large datasets or running hyperparameter sweeps.
- **Build tasks > Controlling parallel execution**: Limit concurrent task executions using semaphores or `flyte.map` concurrency for rate-limited APIs, GPU quotas, and resource-constrained workflows.
- **Build tasks > Human-in-the-loop**: Pause workflow execution at a checkpoint and wait for a human to provide input or approval before continuing.
- **Build tasks > Grouping actions**: Organize related task executions into logical groups for better visualization and management in the UI.
- **Build tasks > Run a bioinformatics tool**: Run arbitrary containers in any language without the Flyte SDK installed, using Flyte's copilot sidecar for seamless data flow.
- **Build tasks > Remote tasks**: Use previously deployed tasks without importing their code or dependencies, enabling team collaboration and task reuse.
- **Configure tasks > Pod templates**: Extend tasks with Kubernetes pod templates to add sidecars, volume mounts, and advanced Kubernetes configurations.
- **Build tasks > Abort and cancel actions**: Stop in-progress actions automatically, programmatically, or manually via the CLI and UI.
- **Build tasks > Regular async function (not a task)**: Advanced patterns like task forwarding and other specialized task execution techniques.

**Development and debugging**
- **Build tasks > Notebooks**: Write and iterate on workflows directly in Jupyter notebooks for interactive development and experimentation.
- **Build tasks > Test business logic directly**: Test your Flyte tasks using direct invocation for business logic or `flyte.run()` for Flyte-specific features.
- **Build tasks > Links**: Add clickable URLs to tasks in the Flyte UI, connecting them to external tools like experiment trackers and monitoring dashboards.
- **Build tasks > Reports**: Generate custom HTML reports during task execution to display progress, results, and visualizations in the UI.
- **Build tasks > Traces**: Add fine-grained observability to helper functions within your tasks for better debugging and resumption capabilities.
- **Build tasks > Error handling**: Implement robust error recovery strategies, including automatic resource scaling and graceful failure handling.

## When to use these patterns

These programming patterns become essential as your workflows grow in complexity:

- Use **fanout** when you need to process multiple items concurrently or run parameter sweeps. Use **controlling parallel execution** when you need to limit how many run at the same time.
- Implement **error handling** for production workflows that need to recover from infrastructure failures.
- Apply **grouping** to organize complex workflows with many task executions.
- Leverage **files and directories** when working with large datasets that don't fit in memory.
- Use **DataFrames** to efficiently pass tabular data between tasks across different processing engines.
- Choose **container tasks** when you need to run code in non-Python languages, use legacy containers, or execute AI-generated code in sandboxes.
- Use **remote tasks** to reuse tasks deployed by other teams without managing their dependencies.
- Apply **pod templates** when you need advanced Kubernetes features like sidecars or specialized storage configurations.
- Use **traces** to debug non-deterministic operations like API calls or ML inference.
- Use **links** to connect tasks to external tools like Weights & Biases, Grafana, or custom dashboards directly from the Flyte UI.
- Create **reports** to monitor long-running workflows and share results with stakeholders.
- Use **custom context** when you need lightweight, cross-cutting metadata to flow through your task hierarchy without becoming part of the task's logical inputs.
- Write **unit tests** to validate your task logic and ensure type transformations work correctly before deployment.
- Use **abort and cancel** to stop unnecessary actions when conditions change, such as early convergence in HPO or manual intervention.
- Use **human-in-the-loop** to insert approval gates or data collection checkpoints into automated workflows.

Each guide includes practical examples and best practices to help you implement these patterns effectively in your own workflows.

## Subpages
- **Build tasks > Files and directories**
- **Build tasks > Data classes and structures**
- **Build tasks > DataFrames**
- **Build tasks > Custom types**
- **Build tasks > Custom context**
- **Build tasks > Abort and cancel actions**
- **Build tasks > Run a bioinformatics tool**
- **Build tasks > Links**
- **Build tasks > Reports**
- **Build tasks > Notebooks**
- **Build tasks > Remote tasks**
- **Build tasks > Error handling**
- **Build tasks > Traces**
- **Build tasks > Grouping actions**
- **Build tasks > Fanout**
- **Build tasks > Controlling parallel execution**
- **Build tasks > Human-in-the-loop**
- **Build tasks > Regular async function (not a task)**
- **Build tasks > Test business logic directly**


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-programming/files-and-directories ===

# Files and directories

Flyte provides the [`flyte.io.File`](../../api-reference/flyte-sdk/packages/flyte.io/file) and
[`flyte.io.Dir`](../../api-reference/flyte-sdk/packages/flyte.io/dir) types to represent files and directories, respectively.
Together with [`flyte.io.DataFrame`](./dataframes) they constitute the *offloaded data types* - unlike [materialized types](./dataclasses-and-structures) like data classes, these pass references rather than full data content.

A variable of an offloaded type does not contain its actual data, but rather a reference to the data.
The actual data is stored in the internal blob store of your Union/Flyte instance.
When a variable of an offloaded type is first created, its data is uploaded to the blob store.
It can then be passed from task to task as a reference.
The actual data is only downloaded from the blob stored when the task needs to access it, for example, when the task calls `open()` on a `File` or `Dir` object.

This allows Flyte to efficiently handle large files and directories without needing to transfer the data unnecessarily.
Even very large data objects like video files and DNA datasets can be passed efficiently between tasks.

The `File` and `Dir` classes provide both `sync` and `async` methods to interact with the data.

## Example usage

The examples below show the basic use-cases of uploading files and directories created locally, and using them as inputs to a task.

```
import asyncio
import tempfile
from pathlib import Path

import flyte
from flyte.io import Dir, File

env = flyte.TaskEnvironment(name="files-and-folders")

@env.task
async def write_file(name: str) -> File:

    # Create a file and write some content to it
    with open("test.txt", "w") as f:
        f.write(f"hello world {name}")

    # Upload the file using flyte
    uploaded_file_obj = await File.from_local("test.txt")
    return uploaded_file_obj
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/files-and-directories/file_and_dir.py*

The upload happens when the [`File.from_local`](../../api-reference/flyte-sdk/packages/flyte.io/file#from_local) command is called.
Because the upload would otherwise block execution, `File.from_local` is implemented as an `async` function.
The Flyte SDK frequently uses this class constructor pattern, so you will see it with other types as well.

This is a slightly more complicated task that calls the task above to produce `File` objects.

These are assembled into a directory and the `Dir` object is returned, also via invoking `from_local`.

```
@env.task
async def write_and_check_files() -> Dir:
    coros = []
    for name in ["Alice", "Bob", "Eve"]:
        coros.append(write_file(name=name))

    vals = await asyncio.gather(*coros)
    temp_dir = tempfile.mkdtemp()
    for file in vals:
        async with file.open("rb") as fh:
            contents = await fh.read()
            # Convert bytes to string
            contents_str = contents.decode('utf-8') if isinstance(contents, bytes) else str(contents)
            print(f"File {file.path} contents: {contents_str}")
            new_file = Path(temp_dir) / file.name
            with open(new_file, "w") as out:  # noqa: ASYNC230
                out.write(contents_str)
    print(f"Files written to {temp_dir}")

    # walk the directory and ls
    for path in Path(temp_dir).iterdir():
        print(f"File: {path.name}")

    my_dir = await Dir.from_local(temp_dir)
    return my_dir
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/files-and-directories/file_and_dir.py*

Finally, these tasks show how to use an offloaded type as an input.
Helper functions like `walk` and `open` have been added to the objects
and do what you might expect.

```
@env.task
async def check_dir(my_dir: Dir):
    print(f"Dir {my_dir.path} contents:")
    async for file in my_dir.walk():
        print(f"File: {file.name}")
        async with file.open("rb") as fh:
            contents = await fh.read()
            # Convert bytes to string
            contents_str = contents.decode('utf-8') if isinstance(contents, bytes) else str(contents)
            print(f"Contents: {contents_str}")

@env.task
async def create_and_check_dir():
    my_dir = await write_and_check_files()
    await check_dir(my_dir=my_dir)

if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(create_and_check_dir)
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/files-and-directories/file_and_dir.py*

## JSONL files

The `flyteplugins-jsonl` package extends `File` and `Dir` with JSONL-aware types: `JsonlFile` and `JsonlDir`. They add streaming record-level read and write on top of the standard file/directory capabilities, with optional [zstd](https://github.com/facebook/zstd) compression and automatic shard rotation for large datasets.

Records are serialized with [orjson](https://github.com/ijl/orjson) for high performance. Both types provide async and sync APIs where every read/write method has a `_sync` variant (e.g. `iter_records_sync()`, `writer_sync()`).

```bash
pip install flyteplugins-jsonl
```

### Setup

```
import flyte
from flyteplugins.jsonl import JsonlDir, JsonlFile

env = flyte.TaskEnvironment(
    name="jsonl-examples",
    image=flyte.Image.from_debian_base(name="jsonl").with_pip_packages(
        "flyteplugins-jsonl"
    ),
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/files-and-directories/jsonl.py*

### JsonlFile

`JsonlFile` is a `File` subclass for single JSONL files. Use its async context manager to write records incrementally without loading the entire dataset into memory:

```
@env.task
async def write_records() -> JsonlFile:
    """Write records to a single JSONL file."""
    out = JsonlFile.new_remote("results.jsonl")
    async with out.writer() as writer:
        for i in range(500_000):
            await writer.write({"id": i, "score": i * 0.1})
    return out
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/files-and-directories/jsonl.py*

Reading is equally streaming:

```
@env.task
async def read_records(data: JsonlFile) -> int:
    """Read records from a JsonlFile and return the count."""
    count = 0
    async for record in data.iter_records():
        count += 1
    return count
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/files-and-directories/jsonl.py*

### Compression

Both `JsonlFile` and `JsonlDir` support zstd compression transparently based on the file extension. Use `.jsonl.zst` (or `.jsonl.zstd`) to enable compression:

```
@env.task
async def write_compressed() -> JsonlFile:
    """Write a zstd-compressed JSONL file.

    Compression is activated by using a .jsonl.zst extension.
    Both reading and writing handle compression transparently.
    """
    out = JsonlFile.new_remote("results.jsonl.zst")
    async with out.writer(compression_level=3) as writer:
        for i in range(100_000):
            await writer.write({"id": i, "compressed": True})
    return out
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/files-and-directories/jsonl.py*

Reading compressed files requires no code changes; the compression format is detected automatically from the extension.

### JsonlDir

`JsonlDir` is a `Dir` subclass that shards records across multiple JSONL files (named `part-00000.jsonl`, `part-00001.jsonl`, etc.). When a shard reaches the record count or byte size threshold, a new shard is opened automatically. This keeps individual files at a manageable size even for very large datasets:

```
@env.task
async def write_large_dataset() -> JsonlDir:
    """Write a large dataset to a sharded JsonlDir.

    JsonlDir automatically rotates to a new shard file once the
    current shard reaches the record or byte limit. Shards are named
    part-00000.jsonl, part-00001.jsonl, etc.
    """
    out = JsonlDir.new_remote("dataset/")
    async with out.writer(
        max_records_per_shard=100_000,
        max_bytes_per_shard=256 * 1024 * 1024,  # 256 MB
    ) as writer:
        for i in range(500_000):
            await writer.write({"index": i, "value": i * i})
    return out
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/files-and-directories/jsonl.py*

Compressed shards are also supported by specifying the `shard_extension`:

```
@env.task
async def write_compressed_dir() -> JsonlDir:
    """Write zstd-compressed shards by specifying the shard extension."""
    out = JsonlDir.new_remote("compressed_dataset/")
    async with out.writer(
        shard_extension=".jsonl.zst",
        max_records_per_shard=50_000,
    ) as writer:
        for i in range(200_000):
            await writer.write({"id": i, "data": f"payload-{i}"})
    return out
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/files-and-directories/jsonl.py*

Reading iterates across all shards transparently. The next shard is prefetched in the background to overlap network I/O with processing:

```
@env.task
async def sum_values(dataset: JsonlDir) -> int:
    """Read all records across all shards and compute a sum.

    Iteration is transparent across shards and handles mixed
    compressed/uncompressed shards automatically. The next shard is
    prefetched in the background for higher throughput.
    """
    total = 0
    async for record in dataset.iter_records():
        total += record["value"]
    return total
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/files-and-directories/jsonl.py*

If you open a writer on a directory that already contains shards, the writer detects existing shard indices and continues from the next one, making it safe to append data to an existing `JsonlDir`.

### Error handling

All read methods accept an `on_error` parameter to control how corrupt or malformed lines are handled:

- `"raise"` (default): propagate parse errors immediately
- `"skip"`: log a warning and skip corrupt lines
- A callable `(line_number, raw_line, exception) -> None` for custom handling

```
@env.task
async def read_with_error_handling(data: JsonlFile) -> int:
    """Read records, skipping any corrupt lines instead of raising."""
    count = 0
    async for record in data.iter_records(on_error="skip"):
        count += 1
    return count

@env.task
async def read_with_custom_handler(data: JsonlFile) -> int:
    """Read records with a custom error handler that collects errors."""
    errors: list[dict] = []

    def on_error(line_number: int, raw_line: bytes, exc: Exception) -> None:
        errors.append({"line": line_number, "error": str(exc)})

    count = 0
    async for record in data.iter_records(on_error=on_error):
        count += 1
    print(f"{count} valid records, {len(errors)} errors")
    return count
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/files-and-directories/jsonl.py*

### Batch iteration

For bulk processing, both `JsonlFile` and `JsonlDir` support batched iteration. `iter_batches()` yields lists of dicts:

```
@env.task
async def process_in_batches(dataset: JsonlDir) -> int:
    """Process records in batches of dicts for bulk operations."""
    total = 0
    async for batch in dataset.iter_batches(batch_size=1000):
        # Each batch is a list[dict]
        total += len(batch)
    return total
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/files-and-directories/jsonl.py*

For analytics workloads, `iter_arrow_batches()` yields Arrow `RecordBatch` objects directly. This requires the optional `pyarrow` dependency:

```bash
pip install 'flyteplugins-jsonl[arrow]'
```

```
arrow_env = flyte.TaskEnvironment(
    name="jsonl-arrow",
    image=flyte.Image.from_debian_base(name="jsonl-arrow").with_pip_packages(
        "flyteplugins-jsonl[arrow]"
    ),
)

@arrow_env.task
async def analyze_with_arrow(dataset: JsonlDir) -> float:
    """Stream records as Arrow RecordBatches for analytics.

    Memory usage is bounded by batch_size — the full dataset is
    never loaded into memory at once.
    """
    import pyarrow as pa

    batches = []
    async for batch in dataset.iter_arrow_batches(batch_size=65_536):
        batches.append(batch)

    table = pa.Table.from_batches(batches)
    mean_value = table.column("value").to_pylist()
    return sum(mean_value) / len(mean_value)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/files-and-directories/jsonl.py*


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-programming/dataclasses-and-structures ===

# Data classes and structures

Dataclasses and Pydantic models are fully supported in Flyte as **materialized data types**:
Structured data where the full content is serialized and passed between tasks.
Use these as you would normally, passing them as inputs and outputs of tasks.

Unlike **offloaded types** like [`DataFrame`s](./dataframes), [`File`s and `Dir`s](./files-and-directories), data class and Pydantic model data is fully serialized, stored, and deserialized between tasks.
This makes them ideal for configuration objects, metadata, and smaller structured data where all fields should be serializable.

## Example: Combining Dataclasses and Pydantic Models

This example demonstrates how data classes and Pydantic models work together as materialized data types, showing nested structures and batch processing patterns:

```python
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "pydantic",
# ]
# main = "main"
# params = ""
# ///

import asyncio
from dataclasses import dataclass
from typing import List

from pydantic import BaseModel
import flyte

env = flyte.TaskEnvironment(name="ex-mixed-structures")

@dataclass
class InferenceRequest:
    feature_a: float
    feature_b: float

@dataclass
class BatchRequest:
    requests: List[InferenceRequest]
    batch_id: str = "default"

class PredictionSummary(BaseModel):
    predictions: List[float]
    average: float
    count: int
    batch_id: str

@env.task
async def predict_one(request: InferenceRequest) -> float:
    """
    A dummy linear model: prediction = 2 * feature_a + 3 * feature_b + bias(=1.0)
    """
    return 2.0 * request.feature_a + 3.0 * request.feature_b + 1.0

@env.task
async def process_batch(batch: BatchRequest) -> PredictionSummary:
    """
    Processes a batch of inference requests and returns summary statistics.
    """
    # Process all requests concurrently
    tasks = [predict_one(request=req) for req in batch.requests]
    predictions = await asyncio.gather(*tasks)

    # Calculate statistics
    average = sum(predictions) / len(predictions) if predictions else 0.0

    return PredictionSummary(
        predictions=predictions,
        average=average,
        count=len(predictions),
        batch_id=batch.batch_id
    )

@env.task
async def summarize_results(summary: PredictionSummary) -> str:
    """
    Creates a text summary from the prediction results.
    """
    return (
        f"Batch {summary.batch_id}: "
        f"Processed {summary.count} predictions, "
        f"average value: {summary.average:.2f}"
    )

@env.task
async def main() -> str:
    batch = BatchRequest(
        requests=[
            InferenceRequest(feature_a=1.0, feature_b=2.0),
            InferenceRequest(feature_a=3.0, feature_b=4.0),
            InferenceRequest(feature_a=5.0, feature_b=6.0),
        ],
        batch_id="demo_batch_001"
    )
    summary = await process_batch(batch)
    result = await summarize_results(summary)
    return result

if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(main)
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/dataclasses-and-structures/example.py*


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-programming/dataframes ===

# DataFrames

By default, return values in Python are materialized - meaning the actual data is downloaded and loaded into memory. This applies to simple types like integers, as well as more complex types like DataFrames.

To avoid downloading large datasets into memory, Flyte V2 exposes [`flyte.io.dataframe`](../../api-reference/flyte-sdk/packages/flyte.io/dataframe): a thin,  uniform wrapper type for DataFrame-style objects that allows you to pass a reference to the data, rather than the fully materialized contents.

The `flyte.io.DataFrame` type provides serialization support for common engines like `pandas`, `polars`, `pyarrow`, `dask`, etc.; enabling you to move data between different DataFrame backends.

## Setting up the environment and sample data

For our example we will start by setting up our task environment with the required dependencies and create some sample data.

```
from typing import Annotated

import numpy as np
import pandas as pd
import flyte
import flyte.io

env = flyte.TaskEnvironment(
    "dataframe_usage",
    image= flyte.Image.from_debian_base().with_pip_packages("pandas", "pyarrow", "numpy"),
    resources=flyte.Resources(cpu="1", memory="2Gi"),
)

BASIC_EMPLOYEE_DATA = {
    "employee_id": range(1001, 1009),
    "name": ["Alice", "Bob", "Charlie", "Diana", "Ethan", "Fiona", "George", "Hannah"],
    "department": ["HR", "Engineering", "Engineering", "Marketing", "Finance", "Finance", "HR", "Engineering"],
    "hire_date": pd.to_datetime(
        ["2018-01-15", "2019-03-22", "2020-07-10", "2017-11-01", "2021-06-05", "2018-09-13", "2022-01-07", "2020-12-30"]
    ),
}

ADDL_EMPLOYEE_DATA = {
    "employee_id": range(1001, 1009),
    "salary": [55000, 75000, 72000, 50000, 68000, 70000, np.nan, 80000],
    "bonus_pct": [0.05, 0.10, 0.07, 0.04, np.nan, 0.08, 0.03, 0.09],
    "full_time": [True, True, True, False, True, True, False, True],
    "projects": [
        ["Recruiting", "Onboarding"],
        ["Platform", "API"],
        ["API", "Data Pipeline"],
        ["SEO", "Ads"],
        ["Budget", "Forecasting"],
        ["Auditing"],
        [],
        ["Platform", "Security", "Data Pipeline"],
    ],
}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/dataframes/dataframes.py*

## Create a raw DataFrame

Now, let's create a task that returns a native Pandas DataFrame:

```
@env.task
async def create_raw_dataframe() -> pd.DataFrame:
    return pd.DataFrame(BASIC_EMPLOYEE_DATA)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/dataframes/dataframes.py*

This is the most basic use-case of how to pass DataFrames (of all kinds, not just Pandas).
We simply create the DataFrame as normal, and return it.

Because the task has been declared to return a supported native DataFrame type (in this case `pandas.DataFrame` Flyte will automatically detect it, serialize it correctly and upload it at task completion enabling it to be passed transparently to the next task.

Flyte supports auto-serialization for the following DataFrame types:
* `pandas.DataFrame`
* `pyarrow.Table`
* `dask.dataframe.DataFrame`
* `polars.DataFrame`
* `flyte.io.DataFrame` (see below)

## Create a flyte.io.DataFrame

Alternatively you can also create a `flyte.io.DataFrame` object directly from a native object with the `from_df` method:

```
@env.task
async def create_flyte_dataframe() -> Annotated[flyte.io.DataFrame, "parquet"]:
    pd_df = pd.DataFrame(ADDL_EMPLOYEE_DATA)
    fdf = flyte.io.DataFrame.from_df(pd_df)
    return fdf
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/dataframes/dataframes.py*

The `flyte.io.DataFrame` class creates a thin wrapper around objects of any standard DataFrame type. It serves as a generic "any DataFrame type" (a concept that Python itself does not currently offer).

As with native DataFrame types, Flyte will automatically serialize and upload the data at task completion.

The advantage of the unified `flyte.io.DataFrame` wrapper is that you can be explicit about the storage format that makes sense for your use case, by using an `Annotated` type where the second argument encodes format or other lightweight hints. For example, here we specify that the DataFrame should be stored as Parquet:

## Automatically convert between types

You can leverage Flyte to automatically download and convert the DataFrame between types when needed:

```
@env.task
async def join_data(raw_dataframe: pd.DataFrame, flyte_dataframe: pd.DataFrame) -> flyte.io.DataFrame:
    joined_df = raw_dataframe.merge(flyte_dataframe, on="employee_id", how="inner")
    return flyte.io.DataFrame.from_df(joined_df)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/dataframes/dataframes.py*

This task takes two DataFrames as input. We'll pass one raw Pandas DataFrame, and one `flyte.io.DataFrame`.
Flyte automatically converts the `flyte.io.DataFrame` to a Pandas DataFrame (since we declared that as the input type) before passing it to the task.
The actual download and conversion happens only when we access the data, in this case, when we do the merge.

## Downloading DataFrames

When a task receives a `flyte.io.DataFrame`, you can request a concrete backend representation. For example, to download as a pandas DataFrame:

```
@env.task
async def download_data(joined_df: flyte.io.DataFrame):
    downloaded = await joined_df.open(pd.DataFrame).all()
    print("Downloaded Data:\n", downloaded)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/dataframes/dataframes.py*

The `open()` call delegates to the DataFrame handler for the stored format and converts to the requested in-memory type.

## Run the example

Finally, we can define a `main` function to run the tasks defined above and a `__main__` block to execute the workflow:

```
@env.task
async def main():
    raw_df = await create_raw_dataframe ()
    flyte_df = await create_flyte_dataframe ()
    joined_df = await join_data (raw_df, flyte_df)
    await download_data (joined_df)

if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(main)
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/dataframes/dataframes.py*

## Polars DataFrames

The `flyteplugins-polars` package extends Flyte's DataFrame support to `polars.DataFrame` and `polars.LazyFrame`. Install it alongside the core SDK and it registers automatically — no additional configuration required.

```bash
pip install flyteplugins-polars
```

Both types are serialized as Parquet when passed between tasks, just like other DataFrame backends.

### Setup

```
import polars as pl

import flyte

env = flyte.TaskEnvironment(
    name="polars-dataframes",
    image=flyte.Image.from_debian_base(name="polars").with_pip_packages(
        "flyteplugins-polars>=2.0.0", "polars"
    ),
    resources=flyte.Resources(cpu="1", memory="2Gi"),
)

EMPLOYEE_DATA = {
    "employee_id": [1001, 1002, 1003, 1004, 1005, 1006],
    "name": ["Alice", "Bob", "Charlie", "Diana", "Ethan", "Fiona"],
    "department": ["Engineering", "Engineering", "Marketing", "Finance", "Finance", "Engineering"],
    "salary": [75000, 72000, 50000, 68000, 70000, 80000],
    "years_experience": [5, 4, 2, 6, 5, 7],
}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/dataframes/polars_dataframes.py*

### Eager DataFrames

Use `pl.DataFrame` when you want immediate evaluation. Flyte serializes it to Parquet on output and deserializes it on input:

```
@env.task
async def create_dataframe() -> pl.DataFrame:
    """Create a Polars DataFrame.

    Polars DataFrames are passed between tasks as serialized Parquet files
    stored in the Flyte blob store — no manual upload required.
    """
    return pl.DataFrame(EMPLOYEE_DATA)

@env.task
async def filter_high_earners(df: pl.DataFrame) -> pl.DataFrame:
    """Filter and enrich a Polars DataFrame."""
    return (
        df.filter(pl.col("salary") > 60000)
        .with_columns(
            (pl.col("salary") / pl.col("years_experience")).alias("salary_per_year")
        )
        .sort("salary", descending=True)
    )
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/dataframes/polars_dataframes.py*

### Lazy DataFrames

Use `pl.LazyFrame` when you want to defer computation and let Polars optimize the full query plan before executing. Flyte handles serialization the same way as `pl.DataFrame`:

```
@env.task
async def create_lazyframe() -> pl.LazyFrame:
    """Create a Polars LazyFrame.

    LazyFrames defer computation until collected, allowing Polars to
    optimize the full query plan. They are serialized to Parquet just
    like DataFrames when passed between tasks.
    """
    return pl.LazyFrame(EMPLOYEE_DATA)

@env.task
async def aggregate_by_department(lf: pl.LazyFrame) -> pl.DataFrame:
    """Aggregate salary statistics by department using a LazyFrame.

    The query plan is built lazily and executed only when collect() is called.
    """
    return (
        lf.group_by("department")
        .agg(
            pl.col("salary").mean().alias("avg_salary"),
            pl.col("salary").max().alias("max_salary"),
            pl.len().alias("headcount"),
        )
        .sort("avg_salary", descending=True)
        .collect()
    )
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/dataframes/polars_dataframes.py*

The `collect()` call in `aggregate_by_department` is what triggers execution of the lazy plan. The `LazyFrame` passed between tasks is serialized as Parquet at that point.

### Run the example

```
@env.task
async def main():
    df = await create_dataframe()
    filtered = await filter_high_earners(df=df)
    print("High earners:")
    print(filtered)

    lf = await create_lazyframe()
    summary = await aggregate_by_department(lf=lf)
    print("Department summary:")
    print(summary)

if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(main)
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/dataframes/polars_dataframes.py*


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-programming/handling-custom-types ===

# Custom types

Flyte has a rich type system that handles most Python types automatically. However, there are cases where you may want to pass custom types into a run or between actions. By default, if Flyte doesn't recognize a type, it uses Python pickle to serialize the data. While this works, pickle has several drawbacks:

- **Inefficiency**: Pickle can be very inefficient for certain data types
- **Language compatibility**: Pickle is Python-specific and doesn't work with other languages
- **Version fragility**: Pickled data can break between Python versions
- **Opacity**: Pickled data appears as bytes or file links in the UI, with no automatic form generation

Consider types like Polars DataFrames or PyTorch Tensors. Using pickle for these is extremely inefficient compared to native serialization formats like Parquet or tensor-specific formats.

Flyte SDK addresses this by allowing you to create and share type extensions.

## Types of extensions

Flyte supports two types of type extensions:

1. **Type transformers**: For scalar types (integers, strings, files, directories, custom objects)
2. **DataFrame extensions**: For tabular data types that benefit from DataFrame-specific handling

DataFrame types are special because they have associated metadata (columns, schemas), can be serialized to efficient formats like Parquet, support parallel uploads from engines like Spark, and can be partitioned.

## Creating a type transformer

Type transformers convert between Python types and Flyte's internal representation. Here's how to create one for a custom `PositiveInt` type.

### Step 1: Define your custom type

```python
# custom_type.py
class PositiveInt:
    """A wrapper type that only accepts positive integers."""

    def __init__(self, value: int):
        if not isinstance(value, int):
            raise TypeError(f"Expected int, got {type(value).__name__}")
        if value <= 0:
            raise ValueError(f"Expected positive integer, got {value}")
        self._value = value

    @property
    def value(self) -> int:
        return self._value

    def __repr__(self) -> str:
        return f"PositiveInt({self._value})"
```

### Step 2: Create the type transformer

```python
# transformer.py
from typing import Type

from flyteidl2.core import literals_pb2, types_pb2

from flyte import logger
from flyte.types import TypeEngine, TypeTransformer, TypeTransformerFailedError
from my_transformer.custom_type import PositiveInt

class PositiveIntTransformer(TypeTransformer[PositiveInt]):
    """
    Type transformer for PositiveInt that validates and transforms positive integers.
    """

    def __init__(self):
        super().__init__(name="PositiveInt", t=PositiveInt)

    def get_literal_type(self, t: Type[PositiveInt]) -> types_pb2.LiteralType:
        """Returns the Flyte literal type for PositiveInt."""
        return types_pb2.LiteralType(
            simple=types_pb2.SimpleType.INTEGER,
            structure=types_pb2.TypeStructure(tag="PositiveInt"),
        )

    async def to_literal(
        self,
        python_val: PositiveInt,
        python_type: Type[PositiveInt],
        expected: types_pb2.LiteralType,
    ) -> literals_pb2.Literal:
        """Converts a PositiveInt instance to a Flyte Literal."""
        if not isinstance(python_val, PositiveInt):
            raise TypeTransformerFailedError(
                f"Expected PositiveInt, got {type(python_val).__name__}"
            )

        return literals_pb2.Literal(
            scalar=literals_pb2.Scalar(
                primitive=literals_pb2.Primitive(integer=python_val.value)
            )
        )

    async def to_python_value(
        self,
        lv: literals_pb2.Literal,
        expected_python_type: Type[PositiveInt]
    ) -> PositiveInt:
        """Converts a Flyte Literal back to a PositiveInt instance."""
        if not lv.scalar or not lv.scalar.primitive:
            raise TypeTransformerFailedError(
                f"Cannot convert literal {lv} to PositiveInt: missing scalar primitive"
            )

        value = lv.scalar.primitive.integer
        try:
            return PositiveInt(value)
        except (TypeError, ValueError) as e:
            raise TypeTransformerFailedError(
                f"Cannot convert value {value} to PositiveInt: {e}"
            )

    def guess_python_type(
        self,
        literal_type: types_pb2.LiteralType
    ) -> Type[PositiveInt]:
        """Guesses the Python type from a Flyte literal type."""
        if (
            literal_type.simple == types_pb2.SimpleType.INTEGER
            and literal_type.structure
            and literal_type.structure.tag == "PositiveInt"
        ):
            return PositiveInt
        raise ValueError(f"Cannot guess PositiveInt from literal type {literal_type}")
```

### Step 3: Register the transformer

Create a registration function that can be called to register your transformer:

```python
def register_positive_int_transformer():
    """Register the PositiveIntTransformer in the TypeEngine."""
    TypeEngine.register(PositiveIntTransformer())
    logger.info("Registered PositiveIntTransformer in TypeEngine")
```

## Distributing type plugins

To share your type transformer as an installable package, configure it as a Flyte plugin using entry points.

### Configure pyproject.toml

Add the entry point to your `pyproject.toml`:

```toml
[project]
name = "my_transformer"
version = "0.1.0"
description = "Custom type transformer"
requires-python = ">=3.10"
dependencies = []

[project.entry-points."flyte.plugins.types"]
my_transformer = "my_transformer.transformer:register_positive_int_transformer"
```

The entry point group `flyte.plugins.types` tells Flyte to automatically load this transformer when the package is installed.

### Automatic loading

When your plugin package is installed, Flyte automatically loads the type transformer at runtime. This happens during `flyte.init()` or `flyte.init_from_config()`.

## Controlling plugin loading

Loading many type plugins can add overhead to initialization. You can disable automatic plugin loading:

```python
import flyte

# Disable automatic loading of type transformer plugins
flyte.init(load_plugin_type_transformers=False)
```

By default, `load_plugin_type_transformers` is `True`.

## Using custom types in tasks

Once registered, use your custom type like any built-in type:

```python
import flyte
from my_transformer.custom_type import PositiveInt

env = flyte.TaskEnvironment(name="custom_types")

@env.task
async def process_positive(value: PositiveInt) -> int:
    """Process a positive integer."""
    return value.value * 2

if __name__ == "__main__":
    flyte.init_from_config()

    # The custom type works seamlessly
    run = flyte.run(process_positive, value=PositiveInt(42))
    run.wait()
    print(run.outputs()[0])  # 84
```

## DataFrame extensions

For tabular data types, Flyte provides a specialized extension mechanism through `flyte.io.DataFrame`. DataFrame extensions support:

- Automatic conversion to/from Parquet format
- Column metadata and schema information
- Parallel uploads from distributed engines
- Partitioning support

DataFrame extensions use encoders and decoders from `flyte.io.extend`. Documentation for creating DataFrame extensions is coming soon.

## Best practices

1. **Use specific types over pickle**: Define type transformers for any custom types used frequently in your workflows
2. **Keep transformers lightweight**: Avoid expensive operations in `to_literal` and `to_python_value`
3. **Add validation**: Validate data in your transformer to catch errors early
4. **Use meaningful tags**: The `TypeStructure.tag` helps identify your type in the Flyte UI
5. **Be judicious with plugins**: Only install the plugins you need to minimize initialization overhead


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-programming/custom-context ===

# Custom context

Custom context provides a mechanism for implicitly passing configuration and metadata through your entire task execution hierarchy without adding parameters to every task. It is ideal for cross-cutting concerns such as tracing, environment metadata, or experiment identifiers.

Think of custom context as **execution-scoped metadata** that automatically flows from parent to child tasks.

## Overview

Custom context is an implicit key–value configuration map that is automatically available to tasks during execution. It is stored in the blob store of your Union/Flyte instance together with the task’s inputs, making it available across tasks without needing to pass it explicitly.

You can access it in a Flyte task via:

```python
flyte.ctx().custom_context
```

Custom context is fundamentally different from standard task inputs. Task inputs are explicit, strongly typed parameters that you declare as part of a task’s signature. They directly influence the task’s computation and therefore participate in Flyte’s caching and reproducibility guarantees.

Custom context, on the other hand, is implicit metadata. It consists only of string key/value pairs, is not part of the task signature, and does not affect task caching. Because it is injected by the Flyte runtime rather than passed as a formal input, it should be used only for environmental or contextual information, not for data that changes the logical output of a task.

## When to use it and when not to

Custom context is perfect when you need metadata, not domain data, to flow through your tasks.

Good use cases:

- Tracing IDs, span IDs
- Experiment or run metadata
- Environment region, cluster ID
- Logging correlation keys
- Feature flags
- Session IDs for 3rd-party APIs (e.g., an LLM session)

Avoid using for:

- Business/domain data
- Inputs that change task outputs
- Anything affecting caching or reproducibility
- Large blobs of data (keep it small)

It is the cleanest mechanism when you need something available everywhere, but not logically an input to the computation.

## Setting custom context

There are two ways to set custom context for a Flyte run:

1. Set it once for the entire run when you launch (`with_runcontext`) — this establishes the base context for the execution
2. Set or override it inside task code using `flyte.custom_context(...)` context manager — this changes the active context for that task block and any nested tasks called from it

Both are legitimate and complementary. The important behavioral rules to understand are:

- `with_runcontext(...)` sets the run-level base. Values provided here are available everywhere unless overridden later. Use this for metadata that should apply to most or all tasks in the run (experiment name, top-level trace id, run id, etc.).
- `flyte.custom_context(...)` is used inside task code to set or override values for that scope. It does affect nested tasks invoked while that context is active. In practice this means you can override run-level entries, add new keys for downstream tasks, or both.
- Merging & precedence: contexts are merged; when the same key appears in multiple places the most recent/innermost value wins (i.e., values set by `flyte.custom_context(...)` override the run-level values from `with_runcontext(...)` for the duration of that block).

### Run-level context

Set base metadata once when starting the run:

```
import flyte

env = flyte.TaskEnvironment("custom-context-example")

@env.task
async def leaf_task() -> str:
    # Reads run-level context
    print("leaf sees:", flyte.ctx().custom_context)
    return flyte.ctx().custom_context.get("trace_id")

@env.task
async def root() -> str:
    return await leaf_task()

if __name__ == "__main__":
    flyte.init_from_config()
    # Base context for the entire run
    flyte.with_runcontext(custom_context={"trace_id": "root-abc", "experiment": "v1"}).run(root)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/custom-context/run_context.py*

Output (every task sees the base keys unless overridden):

```bash
leaf sees: {"trace_id": "root-abc", "experiment": "v1"}
```

### Overriding inside a task (local override that affects nested tasks)

Use `flyte.custom_context(...)` inside a task to override or add keys for downstream calls:

```
@env.task
async def downstream() -> str:
    print("downstream sees:", flyte.ctx().custom_context)
    return flyte.ctx().custom_context.get("trace_id")

@env.task
async def parent() -> str:
    print("parent initial:", flyte.ctx().custom_context)

    # Override the trace_id for the nested call(s)
    with flyte.custom_context(trace_id="child-override"):
        val = await downstream()     # downstream sees trace_id="child-override"

    # After the context block, run-level values are back
    print("parent after:", flyte.ctx().custom_context)
    return val
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/custom-context/override_context.py*

If the run was started with `{"trace_id": "root-abc"}`, this prints:

```bash
parent initial: {"trace_id": "root-abc"}
downstream sees: {"trace_id": "child-override"}
parent after: {"trace_id": "root-abc"}
```

Note that the override affected the nested downstream task because it was invoked while the `flyte.custom_context` block was active.

### Adding new keys for nested tasks

You can add keys (not just override):

```python
with flyte.custom_context(experiment="exp-blue", run_group="g-7"):
    await some_task()   # some_task sees both base keys + the new keys
```

## Accessing custom context

Always via the Flyte runtime:

```python
ctx = flyte.ctx().custom_context
value = ctx.get("key")
```

You can access the custom context using either `flyte.ctx().custom_context` or the shorthand `flyte.get_custom_context()`, which returns the same dictionary of key/value pairs.

Values are always strings, so parse as needed:

```python
timeout = int(ctx["timeout_seconds"])
```


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-programming/abort-tasks ===

# Abort and cancel actions

When running complex workflows, you may need to stop actions that are no longer needed.
This can happen when one branch of your workflow makes others redundant, when a task fails and its siblings should not continue, or when you need to manually intervene in a running workflow.

Flyte provides three mechanisms for stopping actions:

- **Automatic cleanup**: When a root action completes, all its in-progress descendant actions are automatically aborted.
- **Programmatic cancellation**: Cancel specific `asyncio` tasks from within your workflow code.
- **External abort**: Stop individual actions via the CLI, the UI, or the API.

For background on runs and actions, see [Runs and actions](../core-concepts/runs-and-actions).

## Action lifetime

The lifetime of all actions in a [run](../core-concepts/runs-and-actions) is tied to the lifetime of the root action (the first task that was invoked).
When the root action exits—whether it succeeds, fails, or returns early—all in-progress descendant actions are automatically aborted and no new actions can be enqueued.

This means you don't need to manually clean up child actions. Flyte handles it for you.

Consider this example where `main` exits after 10 seconds, but it has spawned a `sleep_for` action that is set to run for 30 seconds:

```python
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# main = "main"
# params = "seconds = 30"
# ///

import asyncio

import flyte

env = flyte.TaskEnvironment(name="action_lifetime")

@env.task
async def do_something():
    print("Doing something")
    await asyncio.sleep(5)
    print("Finished doing something")

@env.task
async def sleep_for(seconds: int):
    print(f"Sleeping for {seconds} seconds")
    try:
        await asyncio.sleep(seconds)
        await do_something()
    except asyncio.CancelledError:
        print("sleep_for was cancelled")
        return
    print(f"Finished sleeping for {seconds} seconds")

@env.task
async def main(seconds: int):
    print("Starting main")
    asyncio.create_task(sleep_for(seconds))
    await asyncio.sleep(10)
    print("Main finished")

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main, seconds=30)
    print(run.url)
    run.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/abort-tasks/action_lifetime.py*

When `main` returns after 10 seconds, the `sleep_for` action (which still has 20 seconds remaining) is automatically aborted.
The `sleep_for` task receives an `asyncio.CancelledError`, giving it a chance to handle the cancellation gracefully.

## Canceling actions programmatically

As a workflow author, you can cancel specific in-progress actions by canceling their corresponding `asyncio` tasks.
This is useful in scenarios like hyperparameter optimization (HPO), where one action converges to the desired result and the remaining actions can be stopped to save compute.

To cancel actions programmatically:

1. Launch actions using `asyncio.create_task()` and retain references to the returned task objects.
2. When the desired condition is met, call `.cancel()` on the tasks you want to stop.

```python
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# main = "main"
# params = "n = 30, f = 10.0"
# ///

import asyncio

import flyte
import flyte.errors

env = flyte.TaskEnvironment("cancel")

@env.task
async def sleepers(f: float, n: int):
    await asyncio.sleep(f)

@env.task
async def failing_task(f: float):
    raise ValueError("I will fail!")

@env.task
async def main(n: int, f: float):
    sleeping_tasks = []
    for i in range(n):
        sleeping_tasks.append(asyncio.create_task(sleepers(f, i)))

    await asyncio.sleep(f)
    try:
        await failing_task(f)
        await asyncio.gather(*sleeping_tasks)
    except flyte.errors.RuntimeUserError as e:
        if e.code == "ValueError":
            print(f"Received ValueError, canceling {len(sleeping_tasks)} sleeping tasks")
            for t in sleeping_tasks:
                t.cancel()
        return

if __name__ == "__main__":
    flyte.init_from_config()
    print(flyte.run(main, 30, 10.0))
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/abort-tasks/cancel_tasks.py*

In this code:

* The `main` task launches 30 `sleepers` actions in parallel using `asyncio.create_task()`.
* It then calls `failing_task`, which raises a `ValueError`.
* The error is caught as a `flyte.errors.RuntimeUserError` (since user-raised exceptions are wrapped by Flyte).
* On catching the error, `main` cancels all sleeping tasks by calling `.cancel()` on each one, freeing their compute resources.

This pattern lets you react to runtime conditions and stop unnecessary work. For more on handling errors within workflows, see [Error handling](./error-handling).

## External abort

Sometimes you need to stop an action manually, outside the workflow code itself. You can abort individual actions using the CLI, the UI, or the API.

When an action is externally aborted, the parent action that awaits it receives a [`flyte.errors.ActionAbortedError`](../../api-reference/flyte-sdk/packages/flyte.errors/actionabortederror). You can catch this error to handle the abort gracefully.

### Aborting via the CLI

To abort a specific action:

```bash
flyte abort <run-name> <action-name>
```

Use `--project` and `--domain` to target a specific [project-domain pair](../projects-and-domains).
For all available options, see the [CLI reference](../../api-reference/flyte-cli#flyte-abort).

### Handling external aborts

When using `asyncio.gather()` with `return_exceptions=True`, externally aborted actions return an `ActionAbortedError` instead of raising it. This lets you inspect results and handle aborts on a per-action basis:

```python
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# main = "main"
# params = "n = 10, sleep_for = 30.0"
# ///

import asyncio

import flyte
import flyte.errors

env = flyte.TaskEnvironment("external_abort")

@env.task
async def long_sleeper(sleep_for: float):
    await asyncio.sleep(sleep_for)

@env.task
async def main(n: int, sleep_for: float) -> str:
    coros = [long_sleeper(sleep_for) for _ in range(n)]
    results = await asyncio.gather(*coros, return_exceptions=True)
    for i, r in enumerate(results):
        if isinstance(r, flyte.errors.ActionAbortedError):
            print(f"Action [{i}] was externally aborted")
    return "Hello World!"

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main, 10, 30.0)
    print(run.url)
    run.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/abort-tasks/external_abort.py*

In this code:

* The `main` task launches 10 `long_sleeper` actions in parallel.
* If any action is externally aborted (via the CLI, the UI, or the API) while running, `asyncio.gather` captures the `ActionAbortedError` as a result instead of propagating it.
* The `main` task iterates over the results and logs which actions were aborted.
* Because the abort is handled, `main` can continue executing and return its result normally.

Without `return_exceptions=True`, an external abort would raise `ActionAbortedError` directly, which you can handle with a standard `try...except` block.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-programming/container-tasks ===

Container tasks are one of Flyte's superpowers. They allow you to execute tasks using any container image without requiring the Flyte SDK to be installed in that container. This means you can run code written in any language, execute shell scripts, or even use pre-built containers pulled directly from the internet while still maintaining Flyte's data orchestration capabilities.

## What are Container Tasks?

A container task is a special type of Flyte task that executes arbitrary container images. Unlike standard `@task` decorated functions that require the Flyte SDK, container tasks can run:

- Code written in any programming language (Rust, Go, Java, R, etc.)
- Legacy containers with unsupported Python versions
- Pre-built bioinformatics or scientific computing containers
- Shell scripts and command-line tools
- Dynamically generated code in sandboxed environments

## How Data Flows In and Out

The magic of container tasks lies in Flyte's **copilot sidecar system**. When you execute a container task, Flyte:

1. Launches your specified container alongside a copilot sidecar container
2. Uses shared Kubernetes pod volumes to pass data between containers
3. Reads inputs from `input_data_dir` and writes outputs to `output_data_dir`
4. Automatically handles serialization and deserialization of typed data

This means you can construct workflows where some tasks are container tasks while others are Python functions, and data will flow seamlessly between them.

## Basic Usage

Here's a simple example that runs a shell command in an Alpine container:

```python
import flyte
from flyte.extras import ContainerTask

greeting_task = ContainerTask(
    name="echo_and_return_greeting",
    image=flyte.Image.from_base("alpine:3.18"),
    input_data_dir="/var/inputs",
    output_data_dir="/var/outputs",
    inputs={"name": str},
    outputs={"greeting": str},
    command=[
        "/bin/sh",
        "-c",
        "echo 'Hello, my name is {{.inputs.name}}.' | tee -a /var/outputs/greeting"
    ],
)
```

### Template Syntax for Inputs

Container tasks support template-style references to inputs using the syntax `{{.inputs.<input_name>}}`. This gets replaced with the actual input value at runtime:

```python
command=["/bin/sh", "-c", "echo 'Processing {{.inputs.user_id}}' > /var/outputs/result"]
```

### Using Container Tasks in Workflows

Container tasks integrate seamlessly with Python tasks:

```python
container_env = flyte.TaskEnvironment.from_task("container_env", greeting_task)
env = flyte.TaskEnvironment(name="hello_world", depends_on=[container_env])

@env.task
async def say_hello(name: str = "flyte") -> str:
    print("Hello container task")
    return await greeting_task(name=name)
```

## Advanced: Passing Files and Directories

Container tasks can accept `File` and `Dir` inputs. For these types, use path-based syntax (not template syntax) in your commands:

```python
from flyte.io import File
import pathlib

code_runner = ContainerTask(
    name="python_code_runner",
    image="ghcr.io/astral-sh/uv:debian-slim",
    input_data_dir="/var/inputs",
    output_data_dir="/var/outputs",
    inputs={"script.py": File, "a": int, "b": int},
    outputs={"result": int},
    command=[
        "/bin/sh",
        "-c",
        "uv run /var/inputs/script.py {{.inputs.a}} {{.inputs.b}} > /var/outputs/result"
    ],
)

@env.task
async def execute_script() -> int:
    path = pathlib.Path(__file__).parent / "my_script.py"
    script_file = await File.from_local(path)
    return await code_runner(**{"script.py": script_file, "a": 10, "b": 20})
```

Note that when passing files, the input key can include the filename (e.g., `"script.py"`), and you reference it in the command as `/var/inputs/script.py`.

## Use Case: Agentic Sandbox Execution

Container tasks are perfect for running AI-generated code in isolated environments. You can generate a data analysis script dynamically and execute it safely:

```python
import flyte
from flyte.extras import ContainerTask
from flyte.io import File
import pathlib

env = flyte.TaskEnvironment(name="agentic_sandbox")

@env.task
async def run_generated_code(script_content: str, param_a: int, param_b: int) -> int:
    # Define a container task that runs arbitrary Python code
    sandbox = ContainerTask(
        name="code_sandbox",
        image="ghcr.io/astral-sh/uv:debian-slim",
        input_data_dir="/var/inputs",
        output_data_dir="/var/outputs",
        inputs={"script": File, "a": int, "b": int},
        outputs={"result": int},
        command=[
            "/bin/sh",
            "-c",
            "uv run --script /var/inputs/script {{.inputs.a}} {{.inputs.b}} > /var/outputs/result"
        ],
    )

    # Save the generated script to a temporary file
    temp_path = pathlib.Path("/tmp/generated_script.py")
    temp_path.write_text(script_content)

    # Execute it in the sandbox
    script_file = await File.from_local(temp_path)
    return await sandbox(script=script_file, a=param_a, b=param_b)
```

This pattern allows you to:
- Generate code using LLMs or other AI systems
- Execute it in a controlled, isolated environment
- Capture results and integrate them back into your workflow
- Maintain full observability and reproducibility

## Use Case: Legacy and Specialized Containers

Many scientific and bioinformatics tools are distributed as pre-built containers. Container tasks let you integrate them directly:

```python
# Run a bioinformatics tool
blast_task = ContainerTask(
    name="run_blast",
    image="ncbi/blast:latest",
    input_data_dir="/data",
    output_data_dir="/results",
    inputs={"query": File, "database": str},
    outputs={"alignments": File},
    command=[
        "blastn",
        "-query", "/data/query",
        "-db", "{{.inputs.database}}",
        "-out", "/results/alignments",
        "-outfmt", "6"
    ],
)

# Run legacy code with an old Python version
legacy_task = ContainerTask(
    name="legacy_python",
    image="python:2.7",  # Unsupported Python version
    input_data_dir="/app/inputs",
    output_data_dir="/app/outputs",
    inputs={"data_file": File},
    outputs={"processed": File},
    command=[
        "python",
        "/legacy_app/process.py",
        "/app/inputs/data_file",
        "/app/outputs/processed"
    ],
)
```

## Use Case: Multi-Language Workflows

Build workflows that span multiple languages:

```python
# Rust task for high-performance computation
rust_task = ContainerTask(
    name="rust_compute",
    image="rust:1.75",
    inputs={"n": int},
    outputs={"result": int},
    input_data_dir="/inputs",
    output_data_dir="/outputs",
    command=["./compute_binary", "{{.inputs.n}}"],
)

# Python task for orchestration
@env.task
async def multi_lang_workflow(iterations: int) -> dict:
    # Call Rust task for heavy computation
    computed = await rust_task(n=iterations)

    # Process results in Python
    processed = await python_analysis_task(computed)

    return {"rust_result": computed, "analysis": processed}
```

## Configuration Options

### ContainerTask Parameters

- **name**: Unique identifier for the task
- **image**: Container image to use (string or `Image` object)
- **command**: Command to execute in the container (list of strings)
- **inputs**: Dictionary mapping input names to types
- **outputs**: Dictionary mapping output names to types
- **input_data_dir**: Directory where Flyte writes input data (default: `/var/inputs`)
- **output_data_dir**: Directory where Flyte reads output data (default: `/var/outputs`)
- **arguments**: Additional command arguments (list of strings)
- **metadata_format**: Format for metadata serialization (`"JSON"`, `"YAML"`, or `"PROTO"`)
- **local_logs**: Whether to print container logs during local execution (default: `True`)

### Supported Input/Output Types

Container tasks support all standard Flyte types:

- Primitives: `str`, `int`, `float`, `bool`
- Temporal: `datetime.datetime`, `datetime.timedelta`
- File system: `File`, `Dir`
- Complex types: dataclasses, Pydantic models (serialized as JSON/YAML/PROTO)

## Best Practices

1. **Use specific image tags**: Prefer `alpine:3.18` over `alpine:latest` for reproducibility
2. **Keep containers focused**: Each container task should do one thing well
3. **Handle errors gracefully**: Ensure your container commands exit with appropriate status codes
4. **Test locally first**: Container tasks can run locally with Docker, making debugging easier
5. **Consider image size**: Smaller images lead to faster task startup times
6. **Document input/output contracts**: Clearly specify what data flows in and out

## Local Execution

Container tasks require Docker to be installed and running on your local machine. When you run them locally, Flyte will:

1. Pull the specified image (if not already available)
2. Mount local directories for inputs and outputs
3. Stream container logs to your console
4. Extract outputs after container completion

This makes it easy to develop and test container tasks before deploying to a remote cluster.

## When to Use Container Tasks

Choose container tasks when you need to:

- Run code in languages other than Python
- Execute pre-built tools or legacy applications
- Isolate potentially unsafe code (AI-generated scripts)
- Use specific runtime environments or dependencies
- Integrate external tools without Python wrappers
- Execute shell scripts or command-line utilities

For Python code that can use the Flyte SDK, standard `@task` decorated functions are usually simpler and more efficient.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-programming/links ===

# Links

Links let you add clickable URLs to tasks that appear in the Flyte UI. Use them to connect tasks to external tools like experiment trackers, monitoring dashboards or custom internal services.

![Links in the Flyte UI](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/integrations/wandb/single_node_auto_flyte.png)

You can attach links to tasks in two ways:

- **Statically** in the task decorator with `links=`
- **Dynamically** at call time with `task.override(links=...)`

`Link` is a Python [Protocol](https://docs.python.org/3/library/typing.html#typing.Protocol) that you subclass to define how URLs are generated. The Weights & Biases plugin provides a [built-in link implementation](../../api-reference/integrations/wandb/packages/flyteplugins.wandb/wandb) as an example.

## Creating a link

To create a link, subclass `Link` as a dataclass and implement the `get_link()` method. The method returns the URL string to display in the UI:

```python
from dataclasses import dataclass

import flyte
from flyte import Link

@dataclass
class GrafanaLink(Link):
    dashboard_url: str
    name: str = "Grafana"

    def get_link(
        self,
        run_name: str,
        project: str,
        domain: str,
        context: dict,
        parent_action_name: str,
        action_name: str,
        pod_name: str,
        **kwargs,
    ) -> str:
        return f"{self.dashboard_url}?var-pod={pod_name}"

env = flyte.TaskEnvironment(...)

@env.task(links=(GrafanaLink(dashboard_url="https://grafana.example.com/d/abc123"),))
def my_task() -> str:
    return "done"
```

The link appears as a clickable "Grafana" link in the Flyte UI for every execution of `my_task`.

## Using execution metadata

The `get_link()` method receives execution metadata that you can use to construct dynamic URLs. Here's an example modeled on the [built-in Wandb](../../integrations/wandb/_index) link that uses the `context` dict to resolve a run ID:

```python
from dataclasses import dataclass
from typing import Optional

from flyte import Link

@dataclass
class Wandb(Link):
    project: str
    entity: str
    id: Optional[str] = None
    name: str = "Weights & Biases"

    def get_link(
        self,
        run_name: str,
        project: str,
        domain: str,
        context: dict[str, str],
        parent_action_name: str,
        action_name: str,
        pod_name: str,
        **kwargs,
    ) -> str:
        run_id = self.id or context.get("wandb_id", run_name)
        return f"https://wandb.ai/{self.entity}/{self.project}/runs/{run_id}"
```

The `name` attribute controls the display label in the UI.

See the [`get_link()` API reference](../../api-reference/flyte-sdk/packages/flyte/link#get_link) for more details. Note that `action_name` and `pod_name` are template variables (`{{.actionName}}` and `{{.podName}}`) that are populated by the backend at runtime.

## Dynamic links with override

Use `task.override(links=...)` to set links at runtime. This is useful when link parameters depend on runtime values like run IDs or configuration:

```python
import os

import flyte
from flyteplugins.wandb import Wandb

env = flyte.TaskEnvironment(...)

WANDB_PROJECT = "my-ml-project"
WANDB_ENTITY = "my-team"

@env.task
def train_model(config: dict) -> dict:
    # Training logic here
    return {"accuracy": 0.95}

@env.task
async def main(wandb_id: str) -> dict:
    result = train_model.override(
        links=(
            Wandb(
                project=WANDB_PROJECT,
                entity=WANDB_ENTITY,
                id=wandb_id,
            ),
        )
    )(config={"lr": 0.001})

    return result

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main, wandb_id="my-run-id")
```

The `override` approach lets you attach links with values that are only known at runtime, such as dynamically generated run IDs.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-programming/reports ===

# Reports

The reports feature allows you to display and update custom output in the UI during task execution.

First, you set the `report=True` flag in the task decorator. This enables the reporting feature for that task.
Within a task with reporting enabled, a [`flyte.report.Report`](../../api-reference/flyte-sdk/packages/flyte.report/report) object is created automatically.

A `Report` object contains one or more tabs, each of which contains HTML.
You can write HTML to an existing tab and create new tabs to organize your content.
Initially, the `Report` object has one tab (the default tab) with no content.

To write content:

- [`flyte.report.log()`](../../api-reference/flyte-sdk/packages/flyte.report/_index#log) appends HTML content directly to the default tab.
- [`flyte.report.replace()`](../../api-reference/flyte-sdk/packages/flyte.report/_index#replace) replaces the content of the default tab with new HTML.

To get or create a new tab:

- [`flyte.report.get_tab()`](../../api-reference/flyte-sdk/packages/flyte.report/_index#get_tab) allows you to specify a unique name for the tab, and it will return the existing tab if it already exists or create a new one if it doesn't.
  It returns a `flyte.report._report.Tab`

You can `log()` or `replace()` HTML on the `Tab` object just as you can directly on the `Report` object.

Finally, you send the report to the Flyte server and make it visible in the UI:

- [`flyte.report.flush()`](../../api-reference/flyte-sdk/packages/flyte.report/_index#flush) dispatches the report.
  **It is important to call this method to ensure that the data is sent**.

<!-- TODO:
Check (test) if implicit flush is performed at the end of the task execution.
-->

## A simple example

```python
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# main = "main"
# params = ""
# ///

import flyte
import flyte.report

env = flyte.TaskEnvironment(name="reports_example")

@env.task(report=True)
async def task1():
    await flyte.report.replace.aio("<p>The quick, brown fox jumps over a lazy dog.</p>")
    tab2 = flyte.report.get_tab("Tab 2")
    tab2.log("<p>The quick, brown dog jumps over a lazy fox.</p>")
    await flyte.report.flush.aio()

if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(task1)
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/reports/simple.py*

Here we define a task `task1` that logs some HTML content to the default tab and creates a new tab named "Tab 2" where it logs additional HTML content.
The `flush` method is called to send the report to the backend.

## A more complex example

Here is another example.
We import the necessary modules, set up the task environment, define the main task with reporting enabled and define the data generation function:

```
import json
import random

import flyte
import flyte.report

env = flyte.TaskEnvironment(
    name="globe_visualization",
)

@env.task(report=True)
async def generate_globe_visualization():
    await flyte.report.replace.aio(get_html_content())
    await flyte.report.flush.aio()

def generate_globe_data():
    """Generate sample data points for the globe"""
    cities = [
        {"city": "New York", "country": "USA", "lat": 40.7128, "lng": -74.0060},
        {"city": "London", "country": "UK", "lat": 51.5074, "lng": -0.1278},
        {"city": "Tokyo", "country": "Japan", "lat": 35.6762, "lng": 139.6503},
        {"city": "Sydney", "country": "Australia", "lat": -33.8688, "lng": 151.2093},
        {"city": "Paris", "country": "France", "lat": 48.8566, "lng": 2.3522},
        {"city": "São Paulo", "country": "Brazil", "lat": -23.5505, "lng": -46.6333},
        {"city": "Mumbai", "country": "India", "lat": 19.0760, "lng": 72.8777},
        {"city": "Cairo", "country": "Egypt", "lat": 30.0444, "lng": 31.2357},
        {"city": "Moscow", "country": "Russia", "lat": 55.7558, "lng": 37.6176},
        {"city": "Beijing", "country": "China", "lat": 39.9042, "lng": 116.4074},
        {"city": "Lagos", "country": "Nigeria", "lat": 6.5244, "lng": 3.3792},
        {"city": "Mexico City", "country": "Mexico", "lat": 19.4326, "lng": -99.1332},
        {"city": "Bangkok", "country": "Thailand", "lat": 13.7563, "lng": 100.5018},
        {"city": "Istanbul", "country": "Turkey", "lat": 41.0082, "lng": 28.9784},
        {"city": "Buenos Aires", "country": "Argentina", "lat": -34.6118, "lng": -58.3960},
        {"city": "Cape Town", "country": "South Africa", "lat": -33.9249, "lng": 18.4241},
        {"city": "Dubai", "country": "UAE", "lat": 25.2048, "lng": 55.2708},
        {"city": "Singapore", "country": "Singapore", "lat": 1.3521, "lng": 103.8198},
        {"city": "Stockholm", "country": "Sweden", "lat": 59.3293, "lng": 18.0686},
        {"city": "Vancouver", "country": "Canada", "lat": 49.2827, "lng": -123.1207},
    ]

    categories = ["high", "medium", "low", "special"]

    data_points = []
    for city in cities:
        data_point = {**city, "value": random.randint(10, 100), "category": random.choice(categories)}
        data_points.append(data_point)

    return data_points
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/reports/globe_visualization.py*

We then define the HTML content for the report:

```python
def get_html_content():
    data_points = generate_globe_data()

    html_content = f"""
    <!DOCTYPE html>
    <html lang="en">
    ...
    </html>
    return html_content
"""
```

(We exclude it here due to length. You can find it in the [source file](https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/reports/globe_visualization.py)).

Finally, we run the workflow:

```
if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(generate_globe_visualization)
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/reports/globe_visualization.py*

When the workflow runs, the report will be visible in the UI:

![Globe visualization](https://raw.githubusercontent.com/unionai/unionai-docs-static/main/images/user-guide/globe_visualization.png)

## Streaming example

Above we demonstrated reports that are sent to the UI once, at the end of the task execution.
But, you can also stream updates to the report during task execution and see the display update in real-time.

You do this by calling `flyte.report.flush()` (or specifying `do_flush=True` in `flyte.report.log()`) periodically during the task execution, instead of just at the end of the task execution

> [!NOTE]
> In the above examples we explicitly call `flyte.report.flush()` to send the report to the UI.
> In fact, this is optional since flush will be called automatically at the end of the task execution.
> For streaming reports, on the other hand, calling `flush()` periodically (or specifying `do_flush=True`
> in `flyte.report.log()`) is necessary to display the updates.

First we import the necessary modules, and set up the task environment:

```
import asyncio
import json
import math
import random
import time
from datetime import datetime
from typing import List

import flyte
import flyte.report

env = flyte.TaskEnvironment(name="streaming_reports")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/reports/streaming_reports.py*

Next we define the HTML content for the report:

```python
DATA_PROCESSING_DASHBOARD_HTML = """
...
"""
```

(We exclude it here due to length. You can find it in the [source file](
https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/reports/streaming_reports.py)).

Finally, we define the task that renders the report (`data_processing_dashboard`), the driver task of the workflow (`main`), and the run logic:

```
@env.task(report=True)
async def data_processing_dashboard(total_records: int = 50000) -> str:
    """
    Simulates a data processing pipeline with real-time progress visualization.
    Updates every second for approximately 1 minute.
    """
    await flyte.report.log.aio(DATA_PROCESSING_DASHBOARD_HTML, do_flush=True)

    # Simulate data processing
    processed = 0
    errors = 0
    batch_sizes = [800, 850, 900, 950, 1000, 1050, 1100]  # Variable processing rates

    start_time = time.time()

    while processed < total_records:
        # Simulate variable processing speed
        batch_size = random.choice(batch_sizes)

        # Add some processing delays occasionally
        if random.random() < 0.1:  # 10% chance of slower batch
            batch_size = int(batch_size * 0.6)
            await flyte.report.log.aio("""
            <script>addActivity("⚠️ Detected slow processing batch, optimizing...");</script>
            """, do_flush=True)
        elif random.random() < 0.05:  # 5% chance of error
            errors += random.randint(1, 5)
            await flyte.report.log.aio("""
            <script>addActivity("❌ Processing errors detected, retrying failed records...");</script>
            """, do_flush=True)
        else:
            await flyte.report.log.aio(f"""
            <script>addActivity("✅ Successfully processed batch of {batch_size} records");</script>
            """, do_flush=True)

        processed = min(processed + batch_size, total_records)
        current_time = time.time()
        elapsed = current_time - start_time
        rate = int(batch_size) if elapsed < 1 else int(processed / elapsed)
        success_rate = ((processed - errors) / processed) * 100 if processed > 0 else 100

        # Update dashboard
        await flyte.report.log.aio(f"""
        <script>
            updateDashboard({processed}, {total_records}, {rate}, {success_rate});
        </script>
        """, do_flush=True)

        print(f"Processed {processed:,} records, Errors: {errors}, Rate: {rate:,}"
              f" records/sec, Success Rate: {success_rate:.2f}%", flush=True)
        await asyncio.sleep(1)  # Update every second

        if processed >= total_records:
            break

    # Final completion message
    total_time = time.time() - start_time
    avg_rate = int(total_records / total_time)

    await flyte.report.log.aio(f"""
    <script>addActivity("🎉 Processing completed successfully!");</script>
    <div style="background-color: #d4edda; border: 1px solid #c3e6cb; color: #155724; padding: 20px; border-radius: 8px; margin-top: 20px;">
        <h3>🎉 Processing Complete!</h3>
        <ul>
            <li><strong>Total Records:</strong> {total_records:,}</li>
            <li><strong>Processing Time:</strong> {total_time:.1f} seconds</li>
            <li><strong>Average Rate:</strong> {avg_rate:,} records/second</li>
            <li><strong>Success Rate:</strong> {success_rate:.2f}%</li>
            <li><strong>Errors Handled:</strong> {errors}</li>
        </ul>
    </div>
    """, do_flush=True)
    print(f"Data processing completed: {processed:,} records processed with {errors} errors.", flush=True)

    return f"Processed {total_records:,} records successfully"

@env.task
async def main():
    """
    Main task to run both reports.
    """
    await data_processing_dashboard(total_records=50000)

if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(main)
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/reports/streaming_reports.py*

The key to the live update ability is the `while` loop that appends Javascript to the report. The Javascript calls execute on append to the document and update it.

When the workflow runs, you can see the report updating in real-time in the UI:

![Data Processing Dashboard](https://raw.githubusercontent.com/unionai/unionai-docs-static/main/images/user-guide/data_processing_dashboard.png)


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-programming/notebooks ===

# Notebooks

Flyte is designed to work seamlessly with Jupyter notebooks, allowing you to write and execute workflows directly within a notebook environment.

## Iterating on and running a workflow

Download the following notebook file and open it in your favorite Jupyter environment: [interactive.ipynb](../../_static/public/interactive.ipynb)

<!-- TODO: add back when working
📥 [interactive.ipynb](/_static/public/interactive.ipynb)
-->

In this example we have a simple workflow defined in our notebook.
You can iterate on the code in the notebook while running each cell in turn.

Note that the [`flyte.init()`](../../api-reference/flyte-sdk/packages/flyte/_index#init) call at the top of the notebook looks like this:

```python
flyte.init(
    endpoint="https://union.example.com",
    org="example_org",
    project="example_project",
    domain="development",
)
```

You will have to adjust it to match your Union server endpoint, organization, project, and domain.

## Accessing runs and downloading logs

Similarly, you can download the following notebook file and open it in your favorite Jupyter environment: [remote.ipynb](../../_static/public/remote.ipynb)

<!-- TODO: add back when working
📥 [remote.ipynb](/_static/public/remote.ipynb)
-->

In this example we use the `flyte.remote` package to list existing runs, access them, and download their details and logs.

For a comprehensive guide on working with runs, actions, inputs, and outputs, see [Interact with runs and actions](../task-deployment/interacting-with-runs).


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-programming/remote-tasks ===

# Remote tasks

Remote tasks let you use previously deployed tasks without importing their code or dependencies. This enables teams to share and reuse tasks without managing complex dependency chains or container images.

## Prerequisites

Remote tasks must be deployed before you can use them. See the [task deployment guide](../task-deployment/_index) for details.

## Basic usage

Use `flyte.remote.Task.get()` to reference a deployed task:

```python
import flyte
import flyte.remote

env = flyte.TaskEnvironment(name="my_env")

# Get the latest version of a deployed task
data_processor = flyte.remote.Task.get(
    "data_team.spark_analyzer",
    auto_version="latest"
)

# Use it in your task
@env.task
async def my_task(data_path: str) -> flyte.io.DataFrame:
    # Call the reference task like any other task
    result = await data_processor(input_path=data_path)
    return result
```

You can run this directly without deploying it:

```bash
flyte run my_workflow.py my_task --data_path s3://my-bucket/data.parquet
```

## Understanding lazy loading

Remote tasks use **lazy loading** to keep module imports fast and enable flexible client configuration. When you call `flyte.remote.Task.get()`, it returns a lazy reference that doesn't actually fetch the task from the server until the first invocation.

### When tasks are fetched

The remote task is fetched from the server only when:

- You call `flyte.run()` with the task
- You call `flyte.deploy()` with code that uses the task
- You invoke the task with the `()` operator inside another task
- You explicitly call `.fetch()` on the lazy reference

```python
import flyte.remote

# This does NOT make a network call - returns a lazy reference
data_processor = flyte.remote.Task.get(
    "data_team.spark_analyzer",
    auto_version="latest"
)

# The task is fetched here when you invoke it
run = flyte.run(data_processor, input_path="s3://my-bucket/data.parquet")
```

### Benefits of lazy loading

**Fast module loading**: Since no network calls are made during import, your Python modules load quickly even when referencing many remote tasks.

**Late binding**: You can call `flyte.init()` after importing remote tasks, and the correct client will be bound when the task is actually invoked:

```python
import flyte
import flyte.remote

# Load remote task reference at module level
data_processor = flyte.remote.Task.get(
    "data_team.spark_analyzer",
    auto_version="latest"
)

# Initialize the client later
flyte.init_from_config()

# The task uses the client configured above
run = flyte.run(data_processor, input_path="s3://data.parquet")
```

### Error handling

Because of lazy loading, if a referenced task doesn't exist, you won't get an error when calling `get()`. Instead, the error occurs during invocation, raising a `flyte.errors.RemoteTaskNotFoundError`:

```python
import flyte
import flyte.remote
import flyte.errors

# This succeeds even if the task doesn't exist
data_processor = flyte.remote.Task.get(
    "nonexistent.task",
    auto_version="latest"
)

try:
    # Error occurs here during invocation
    run = flyte.run(data_processor, input_path="s3://data.parquet")
except flyte.errors.RemoteTaskNotFoundError as e:
    print(f"Task not found or invocation failed: {e}")
    # Handle the error - perhaps use a fallback task
    # or notify the user that the task needs to be deployed
```

You can also catch errors when using remote tasks within other tasks:

```python
import flyte.errors

@env.task
async def pipeline_with_fallback(data_path: str) -> dict:
    try:
        # Try to use the remote task
        result = await data_processor(input_path=data_path)
        return {"status": "success", "result": result}
    except flyte.errors.RemoteTaskNotFoundError as e:
        # Fallback to local processing
        print(f"Remote task failed: {e}, using local fallback")
        return {"status": "fallback", "result": local_process(data_path)}
    except flyte.errors.RemoteTaskUsageError as e:
        raise ValueError(f"Bad Usage of remote task, maybe arguments dont match!")
```

### Eager fetching with `fetch()`

While lazy loading is convenient, you can explicitly fetch a task upfront using the `fetch()` method. This is useful for:

- **Catching errors early**: Validate that the task exists before execution starts
- **Caching**: Avoid the network call on first invocation when running multiple times
- **Service initialization**: Pre-load tasks when your service starts

```python
import flyte
import flyte.remote
import flyte.errors

# Get the lazy reference
data_processor = flyte.remote.Task.get(
    "data_team.spark_analyzer",
    auto_version="latest"
)

try:
    # Eagerly fetch the task details
    task_details = data_processor.fetch()

    # Now the task is cached - subsequent calls won't hit the remote service
    # You can pass either the original reference or task_details to flyte.run
    run1 = flyte.run(data_processor, input_path="s3://data1.parquet")
    run2 = flyte.run(task_details, input_path="s3://data2.parquet")

except flyte.errors.RemoteTaskNotFoundError as e:
    print(f"Task not found failed at startup: {e}")
    raise
except flyte.errors.RemoteTaskUsageError as e:
    print(f"Task run validation failed....")
    # Handle the error before any execution attempts
```

For async contexts, use `await fetch.aio()`:

```python
import flyte.remote

async def initialize_service():
    processor_ref = flyte.remote.Task.get(
        "data_team.spark_analyzer",
        auto_version="latest"
    )

    try:
        # Fetch asynchronously
        task_details = await processor_ref.fetch.aio()
        print(f"Task {task_details.name} loaded successfully")
        return processor_ref  # Return the cached reference
    except flyte.errors.RemoteTaskNotFoundError as e:
        print(f"Failed to load task: {e}")
        raise

# Initialize once at service startup
cached_processor = None

async def startup():
    global cached_processor
    cached_processor = await initialize_service()

# Later in your service
async def process_request(data_path: str):
    # The task is already cached from initialization
    # No network call on first invocation
    run = flyte.run(cached_processor, input_path=data_path)
    return run
```

**When to use eager fetching**:

- **Service startup**: Fetch all remote tasks during initialization to validate they exist and cache them
- **Multiple invocations**: If you'll invoke the same task many times, fetch once to cache it
- **Fail-fast validation**: Catch configuration errors before execution begins

**When lazy loading is better**:

- **Single-use tasks**: If you only invoke the task once, lazy loading is simpler
- **Import-time overhead**: Keep imports fast by deferring network calls
- **Conditional usage**: If the task may not be needed, don't fetch it upfront

### Module-level vs dynamic loading

**Module-level loading (recommended)**: Load remote tasks at the module level for cleaner, more maintainable code:

```python
import flyte.remote

# Module-level - clear and maintainable
data_processor = flyte.remote.Task.get(
    "data_team.spark_analyzer",
    auto_version="latest"
)

@env.task
async def my_task(data_path: str):
    return await data_processor(input_path=data_path)
```

**Dynamic loading**: You can also load remote tasks dynamically within a task if needed:

```python
@env.task
async def dynamic_pipeline(task_name: str, data_path: str):
    # Load the task based on runtime parameters
    processor = flyte.remote.Task.get(
        f"data_team.{task_name}",
        auto_version="latest"
    )

    try:
        result = await processor(input_path=data_path)
        return result
    except flyte.errors.RemoteTaskNotFoundError as e:
        raise ValueError(f"Task {task_name} not found: {e}")
```

## Complete example

This example shows how different teams can collaborate using remote tasks.

### Team A: Spark environment

Team A maintains Spark-based data processing tasks:

```python
# spark_env.py
from dataclasses import dataclass
import flyte

env = flyte.TaskEnvironment(name="spark_env")

@dataclass
class AnalysisResult:
    mean_value: float
    std_dev: float

@env.task
async def analyze_data(data_path: str) -> AnalysisResult:
    # Spark code here (not shown)
    return AnalysisResult(mean_value=42.5, std_dev=3.2)

@env.task
async def compute_score(result: AnalysisResult) -> float:
    # More Spark processing
    return result.mean_value / result.std_dev
```

Deploy the Spark environment:

```bash
flyte deploy spark_env/
```

### Team B: ML environment

Team B maintains PyTorch-based ML tasks:

```python
# ml_env.py
from pydantic import BaseModel
import flyte

env = flyte.TaskEnvironment(name="ml_env")

class PredictionRequest(BaseModel):
    feature_x: float
    feature_y: float

class Prediction(BaseModel):
    score: float
    confidence: float
    model_version: str

@env.task
async def run_inference(request: PredictionRequest) -> Prediction:
    # PyTorch model inference (not shown)
    return Prediction(
        score=request.feature_x * 2.5,
        confidence=0.95,
        model_version="v2.1"
    )
```

Deploy the ML environment:

```bash
flyte deploy ml_env/
```

### Team C: Orchestration

Team C builds a workflow using remote tasks from both teams without needing Spark or PyTorch dependencies:

```python
# orchestration_env.py
import flyte.remote

env = flyte.TaskEnvironment(name="orchestration")

# Reference tasks from other teams
analyze_data = flyte.remote.Task.get(
    "spark_env.analyze_data",
    auto_version="latest"
)

compute_score = flyte.remote.Task.get(
    "spark_env.compute_score",
    auto_version="latest"
)

run_inference = flyte.remote.Task.get(
    "ml_env.run_inference",
    auto_version="latest"
)

@env.task
async def orchestrate_pipeline(data_path: str) -> float:
    # Use Spark tasks without Spark dependencies
    analysis = await analyze_data(data_path=data_path)

    # Access attributes from the result
    # (Flyte creates a fake type that allows attribute access)
    print(f"Analysis: mean={analysis.mean_value}, std={analysis.std_dev}")

    data_score = await compute_score(result=analysis)

    # Use ML task without PyTorch dependencies
    # Pass Pydantic models as dictionaries
    prediction = await run_inference(
        request={
            "feature_x": analysis.mean_value,
            "feature_y": data_score
        }
    )

    # Access Pydantic model attributes
    print(f"Prediction: {prediction.score} (confidence: {prediction.confidence})")

    return prediction.score
```

Run the orchestration task directly (no deployment needed):

**Using Python API**:
```python
if __name__ == "__main__":
    flyte.init_from_config()

    run = flyte.run(
        orchestrate_pipeline,
        data_path="s3://my-bucket/data.parquet"
    )

    print(f"Execution URL: {run.url}")
    # You can wait for the execution
    run.wait()

    # You can then retrieve the outputs
    print(f"Pipeline result: {run.outputs()}")
```

**Using CLI**:
```bash
flyte run orchestration_env.py orchestrate_pipeline --data_path s3://my-bucket/data.parquet
```

## Invoke remote tasks in a script.

You can also run any remote task directly using a script in a similar way
```python
import flyte
import flyte.models
import flyte.remote

flyte.init_from_config()

# Fetch the task
remote_task = flyte.remote.Task.get("package-example.calculate_average", auto_version="latest")

# Create a run, note keyword arguments are required currently. In the future this will accept positional args based on the declaration order, but, we still recommend to use keyword args.
run = flyte.run(remote_task, numbers=[1.0, 2.0, 3.0])

print(f"Execution URL: {run.url}")
# you can view the phase

print(f"Current Phase: {run.phase}")
# You can wait for the execution
run.wait()

# Only available after flyte >= 2.0.0b39
print(f"Current phase: {run.phase}")

# Phases can be compared to
if run.phase == flyte.models.ActionPhase.SUCCEEDED:
    print(f"Run completed!")

# You can then retrieve the outputs
print(f"Pipeline result: {run.outputs()}")
```

## Why use remote tasks?

Remote tasks solve common collaboration and dependency management challenges:

**Cross-team collaboration**: Team A has deployed a Spark task that analyzes large datasets. Team B needs this analysis for their ML pipeline but doesn't want to learn Spark internals, install Spark dependencies, or build Spark-enabled container images. With remote tasks, Team B simply references Team A's deployed task.

**Platform reusability**: Platform teams can create common, reusable tasks (data validation, feature engineering, model serving) that other teams can use without duplicating code or managing complex dependencies.

**Microservices for data workflows**: Remote tasks work like microservices for long-running tasks or agents, enabling secure sharing while maintaining isolation.

## When to use remote tasks

Use remote tasks when you need to:

- Use functionality from another team without their dependencies
- Share common tasks across your organization
- Build reusable platform components
- Avoid dependency conflicts between different parts of your workflow
- Create modular, maintainable data pipelines

## How remote tasks work

### Security model

Remote tasks run in the **caller's project and domain** using the caller's compute resources, but execute with the **callee's service accounts, IAM roles, and secrets**. This ensures:

- Tasks are secure from misuse
- Resource usage is properly attributed
- Authentication and authorization are maintained
- Collaboration remains safe and controlled

### Type system

Remote tasks use Flyte's default types as inputs and outputs. Flyte's type system seamlessly translates data between tasks without requiring the original dependencies:

| Remote Task Type | Flyte Type |
|-------------------|------------|
| DataFrames (`pandas`, `polars`, `spark`, etc.) | `flyte.io.DataFrame` |
| Object store files | `flyte.io.File` |
| Object store directories | `flyte.io.Dir` |
| Pydantic models | Dictionary (Flyte creates a representation) |

Any DataFrame type (pandas, polars, spark) automatically becomes `flyte.io.DataFrame`, allowing seamless data exchange between tasks using different DataFrame libraries. You can also write custom integrations or explore Flyte's plugin system for additional types.

For Pydantic models specifically, you don't need the exact model locally. Pass a dictionary as input, and Flyte will handle the translation.

## Versioning options

Reference tasks support flexible versioning:

**Specific version**:

```python
task = flyte.remote.Task.get(
    "team_a.process_data",
    version="v1.2.3"
)
```

**Latest version** (`auto_version="latest"`):

```python
# Always use the most recently deployed version
task = flyte.remote.Task.get(
    "team_a.process_data",
    auto_version="latest"
)
```

**Current version** (`auto_version="current"`):

```python
# Use the same version as the calling task's deployment
# Useful when all environments deploy with the same version
# Can only be used from within a task context
task = flyte.remote.Task.get(
    "team_a.process_data",
    auto_version="current"
)
```

## Customizing remote tasks

Remote tasks can be customized by overriding various properties without modifying the original deployed task. This allows you to adjust resource requirements, retry strategies, caching behavior, and more based on your specific use case.

### Available overrides

The `override()` method on remote tasks accepts the following parameters:

- **short_name** (`str`): A short name for the task instance
- **resources** (`flyte.Resources`): CPU, memory, GPU, and storage limits
- **retries** (`int | flyte.RetryStrategy`): Number of retries or retry strategy
- **timeout** (`flyte.TimeoutType`): Task execution timeout
- **env_vars** (`Dict[str, str]`): Environment variables to set
- **secrets** (`flyte.SecretRequest`): Secrets to inject
- **max_inline_io_bytes** (`int`): Maximum size for inline IO in bytes
- **cache** (`flyte.Cache`): Cache behavior and settings
- **queue** (`str`): Execution queue to use

### Override examples

**Increase resources for a specific use case**:

```python
import flyte.remote

# Get the base task
data_processor = flyte.remote.Task.get(
    "data_team.spark_analyzer",
    auto_version="latest"
)

# Override with more resources for large dataset processing
large_data_processor = data_processor.override(
    resources=flyte.Resources(
        cpu="16",
        memory="64Gi",
        storage="200Gi"
    )
)

@env.task
async def process_large_dataset(data_path: str):
    # Use the customized version
    return await large_data_processor(input_path=data_path)
```

**Add retries and timeout**:

```python
# Override with retries and timeout for unreliable operations
reliable_processor = data_processor.override(
    retries=3,
    timeout="2h"
)

@env.task
async def robust_pipeline(data_path: str):
    return await reliable_processor(input_path=data_path)
```

**Configure caching**:

```python
# Override cache settings
cached_processor = data_processor.override(
    cache=flyte.Cache(
        behavior="override",
        version_override="v2",
        serialize=True
    )
)
```

**Set environment variables and secrets**:

```python
# Override with custom environment and secrets
custom_processor = data_processor.override(
    env_vars={
        "LOG_LEVEL": "DEBUG",
        "REGION": "us-west-2"
    },
    secrets=flyte.SecretRequest(
        secrets={"api_key": "my-secret-key"}
    )
)
```

**Multiple overrides**:

```python
# Combine multiple overrides
production_processor = data_processor.override(
    short_name="prod_spark_analyzer",
    resources=flyte.Resources(cpu="8", memory="32Gi"),
    retries=5,
    timeout="4h",
    env_vars={"ENV": "production"},
    queue="high-priority"
)

@env.task
async def production_pipeline(data_path: str):
    return await production_processor(input_path=data_path)
```

### Chain overrides

You can chain multiple `override()` calls to incrementally adjust settings:

```python
# Start with base task
processor = flyte.remote.Task.get("data_team.analyzer", auto_version="latest")

# Add resources
processor = processor.override(resources=flyte.Resources(cpu="4", memory="16Gi"))

# Add retries for production
if is_production:
    processor = processor.override(retries=5, timeout="2h")

# Use the customized task
result = await processor(input_path="s3://data.parquet")
```

## Best practices

### 1. Use meaningful task names

Remote tasks are accessed by name, so use clear, descriptive naming:

```python
# Good
customer_segmentation = flyte.remote.Task.get("ml_platform.customer_segmentation")

# Avoid
task1 = flyte.remote.Task.get("team_a.task1")
```

### 2. Document task interfaces

Since remote tasks abstract away implementation details, clear documentation of inputs, outputs, and behavior is essential:

```python
@env.task
async def process_customer_data(
    customer_ids: list[str],
    date_range: tuple[str, str]
) -> flyte.io.DataFrame:
    """
    Process customer data for the specified date range.

    Args:
        customer_ids: List of customer IDs to process
        date_range: Tuple of (start_date, end_date) in YYYY-MM-DD format

    Returns:
        DataFrame with processed customer features
    """
    ...
```

### 3. Prefer module-level loading

Load remote tasks at the module level rather than inside functions for cleaner code:

```python
import flyte.remote

# Good - module level
data_processor = flyte.remote.Task.get("team.processor", auto_version="latest")

@env.task
async def my_task(data: str):
    return await data_processor(input=data)
```

This approach:
- Makes dependencies clear and discoverable
- Reduces code duplication
- Works well with lazy loading (no performance penalty)

Dynamic loading within tasks is also supported when you need runtime flexibility.

### 4. Handle versioning thoughtfully

- Use `auto_version="latest"` during development for rapid iteration
- Use specific versions in production for stability and reproducibility
- Use `auto_version="current"` when coordinating multienvironment deployments

### 5. Deploy remote tasks first

Always deploy the remote tasks before using them. Tasks that reference them can be run directly without deployment:

Deploy the remote task environments first:

```bash
flyte deploy spark_env/
flyte deploy ml_env/
```

Then run the orchestration task directly (no deployment needed):

```bash
flyte run orchestration_env.py orchestrate_pipeline
```

If you want to deploy the orchestration task as well (for scheduled runs or to be referenced by other tasks), deploy it after its dependencies:

```bash
flyte deploy orchestration_env/
```

## Limitations

1. **Lazy error detection**: Because of lazy loading, errors about missing or invalid tasks only occur during invocation, not when calling `get()`. You'll receive a `flyte.errors.RemoteTaskNotFoundError` if the task doesn't exist and `flyte.errors.RemoteTaskUsageError` if it can't be invoked in the way you are passing either arguments or overrides.

2. **Type fidelity**: While Flyte translates types seamlessly, you work with Flyte's representation of Pydantic models, not the exact original types

3. **Deployment order**: Referenced tasks must be deployed before tasks that reference them can be invoked

4. **Context requirement**: Using `auto_version="current"` requires running within a task context

5. **Dictionary inputs**: Pydantic models must be passed as dictionaries, which loses compile-time type checking

6. **No positional arguments**: Remote tasks currently only support keyword arguments (this may change in future versions)

## Next steps

- Learn about [task deployment](../task-deployment/_index)
- Explore [task environments and configuration](../task-configuration/_index)


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-programming/error-handling ===

# Error handling

One of the key features of Flyte 2 is the ability to recover from user-level errors in a workflow execution.
This includes out-of-memory errors and other exceptions.

In a distributed system with heterogeneous compute, certain types of errors are expected and even, in a sense, acceptable.
Flyte 2 recognizes this and allows you to handle them gracefully as part of your workflow logic.

This ability is a direct result of the fact that workflows are now written in regular Python,
giving you with all the power and flexibility of Python error handling.
Let's look at an example:

```python
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# main = "main"
# params = ""
# ///

import asyncio

import flyte
import flyte.errors

env = flyte.TaskEnvironment(name="fail", resources=flyte.Resources(cpu=1, memory="250Mi"))

@env.task
async def oomer(x: int):
    large_list = [0] * 100000000
    print(len(large_list))

@env.task
async def always_succeeds() -> int:
    await asyncio.sleep(1)
    return 42

@env.task
async def main() -> int:
    try:
        await oomer(2)
    except flyte.errors.OOMError as e:
        print(f"Failed with oom trying with more resources: {e}, of type {type(e)}, {e.code}")
        try:
            await oomer.override(resources=flyte.Resources(cpu=1, memory="1Gi"))(5)
        except flyte.errors.OOMError as e:
            print(f"Failed with OOM Again giving up: {e}, of type {type(e)}, {e.code}")
            raise e
    finally:
        await always_succeeds()

    return await always_succeeds()

if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(main)
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/error-handling/error_handling.py*
<!-- TODO:
Create better example.
-->

In this code, we do the following:

* Import the necessary modules
* Set up the task environment. Note that we define our task environment with a resource allocation of 1 CPU and 250 MiB of memory.
* Define two tasks: one that will intentionally cause an out-of-memory (OOM) error, and another that will always succeed.
* Define the main task (the top level workflow task) that will handle the failure recovery logic.

The top `try...catch` block attempts to run the `oomer` task with a parameter that is likely to cause an OOM error.
If the error occurs, it catches the [`flyte.errors.OOMError`](../../api-reference/flyte-sdk/packages/flyte.errors/oomerror) and attempts to run the `oomer` task again with increased resources.

This type of dynamic error handling allows you to gracefully recover from user-level errors in your workflows.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-programming/traces ===

# Traces

The `@flyte.trace` decorator provides fine-grained observability and resumption capabilities for functions called within your Flyte workflows.
Traces are used on **helper functions** that tasks call to perform specific operations like API calls, data processing, or computations.
Traces are particularly useful for [managing the challenges of non-deterministic behavior in workflows](../flyte-2/considerations#non-deterministic-behavior), allowing you to track execution details and resume from failures.

## What are traced functions for?

At the top level, Flyte workflows are composed of **tasks**. But it is also common practice to break down complex task logic into smaller, reusable functions by defining helper functions that tasks call to perform specific operations.

Any helper functions defined or imported into the same file as a task definition are automatically uploaded to the Flyte environment alongside the task when it is deployed.

At the task level, observability and resumption of failed executions is provided by caching, but what if you want these capabilities at a more granular level, for the individual operations that tasks perform?

This is where **traced functions** come in. By decorating helper functions with `@flyte.trace`, you enable:
- **Detailed observability**: Track execution time, inputs/outputs, and errors for each function call.
- **Fine-grained resumption**: If a workflow fails, resume from the last successful traced function instead of re-running the entire task.
Each traced function is effectively a checkpoint within its task.

Here is an example:

```
import asyncio

import flyte

env = flyte.TaskEnvironment("env")

@flyte.trace
async def call_llm(prompt: str) -> str:
    await asyncio.sleep(0.1)
    return f"LLM response for: {prompt}"

@flyte.trace
async def process_data(data: str) -> dict:
    await asyncio.sleep(0.2)
    return {"processed": data, "status": "completed"}

@env.task
async def research_workflow(topic: str) -> dict:
    llm_result = await call_llm(f"Generate research plan for: {topic}")
    processed_data = await process_data(llm_result)
    return {"topic": topic, "result": processed_data}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/traces/task_vs_trace.py*

## What Gets Traced

Traces capture detailed execution information:
- **Execution time**: How long each function call takes.
- **Inputs and outputs**: Function parameters and return values.
- **Checkpoints**: State that enables workflow resumption.

### Errors are not recorded

Only successful trace executions are recorded in the checkpoint system. When a traced function fails, the exception propagates up to your task code where you can handle it with standard error handling patterns.

### Supported Function Types

The trace decorator works with:
- **Asynchronous functions**: Functions defined with `async def`.
- **Generator functions**: Functions that `yield` values.
- **Async generators**: Functions that `async yield` values.

> [!NOTE]
> Currently tracing only works for asynchronous functions. Tracing of synchronous functions is coming soon.

```
@flyte.trace
async def async_api_call(topic: str) -> dict:
    # Asynchronous API call
    await asyncio.sleep(0.1)
    return {"data": ["item1", "item2", "item3"], "status": "success"}

@flyte.trace
async def stream_data(items: list[str]):
    # Async generator function for streaming
    for item in items:
        await asyncio.sleep(0.02)
        yield f"Processing: {item}"

@flyte.trace
async def async_stream_llm(prompt: str):
    # Async generator for streaming LLM responses
    chunks = ["Research shows", " that machine learning", " continues to evolve."]
    for chunk in chunks:
        await asyncio.sleep(0.05)
        yield chunk

@env.task
async def research_workflow(topic: str) -> dict:
    llm_result = await async_api_call(topic)

    # Collect async generator results
    processed_data = []
    async for item in stream_data(llm_result["data"]):
        processed_data.append(item)

    llm_stream = []
    async for chunk in async_stream_llm(f"Summarize research on {topic}"):
        llm_stream.append(chunk)

    return {
        "topic": topic,
        "processed_data": processed_data,
        "llm_summary": "".join(llm_stream)
    }
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/traces/function_types.py*

## Task Orchestration Pattern

The typical Flyte workflow follows this pattern:

```
@flyte.trace
async def search_web(query: str) -> list[dict]:
    # Search the web and return results
    await asyncio.sleep(0.1)
    return [{"title": f"Article about {query}", "content": f"Content on {query}"}]

@flyte.trace
async def summarize_content(content: str) -> str:
    # Summarize content using LLM
    await asyncio.sleep(0.1)
    return f"Summary of {len(content.split())} words"

@flyte.trace
async def extract_insights(summaries: list[str]) -> dict:
    # Extract insights from summaries
    await asyncio.sleep(0.1)
    return {"insights": ["key theme 1", "key theme 2"], "count": len(summaries)}

@env.task
async def research_pipeline(topic: str) -> dict:
    # Each helper function creates a checkpoint
    search_results = await search_web(f"research on {topic}")

    summaries = []
    for result in search_results:
        summary = await summarize_content(result["content"])
        summaries.append(summary)

    final_insights = await extract_insights(summaries)

    return {
        "topic": topic,
        "insights": final_insights,
        "sources_count": len(search_results)
    }
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/traces/pattern.py*

**Benefits of this pattern:**
- If `search_web` succeeds but `summarize_content` fails, resumption skips the search step
- Each operation is independently observable and debuggable
- Clear separation between workflow coordination (task) and execution (traced functions)

## Relationship to Caching and Checkpointing

Understanding how traces work with Flyte's other execution features:

| Feature | Scope | Purpose | Default Behavior |
|---------|-------|---------|------------------|
| **Task Caching** | Entire task execution (`@env.task`) | Skip re-running tasks with same inputs | Enabled (`cache="auto"`) |
| **Traces** | Individual helper functions | Observability and fine-grained resumption | Manual (requires `@flyte.trace`) |
| **Checkpointing** | Workflow state | Resume workflows from failure points | Automatic when traces are used |

### How They Work Together

<!-- TODO
Lets use better typing for all of these examples, we have the opportunity to make this right for our users
-->

```
@flyte.trace
async def traced_data_cleaning(dataset_id: str) -> List[str]:
    # Creates checkpoint after successful execution.
    await asyncio.sleep(0.2)
    return [f"cleaned_record_{i}_{dataset_id}" for i in range(100)]

@flyte.trace
async def traced_feature_extraction(data: List[str]) -> dict:
    # Creates checkpoint after successful execution.
    await asyncio.sleep(0.3)
    return {
        "features": [f"feature_{i}" for i in range(10)],
        "feature_count": len(data),
        "processed_samples": len(data)
    }

@flyte.trace
async def traced_model_training(features: dict) -> dict:
    # Creates checkpoint after successful execution.
    await asyncio.sleep(0.4)
    sample_count = features["processed_samples"]
    # Mock accuracy based on sample count
    accuracy = min(0.95, 0.7 + (sample_count / 1000))
    return {
        "accuracy": accuracy,
        "epochs": 50,
        "model_size": "125MB"
    }

@env.task(cache="auto")  # Task-level caching enabled
async def data_pipeline(dataset_id: str) -> dict:
    # 1. If this exact task with these inputs ran before,
    #    the entire task result is returned from cache

    # 2. If not cached, execution begins and each traced function
    #    creates checkpoints for resumption
    cleaned_data = await traced_data_cleaning(dataset_id)      # Checkpoint 1
    features = await traced_feature_extraction(cleaned_data)   # Checkpoint 2
    model_results = await traced_model_training(features)      # Checkpoint 3

    # 3. If workflow fails at step 3, resumption will:
    #    - Skip traced_data_cleaning (checkpointed)
    #    - Skip traced_feature_extraction (checkpointed)
    #    - Re-run only traced_model_training

    return {"dataset_id": dataset_id, "accuracy": model_results["accuracy"]}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/traces/caching_vs_checkpointing.py*

### Execution Flow

1. **Task Submission**: Task is submitted with input parameters
2. **Cache Check**: Flyte checks if identical task execution exists in cache
3. **Cache Hit**: If cached, return cached result immediately (no traces needed)
4. **Cache Miss**: Begin fresh execution
5. **Trace Checkpoints**: Each `@flyte.trace` function creates resumption points
6. **Failure Recovery**: If workflow fails, resume from last successful checkpoint
7. **Task Completion**: Final result is cached for future identical inputs

<!--
Clarify what actually happens on error vs success with traces

## Error Handling and Observability

Traces capture comprehensive execution information for debugging and monitoring:

```
@flyte.trace
async def risky_api_call(endpoint: str, data: dict) -> dict:
    """API call that might fail - traces capture errors."""
    try:
        response = await api_client.post(endpoint, json=data)
        return response.json()
    except Exception as e:
        # Error is automatically captured in trace
        logger.error(f"API call failed: {e}")
        raise

@env.task
async def error_handling() -> dict:
    try:
        result = await risky_api_call("/process", {"invalid": "data"})
        return {"status": "success", "result": result}
    except Exception as e:
        # The error is recorded in the trace for debugging
        return {"status": "error", "message": str(e)}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/traces/error_handling.py*

**What traces capture:**
- **Execution time**: Duration of each function call
- **Inputs and outputs**: Function parameters and return values
- **Checkpoints**: State that enables workflow resumption from successful executions
- **Action IDs**: Unique identifiers for each execution

**Error handling:**
- Errors from traced functions are not recorded in checkpoints
- Exceptions propagate to your task code for standard error handling
- The error_handling example shows how to catch and handle these exceptions in your task

TODO:
Ketan Umare:
we should show an example where tasks and traces can be used interchangeably

## Examples in Practice

### LLM Pipeline with Traces

```python
import flyte

env = flyte.TaskEnvironment("llm-pipeline")

@flyte.trace
async def call_llm(prompt: str, model: str = "gpt-4") -> str:
    """Call LLM with specified model."""
    response = await llm_client.chat(prompt, model=model)
    return response

@flyte.trace
async def extract_entities(text: str) -> list[str]:
    """Extract named entities from text."""
    entities = await nlp_service.extract_entities(text)
    return entities

@env.task
async def process_documents(documents: list[str]) -> dict:
    """Process multiple documents through LLM pipeline."""
    results = []

    for doc in documents:
        # Each call is traced for monitoring and resumption
        summary = await call_llm(f"Summarize: {doc}")
        entities = await extract_entities(summary)

        results.append({
            "document": doc,
            "summary": summary,
            "entities": entities
        })

    return {"processed_documents": results, "total_count": len(results)}
```

This comprehensive tracing system provides visibility into your workflow execution while enabling robust error recovery and resumption capabilities.
-->


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-programming/grouping-actions ===

# Grouping actions

Groups are an organizational feature in Flyte that allow you to logically cluster related task invocations (called "actions") for better visualization and management in the UI.
Groups help you organize task executions into manageable, hierarchical structures regardless of whether you're working with large fanouts or smaller, logically-related sets of operations.

## What are groups?

Groups provide a way to organize task invocations into logical units in the Flyte UI.
When you have multiple task executions—whether from large [fanouts](./fanout), sequential operations, or any combination of tasks—groups help organize them into manageable units.

### The problem groups solve

Without groups, complex workflows can become visually overwhelming in the Flyte UI:
- Multiple task executions appear as separate nodes, making it hard to see the high-level structure
- Related operations are scattered throughout the workflow graph
- Debugging and monitoring becomes difficult when dealing with many individual task executions

Groups solve this by:
- **Organizing actions**: Multiple task executions within a group are presented as a hierarchical "folder" structure
- **Improving UI visualization**: Instead of many individual nodes cluttering the view, you see logical groups that can be collapsed or expanded
- **Aggregating status information**: Groups show aggregated run status (success/failure) of their contained actions when you hover over them in the UI
- **Maintaining execution parallelism**: Tasks still run concurrently as normal, but are organized for display

### How groups work

Groups are declared using the [`flyte.group`](../../api-reference/flyte-sdk/packages/flyte/_index#group) context manager.
Any task invocations that occur within the `with flyte.group()` block are automatically associated with that group:

```python
with flyte.group("my-group-name"):
    # All task invocations here belong to "my-group-name"
    result1 = await task_a(data)
    result2 = await task_b(data)
    result3 = await task_c(data)
```

The key points about groups:

1. **Context-based**: Use the `with flyte.group("name"):` context manager.
2. **Organizational tool**: Task invocations within the context are grouped together in the UI.
3. **UI folders**: Groups appear as collapsible/expandable folders in the Flyte UI run tree.
4. **Status aggregation**: Hover over a group in the UI to see aggregated success/failure information.
5. **Execution unchanged**: Tasks still execute in parallel as normal; groups only affect organization and visualization.

**Important**: Groups do not aggregate outputs. Each task execution still produces its own individual outputs. Groups are purely for organization and UI presentation.

## Common grouping patterns

### Sequential operations

Group related sequential operations that logically belong together:

```
@env.task
async def data_pipeline(raw_data: str) -> str:
    with flyte.group("data-validation"):
        validated_data = await process_data(raw_data, "validate_schema")
        validated_data = await process_data(validated_data, "check_quality")
        validated_data = await process_data(validated_data, "remove_duplicates")

    with flyte.group("feature-engineering"):
        features = await process_data(validated_data, "extract_features")
        features = await process_data(features, "normalize_features")
        features = await process_data(features, "select_features")

    with flyte.group("model-training"):
        model = await process_data(features, "train_model")
        model = await process_data(model, "validate_model")
        final_model = await process_data(model, "save_model")

    return final_model
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/grouping-actions/grouping.py*

### Parallel processing with groups

Groups work well with parallel execution patterns:

```
@env.task
async def parallel_processing_example(n: int) -> str:
    tasks = []

    with flyte.group("parallel-processing"):
        # Collect all task invocations first
        for i in range(n):
            tasks.append(process_item(i, "transform"))

        # Execute all tasks in parallel
        results = await asyncio.gather(*tasks)

    # Convert to string for consistent return type
    return f"parallel_results: {results}"
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/grouping-actions/grouping.py*

### Multi-phase workflows

Use groups to organize different phases of complex workflows:

```
@env.task
async def multi_phase_workflow(data_size: int) -> str:
    # First phase: data preprocessing
    preprocessed = []
    with flyte.group("preprocessing"):
        for i in range(data_size):
            preprocessed.append(process_item(i, "preprocess"))
        phase1_results = await asyncio.gather(*preprocessed)

    # Second phase: main processing
    processed = []
    with flyte.group("main-processing"):
        for result in phase1_results:
            processed.append(process_item(result, "transform"))
        phase2_results = await asyncio.gather(*processed)

    # Third phase: postprocessing
    postprocessed = []
    with flyte.group("postprocessing"):
        for result in phase2_results:
            postprocessed.append(process_item(result, "postprocess"))
        final_results = await asyncio.gather(*postprocessed)

    # Convert to string for consistent return type
    return f"multi_phase_results: {final_results}"
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/grouping-actions/grouping.py*

### Nested groups

Groups can be nested to create hierarchical organization:

```
@env.task
async def hierarchical_example(raw_data: str) -> str:
    with flyte.group("data-preparation"):
        cleaned_data = await process_data(raw_data, "clean_data")
        split_data = await process_data(cleaned_data, "split_dataset")

    with flyte.group("hyperparameter-tuning"):
        best_params = await process_data(split_data, "tune_hyperparameters")

    with flyte.group("model-training"):
        model = await process_data(best_params, "train_final_model")
    return model
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/grouping-actions/grouping.py*

### Conditional grouping

Groups can be used with conditional logic:

```
@env.task
async def conditional_processing(use_advanced_features: bool, input_data: str) -> str:
    base_result = await process_data(input_data, "basic_processing")

    if use_advanced_features:
        with flyte.group("advanced-features"):
            enhanced_result = await process_data(base_result, "advanced_processing")
            optimized_result = await process_data(enhanced_result, "optimize_result")
            return optimized_result
    else:
        with flyte.group("basic-features"):
            simple_result = await process_data(base_result, "simple_processing")
            return simple_result
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/grouping-actions/grouping.py*

## Key insights

Groups are primarily an organizational and UI visualization tool—they don't change how your tasks execute or aggregate their outputs, but they help organize related task invocations (actions) into collapsible folder-like structures for better workflow management and display. The aggregated status information (success/failure rates) is visible when hovering over group folders in the UI.

Groups make your Flyte workflows more maintainable and easier to understand, especially when working with complex workflows that involve multiple logical phases or large numbers of task executions. They serve as organizational "folders" in the UI's call stack tree, allowing you to collapse sections to reduce visual distraction while still seeing aggregated status information on hover.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-programming/fanout ===

# Fanout

Flyte is designed to scale effortlessly, allowing you to run workflows with large fanouts.
When you need to execute many tasks in parallel—such as processing a large dataset or running hyperparameter sweeps—Flyte provides powerful patterns to implement these operations efficiently.

> [!NOTE]
> By default fanouts in Union are limited to a maximum size.
> Adjustment can made to this maximum by consulting with the Union team.
> Full documentation of this aspect of fanout is coming soon.

## Understanding fanout

A "fanout" pattern occurs when you spawn multiple tasks concurrently.
Each task runs in its own container and contributes an output that you later collect.
The most common way to implement this is using the [`asyncio.gather`](https://docs.python.org/3/library/asyncio-task.html#asyncio.gather) function.

In Flyte terminology, each individual task execution is called an "action"—this represents a specific invocation of a task with particular inputs. When you call a task multiple times in a loop, you create multiple actions.

## Example

We start by importing our required packages, defining our Flyte environment, and creating a simple task that fetches user data from a mock API.

```
import asyncio
from typing import List, Tuple

import flyte

env = flyte.TaskEnvironment("fanout_env")

@env.task
async def fetch_data(user_id: int) -> dict:
    """Simulate fetching user data from an API - good for parallel execution."""
    # Simulate network I/O delay
    await asyncio.sleep(0.1)
    return {
        "user_id": user_id,
        "name": f"User_{user_id}",
        "score": user_id * 10,
        "data": f"fetched_data_{user_id}"
    }
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/fanout/fanout.py*

### Parallel execution

Next we implement the most common fanout pattern, which is to collect task invocations and execute them in parallel using `asyncio.gather()`:

```
@env.task
async def parallel_data_fetching(user_ids: List[int]) -> List[dict]:
    """Fetch data for multiple users in parallel - ideal for I/O bound operations."""
    tasks = []

    # Collect all fetch tasks - these can run in parallel since they're independent
    for user_id in user_ids:
        tasks.append(fetch_data(user_id))

    # Execute all fetch operations in parallel
    results = await asyncio.gather(*tasks)
    return results
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/fanout/fanout.py*

### Running the example

To actually run our example, we create a main guard that intializes Flyte and runs our main driver task:

```
if __name__ == "__main__":
    flyte.init_from_config()
    user_ids = [1, 2, 3, 4, 5]
    r = flyte.run(parallel_data_fetching, user_ids)
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/fanout/fanout.py*

## How Flyte handles concurrency and parallelism

In the example we use a standard `asyncio.gather()` pattern.
When this pattern is used in a normal Python environment, the tasks would execute **concurrently** (cooperatively sharing a single thread through the event loop), but not in true **parallel** (multiple CPU cores simultaneously).

However, **Flyte transforms this concurrency model into true parallelism**. When you use `asyncio.gather()` in a Flyte task:

1. **Flyte acts as a distributed event loop**: Instead of scheduling coroutines on a single machine, Flyte schedules each task action to run in its own container across the cluster
2. **Concurrent becomes parallel**: What would be cooperative multitasking in regular Python becomes true parallel execution across multiple machines
3. **Native Python patterns**: You use familiar `asyncio` patterns, but Flyte automatically distributes the work

This means that when you write:
```python
results = await asyncio.gather(fetch_data(1), fetch_data(2), fetch_data(3))
```

Instead of three coroutines sharing one CPU, you get three separate containers running simultaneously, each with their own CPU, memory, and resources. Flyte seamlessly bridges the gap between Python's concurrency model and distributed parallel computing, allowing for massive scalability while maintaining the familiar async/await programming model.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-programming/controlling-parallelism ===

# Controlling parallel execution

When you [fan out](./fanout) to many tasks, you often need to limit how many run at the same time.
Common reasons include rate-limited APIs, GPU quotas, database connection limits, or simply avoiding overwhelming a downstream service.

Flyte 2 provides two ways to control concurrency:
[`asyncio.Semaphore`](https://docs.python.org/3/library/asyncio-sync.html#asyncio.Semaphore) for fine-grained control,
and `flyte.map` with a built-in `concurrency` parameter for simpler cases.

## The problem: unbounded parallelism

A straightforward `asyncio.gather` launches every task at once.
If you are calling an external API that allows only a few concurrent requests, this can cause throttling or errors:

```
import asyncio

import flyte

env = flyte.TaskEnvironment("controlling_parallelism")

@env.task
async def call_llm_api(prompt: str) -> str:
    """Simulate calling a rate-limited LLM API."""
    # In a real workflow, this would call an external API.
    # The API might allow only a few concurrent requests.
    await asyncio.sleep(0.5)
    return f"Response to: {prompt}"
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/controlling-parallelism/controlling_parallelism.py*

```
@env.task
async def process_all_at_once(prompts: list[str]) -> list[str]:
    """Send all requests in parallel with no concurrency limit.

    This can overwhelm a rate-limited API, causing errors or throttling.
    """
    results = await asyncio.gather(*[call_llm_api(p) for p in prompts])
    return list(results)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/controlling-parallelism/controlling_parallelism.py*

With eight prompts, this fires eight concurrent API calls.
That works fine when there are no limits, but will fail when the API enforces a concurrency cap.

## Using asyncio.Semaphore

An `asyncio.Semaphore` acts as a gate: only a fixed number of tasks can pass through at a time.
The rest wait until a slot opens up.

```
@env.task
async def process_batch_with_semaphore(
    prompts: list[str],
    max_concurrent: int = 3,
) -> list[str]:
    """Process prompts in parallel, limiting concurrency with a semaphore.

    At most `max_concurrent` calls to the API run at any given time.
    The remaining tasks wait until a slot is available.
    """
    semaphore = asyncio.Semaphore(max_concurrent)

    async def limited_call(prompt: str) -> str:
        async with semaphore:
            return await call_llm_api(prompt)

    results = await asyncio.gather(*[limited_call(p) for p in prompts])
    return list(results)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/controlling-parallelism/controlling_parallelism.py*

The pattern is:

1. Create a semaphore with the desired limit.
2. Wrap each task call in an inner async function that acquires the semaphore before calling and releases it after.
3. Pass all wrapped calls to `asyncio.gather`.

All eight tasks are submitted immediately, but the Flyte orchestrator only allows three to run in parallel.
As each one completes, the next waiting task starts.

> [!NOTE]
> The semaphore controls how many tasks execute concurrently on the Flyte cluster.
> Each task still runs in its own container with its own resources — the semaphore simply limits how many containers are active at a time.

## Using flyte.map with concurrency

For uniform work — applying the same task to a list of inputs — `flyte.map` with the `concurrency` parameter is simpler:

CODE2

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/controlling-parallelism/controlling_parallelism.py*

This achieves the same concurrency limit with less boilerplate.

## Running the example

CODE3

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/controlling-parallelism/controlling_parallelism.py*

## When to use each approach

Use **`flyte.map(concurrency=N)`** when:

- Every item goes through the same task.
- You want the simplest possible code.

Use **`asyncio.Semaphore`** when:

- You need different concurrency limits for different task types within the same workflow.
- You want to combine concurrency control with error handling (e.g., `asyncio.gather(*tasks, return_exceptions=True)`).
- You are calling multiple different tasks in one parallel batch.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-programming/human-in-the-loop ===

# Human-in-the-loop

Human-in-the-loop (HITL) workflows pause execution at a defined point, wait for a human to provide input or approval, and then continue based on that response. Common use cases include content moderation gates, model output review, anomaly confirmation, and manual approval steps before costly or irreversible operations.

The `flyteplugins-hitl` package provides an event-based API for this pattern. When an event is created, Flyte automatically serves a small FastAPI web app with a form where a human can submit input. The workflow then resumes with the submitted value.

```bash
pip install flyteplugins-hitl
```

Key characteristics:

- Supports `int`, `float`, `str`, and `bool` input types
- Crash-resilient: uses durable sleep so polling survives task restarts
- Configurable timeout and poll interval
- The web form is accessible from the task's report in the Flyte UI

## Setup

The task environment must declare `hitl.env` as a dependency. This makes the HITL web app available during task execution:

```
import flyte
import flyteplugins.hitl as hitl

# The task environment must declare hitl.env as a dependency.
# This makes the HITL web app available during task execution.
env = flyte.TaskEnvironment(
    name="hitl-workflow",
    image=flyte.Image.from_debian_base(name="hitl").with_pip_packages(
        "flyteplugins-hitl>=2.0.0",
        "fastapi",
        "uvicorn",
        "python-multipart",
    ),
    resources=flyte.Resources(cpu="1", memory="512Mi"),
    depends_on=[hitl.env],
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/human-in-the-loop/hitl.py*

## Automated task

An automated task runs first and produces a result that requires human review:

```
@env.task(report=True)
async def analyze_data(dataset: str) -> dict:
    """Automated task that produces a result requiring human review."""
    # Simulate analysis
    result = {
        "dataset": dataset,
        "row_count": 142857,
        "anomalies_detected": 3,
        "confidence": 0.87,
    }
    await flyte.report.replace.aio(
        f"Analysis complete: {result['anomalies_detected']} anomalies detected "
        f"(confidence: {result['confidence']:.0%})"
    )
    await flyte.report.flush.aio()
    return result
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/human-in-the-loop/hitl.py*

## Requesting human input

Use `hitl.new_event()` to pause and wait for a human response. The `prompt` is shown on the web form. The `data_type` controls what type the submitted value is converted to before being returned:

```
@env.task(report=True)
async def request_human_review(analysis: dict) -> bool:
    """Pause and ask a human whether to proceed with the flagged records."""
    event = await hitl.new_event.aio(
        "review_decision",
        data_type=bool,
        scope="run",
        prompt=(
            f"Analysis found {analysis['anomalies_detected']} anomalies "
            f"with {analysis['confidence']:.0%} confidence. "
            "Approve for downstream processing? (true/false)"
        ),
    )
    approved: bool = await event.wait.aio()
    return approved
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/human-in-the-loop/hitl.py*

When this task runs, Flyte:

1. Serves the HITL web app (if not already running)
2. Creates an event and writes a pending request to object storage
3. Displays a link to the web form in the task report
4. Polls for a response using durable sleep
5. Returns the submitted value once input is received

## Wiring it together

The main task orchestrates the automated step and the HITL gate:

```
@env.task(report=True)
async def main(dataset: str = "s3://my-bucket/data.parquet") -> str:
    analysis = await analyze_data(dataset=dataset)

    approved = await request_human_review(analysis=analysis)

    if approved:
        return "Processing approved — continuing pipeline."
    else:
        return "Processing rejected by reviewer — pipeline halted."

if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(main)
    print(r.name)
    print(r.url)
    r.wait()
    print(r.outputs())
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-programming/human-in-the-loop/hitl.py*

## Event options

`hitl.new_event()` accepts the following parameters:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `name` | `str` | — | Descriptive name shown in logs and the UI |
| `data_type` | `type` | — | Expected input type: `int`, `float`, `str`, or `bool` |
| `scope` | `str` | `"run"` | Scope of the event. Currently only `"run"` is supported |
| `prompt` | `str` | `"Please provide a value"` | Message shown on the web form |
| `timeout_seconds` | `int` | `3600` | Maximum time to wait before raising `TimeoutError` |
| `poll_interval_seconds` | `int` | `5` | How often to check for a response |

## Submitting input programmatically

In addition to the web form, input can be submitted via the event's JSON API endpoint. This is useful for automated testing or integration with external approval systems:

```bash
curl -X POST https://<hitl-app-endpoint>/submit/json \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "<request_id>",
    "response_path": "<response_path>",
    "value": "true",
    "data_type": "bool"
  }'
```

The `request_id` and `response_path` are shown in the task report alongside the form URL.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-programming/other-features ===

This section covers advanced programming patterns and techniques for working with Flyte tasks.

## Task Forwarding

When one task calls another task using the normal invocation syntax (e.g., `await inner_task(x)`), Flyte creates a durable action that's recorded in the UI with data passed through the metadata store. However, if you want to execute a task in the same Python VM without this overhead, use the `.forward()` method.

**When to use**: You want to avoid durability overhead and execute task logic directly in the current VM.

```python
import flyte

env = flyte.TaskEnvironment("my-env")

@env.task
async def inner_task(x: int) -> int:
    return x + 1

@env.task
async def outer_task(x: int) -> int:
    # Executes in same VM, no durable action created
    v = await inner_task.forward(x=10)

    # Creates a durable action, recorded in UI
    return await inner_task(v)
```

The `.forward()` method works with both sync and async tasks:

```python
@env.task
def sync_inner_task(x: int) -> int:
    return x + 1

@env.task
def sync_outer_task(x: int) -> int:
    # Direct execution, no remote call
    v = sync_inner_task.forward(x=10)
    return sync_inner_task(v)
```

## Passing Tasks and Functions as Arguments

You can pass both Flyte tasks and regular Python functions as arguments to other tasks. Flyte handles this through pickling, so the code appears as pickled data in the UI.

```python
import typing
import flyte

env = flyte.TaskEnvironment("udfs")

@env.task
async def add_one_udf(x: int) -> int:
    return x + 1

# Regular async function (not a task)
async def fn_add_two_udf(x: int) -> int:
    return x + 2

@env.task
async def run_udf(x: int, udf: typing.Callable[[int], typing.Awaitable[int]]) -> int:
    return await udf(x)

@env.task
async def main() -> list[int]:
    # Pass a Flyte task as an argument
    result_one = await run_udf(5, add_one_udf)

    # Pass a regular function as an argument
    result_two = await run_udf(5, fn_add_two_udf)

    return [result_one, result_two]
```

**Note**: Both tasks and regular functions are serialized via pickling when passed as arguments.

## Custom Action Names

By default, actions in the UI use the task's function name. You can provide custom, user-friendly names using the `short_name` parameter.

### Set at Task Definition

```python
import flyte

env = flyte.TaskEnvironment("friendly_names")

@env.task(short_name="my_task")
async def some_task() -> str:
    return "Hello, Flyte!"
```

### Override at Call Time

```python
@env.task(short_name="entrypoint")
async def main() -> str:
    # Uses the default short_name "my_task"
    s = await some_task()

    # Overrides to use "my_name" for this specific action
    return s + await some_task.override(short_name="my_name")()
```

This is useful when the same task is called multiple times with different contexts, making the UI more readable.

## Invoking Async Functions from Sync Tasks

When migrating from Flyte 1.x to 2.0, you may have legacy sync code that needs to call async functions. Use `nest_asyncio.apply()` to enable `asyncio.run()` within sync tasks.

```python
import asyncio
import nest_asyncio
import flyte

env = flyte.TaskEnvironment(
    "async_in_sync",
    image=flyte.Image.from_debian_base().with_pip_packages("nest_asyncio"),
)

# Apply at module level
nest_asyncio.apply()

async def async_function() -> str:
    await asyncio.sleep(1)
    return "done"

@env.task
def sync_task() -> str:
    # Now you can use asyncio.run() in a sync task
    return asyncio.run(async_function())
```

**Important**:
- Call `nest_asyncio.apply()` at the module level before defining tasks
- Add `nest_asyncio` to your image dependencies
- This is particularly useful during migration when you have mixed sync/async code

## Async and Sync Task Interoperability

When migrating from older sync-based code to async tasks, or when working with mixed codebases, you need to call sync tasks from async parent tasks. Flyte provides the `.aio` method on every task (even sync ones) to enable this.

### Calling Sync Tasks from Async Tasks

Every sync task automatically has an `.aio` property that returns an async-compatible version:

```python
import flyte

env = flyte.TaskEnvironment("mixed-tasks")

@env.task
def sync_task(x: int) -> str:
    """Legacy sync task"""
    return f"Processed {x}"

@env.task
async def async_task(x: int) -> str:
    """New async task that calls legacy sync task"""
    # Use .aio to call sync task from async context
    result = await sync_task.aio(x)
    return result
```

### Using with `flyte.map.aio()`

When you need to call sync tasks in parallel from an async context, use `flyte.map.aio()`:

```python
from typing import List
import flyte

env = flyte.TaskEnvironment("map-example")

@env.task
def sync_process(x: int) -> str:
    """Synchronous processing task"""
    return f"Task {x}"

@env.task
async def async_main(n: int) -> List[str]:
    """Async task that maps over sync task"""
    results = []

    # Map over sync task from async context
    async for result in flyte.map.aio(sync_process, range(n)):
        if isinstance(result, Exception):
            raise result
        results.append(result)

    return results
```

**Why this matters**: This pattern is powerful when migrating from Flyte 1.x or integrating legacy sync tasks with new async code. You don't need to rewrite all sync tasks at once—they can be called seamlessly from async contexts.

## Using AnyIO in Async Tasks

Flyte async tasks support `anyio` for structured concurrency as an alternative to `asyncio.gather()`.

```python
import anyio
import aioresult
import flyte

env = flyte.TaskEnvironment(
    "anyio_example",
    image=flyte.Image.from_debian_base().with_pip_packages("anyio", "aioresult"),
)

@env.task
async def process_item(x: int) -> int:
    return x * 2

@env.task
async def batch_process(items: list[int]) -> list[int]:
    captured_results = []

    async with anyio.create_task_group() as tg:
        # Start multiple tasks concurrently
        for item in items:
            captured_results.append(
                aioresult.ResultCapture.start_soon(tg, process_item, item)
            )

    # Extract results
    return [r.result() for r in captured_results]
```

**Note**: You can use anyio's task groups, timeouts, and other structured concurrency primitives within Flyte async tasks.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-programming/unit-testing ===

Unit testing is essential for ensuring your Flyte tasks work correctly. Flyte 2.0 provides flexible testing approaches that allow you to test both your business logic and Flyte-specific features like type transformations and caching.

## Understanding Task Invocation

When working with functions decorated with `@env.task`, there are two ways to invoke them, each with different behavior:

### Direct Function Invocation

When you call a task directly like a regular Python function:

```python
result = my_task(x=10, y=20)
```

**Flyte features are NOT invoked**, including:
- Type transformations and serialization
- Caching
- Data validation

This behaves exactly like calling a regular Python function, making it ideal for testing your business logic.

### Using `flyte.run()`

When you invoke a task using `flyte.run()`:

```python
run = flyte.run(my_task, x=10, y=20)
result = run.outputs()
```

**Flyte features ARE invoked**, including:
- Type transformations and serialization
- Data validation
- Type checking (raises `flyte.errors` if types are not supported or restricted)

This allows you to test Flyte-specific behavior like serialization and caching.

## Testing Business Logic

For most unit tests, you want to verify your business logic works correctly. Use **direct function invocation** for this:

```python
import flyte

env = flyte.TaskEnvironment("my_env")

@env.task
def add(a: int, b: int) -> int:
    return a + b

def test_add():
    result = add(a=3, b=5)
    assert result == 8
```

### Testing Async Tasks

Async tasks work the same way with direct invocation:

```python
import pytest

@env.task
async def subtract(a: int, b: int) -> int:
    return a - b

@pytest.mark.asyncio
async def test_subtract():
    result = await subtract(a=10, b=4)
    assert result == 6
```

### Testing Nested Tasks

When tasks call other tasks, direct invocation continues to work without any Flyte overhead:

```python
@env.task
def nested(a: int, b: int) -> int:
    return add(a, b)  # Calls the add task directly

def test_nested():
    result = nested(3, 5)
    assert result == 8
```

## Testing Type Transformations and Serialization

When you need to test how Flyte handles data types, serialization, or caching, use `flyte.run()`:

```python
@pytest.mark.asyncio
async def test_add_with_flyte_run():
    run = flyte.run(add, 3, 5)
    assert run.outputs() == 8
```

### Testing Type Restrictions

Some types may not be supported or may be restricted. Use `flyte.run()` to test that these restrictions are enforced:

```python
from typing import Tuple
import flyte.errors

@env.task
def not_supported_types(x: Tuple[str, str]) -> str:
    return x[0]

@pytest.mark.asyncio
async def test_not_supported_types():
    # Direct invocation works fine
    result = not_supported_types(x=("a", "b"))
    assert result == "a"

    # flyte.run enforces type restrictions
    with pytest.raises(flyte.errors.RestrictedTypeError):
        flyte.run(not_supported_types, x=("a", "b"))
```

### Testing Nested Tasks with Serialization

You can also test nested task execution with Flyte's full machinery:

```python
@pytest.mark.asyncio
async def test_nested_with_run():
    run = flyte.run(nested, 3, 5)
    assert run.outputs() == 8
```

## Testing Traced Functions

Functions decorated with `@flyte.trace` can be tested similarly to tasks:

```python
@flyte.trace
async def traced_multiply(a: int, b: int) -> int:
    return a * b

@pytest.mark.asyncio
async def test_traced_multiply():
    result = await traced_multiply(a=6, b=7)
    assert result == 42
```

## Best Practices

1. **Test logic with direct invocation**: For most unit tests, call tasks directly to test your business logic without Flyte overhead.

2. **Test serialization with `flyte.run()`**: Use `flyte.run()` when you need to verify:
   - Type transformations work correctly
   - Data serialization/deserialization
   - Caching behavior
   - Type restrictions are enforced

3. **Use standard testing frameworks**: Flyte tasks work with pytest, unittest, and other Python testing frameworks.

4. **Test async tasks properly**: Use `@pytest.mark.asyncio` for async tasks and await their results.

5. **Mock external dependencies**: Use standard Python mocking techniques for external services, databases, etc.

## Quick Reference

| Test Scenario | Method | Example |
|--------------|--------|---------|
| Business logic (sync) | Direct call | `result = task(x=10)` |
| Business logic (async) | Direct await | `result = await task(x=10)` |
| Type transformations | `flyte.run()` | `r = flyte.run(task, x=10)` |
| Data serialization | `flyte.run()` | `r = flyte.run(task, x=10)` |
| Caching behavior | `flyte.run()` | `r = flyte.run(task, x=10)` |
| Type restrictions | `flyte.run()` + pytest.raises | `pytest.raises(flyte.errors.RestrictedTypeError)` |

## Example Test Suite

Here's a complete example showing different testing approaches:

```python
import pytest
import flyte
import flyte.errors

env = flyte.TaskEnvironment("test_env")

@env.task
def add(a: int, b: int) -> int:
    return a + b

@env.task
async def subtract(a: int, b: int) -> int:
    return a - b

# Test business logic directly
def test_add_logic():
    result = add(a=3, b=5)
    assert result == 8

@pytest.mark.asyncio
async def test_subtract_logic():
    result = await subtract(a=10, b=4)
    assert result == 6

# Test with Flyte serialization
@pytest.mark.asyncio
async def test_add_serialization():
    run = flyte.run(add, 3, 5)
    assert run.outputs() == 8

@pytest.mark.asyncio
async def test_subtract_serialization():
    run = flyte.run(subtract, a=10, b=4)
    assert run.outputs() == 6
```

## Future Improvements

The Flyte SDK team is actively working on improvements for advanced unit testing scenarios, particularly around initialization and setup for complex test cases. Additional utilities and patterns may be introduced in future releases to make unit testing even more streamlined.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-deployment ===

# Run and deploy tasks

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

You have seen how to configure and build the tasks that compose your project.
Now you need to decide how to execute them on your Flyte backend.

Flyte offers two distinct approaches for getting your tasks onto the backend:

**Use `flyte run` when you're iterating and experimenting:**
- Quickly test changes during development
- Try different parameters or code modifications
- Debug issues without creating permanent artifacts
- Prototype new ideas rapidly

**Use `flyte deploy` when your project is ready to be formalized:**
- Freeze a stable version of your tasks for repeated use
- Share tasks with team members or across environments
- Move from experimentation to a more structured workflow
- Create a permanent reference point (not necessarily production-ready)

This section explains both approaches and when to use each one.

## Ephemeral deployment and immediate execution

The `flyte run` CLI command and the `flyte.run()` SDK function are used to **ephemerally deploy** and **immediately execute** a task on the backend in a single step.
The task can be re-run and its execution and outputs can be observed in the **Runs list** UI, but it is not permanently added to the **Tasks list** on the backend.

Let's say you have the following file called `greeting.py`:

```python
# greeting.py

import flyte

env = flyte.TaskEnvironment(name="greeting_env")

@env.task
async def greet(message: str) -> str:
    return f"{message}!"
```

### Programmatic

You can run the task programmatically using the `flyte.run()` function:

```python
# greeting.py

import flyte

env = flyte.TaskEnvironment(name="greeting_env")

@env.task
async def greet(message: str) -> str:
    return f"{message}!"

if __name__ == "__main__":
    flyte.init_from_config()
    result = flyte.run(greet, message="Good morning!")
    print(f"Result: {result}")
```

Here we add a `__main__` block to the `greeting.py` file that initializes the Flyte SDK from the configuration file and then calls `flyte.run()` with the `greet` task and its argument.
Now you can run the `greet` task on the backend just by executing the `greeting.py` file locally as a script:

```bash
python greeting.py
```

### CLI

The general form of the command for running a task from a local file is:

```bash
flyte run <file_path> <task_name> <args>
```

So, to run the `greet` task defined in the `greeting.py` file, you would run:

```bash
flyte run greeting.py greet --message "Good morning!"
```

This command:
1. **Temporarily deploys** the task environment named `greeting_env` (held by the variable `env`) that contains the `greet` task.
2. **Executes** the `greet` function with argument `message` set to `"Good morning!"`. Note that `message` is the actual parameter name defined in the function signature.
3. **Returns** the execution results and displays them in the terminal.

For more details on how `flyte run` and `flyte.run()` work under the hood, see **Run and deploy tasks > How task run works**.

## Persistent deployment

The `flyte deploy` CLI command and the `flyte.deploy()` SDK function are used to **persistently deploy** a task environment (and all its contained tasks) to the backend.
The tasks within the deployed environment will appear in the **Tasks list** UI on the backend and can then be executed multiple times without needing to redeploy them.

### Programmatic

You can deploy programmatically using the `flyte.deploy()` function:

```python
# greeting.py

import flyte

env = flyte.TaskEnvironment(name="greeting_env")

@env.task
async def greet(message: str) -> str:
    return f"{message}!"

if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(env)
    print(deployments[0].summary_repr())
```

Now you can deploy the `greeting_env` task environment (and therefore the `greet()` task) just by executing the `greeting.py` file locally as a script.

```bash
python greeting.py
```

### CLI

The general form of the command for deploying a task environment from a local file is:

```bash
flyte deploy <file_path> <task_environment_variable>
```

So, using the same `greeting.py` file as before, you can deploy the `greeting_env` task environment like this:

```bash
flyte deploy greeting.py env
```

This command deploys the task environment *assigned to the variable `env`* in the `greeting.py` file, which is the `TaskEnvironment` named `greeting_env`.

Notice that you must specify the *variable* to which the `TaskEnvironment` is assigned (`env` in this case), not the name of the environment itself (`greeting_env`).

Deploying a task environment deploys all tasks defined within it. Here, that means all functions decorated with `@env.task`.
In this case there is just one: `greet()`.

For more details on how `flyte deploy` and `flyte.deploy()` work under the hood, see **Run and deploy tasks > How task deployment works**.

## Running already deployed tasks

If you have already deployed your task environment, you can run its tasks without redeploying by using the `flyte run` CLI command or the `flyte.run()` SDK function in a slightly different way. Alternatively, you can always initiate execution of a deployed task from the UI.

### Programmatic

You can run already-deployed tasks programmatically using the `flyte.run()` function.
For example, to run the previously deployed `greet` task from the `greeting_env` environment:

```python
# greeting.py

import flyte

env = flyte.TaskEnvironment(name="greeting_env")

@env.task
async def greet(message: str) -> str:
    return f"{message}!"

if __name__ == "__main__":
    flyte.init_from_config()
    flyte.deploy(env)
    task = flyte.remote.Task.get("greeting_env.greet", auto_version="latest")
    result = flyte.run(task, message="Good morning!")
    print(f"Result: {result}")
```

When you execute this script locally, it will:

- Deploy the `greeting_env` task environment as before.
- Retrieve the already-deployed `greet` task using `flyte.remote.Task.get()`, specifying its full task reference as a string: `"greeting_env.greet"`.
- Call `flyte.run()` with the retrieved task and its argument.

For more details on how running already-deployed tasks works, see **Run and deploy tasks > How task run works > Running deployed tasks**.

### CLI

To run a permanently deployed task using the `flyte run` CLI command, use the special `deployed-task` keyword followed by the task reference in the format `{environment_name}.{task_name}`. For example, to run the previously deployed `greet` task from the `greeting_env` environment:

```bash
flyte run deployed-task greeting_env.greet --message "World"
```

Notice that now that the task environment is deployed, you use its name (`greeting_env`), not by the variable name to which it was assigned in source code (`env`).
The task environment name plus the task name (`greet`) are combined with a dot (`.`) to form the full task reference: `greeting_env.greet`.
The special `deployed-task` keyword tells the CLI that you are referring to a task that has already been deployed. In effect, it replaces the file path argument used for ephemeral runs.

When executed, this command will run the already-deployed `greet` task with argument `message` set to `"World"`. You will see the result printed in the terminal. You can also, of course, observe the execution in the **Runs list** UI.

To execute a deployed task in a different project or domain than your configured defaults, use `--run-project` and `--run-domain`:

```bash
flyte run --run-project prod-project --run-domain production deployed-task greeting_env.greet --message "World"
```

For all `flyte run` options, see **Run and deploy tasks > Run command options**.

## Configuring runs with `flyte.with_runcontext()`

Both `flyte run` and `flyte.run()` accept a range of invocation-time parameters that control where the run executes, where outputs are stored, caching behavior, and more.
Programmatically, these are set with `flyte.with_runcontext()` before calling `.run()`.
Inside a running task, `flyte.ctx()` provides read access to the same context.

For the full parameter reference, see **Run and deploy tasks > Run context**.

<!--
TODO: Add link to Flyte remote documentation when available
For details on Flyte remote functionality, see the [Flyte remote]().
-->

## Subpages
- **Run and deploy tasks > How task run works**
- **Run and deploy tasks > Interact with runs and actions**
- **Run and deploy tasks > Work with local data**
- **Run and deploy tasks > Run command options**
- **Run and deploy tasks > How task deployment works**
- **Run and deploy tasks > Deploy command options**
- **Run and deploy tasks > Code packaging for remote execution**
- **Run and deploy tasks > Running Tasks via Webhooks**
- **Run and deploy tasks > Deployment patterns**
- **Run and deploy tasks > Run context**


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-deployment/how-task-run-works ===

# How task run works

The `flyte run` command and `flyte.run()` SDK function support three primary execution modes:

1. **Ephemeral deployment + run**: Automatically prepare task environments ephemerally and execute tasks (development shortcut)
2. **Run deployed task**: Execute permanently deployed tasks without redeployment
3. **Local execution**: Run tasks on your local machine for development and testing

Additionally, you can run deployed tasks through the Flyte/Union UI for interactive execution and monitoring.

## Ephemeral deployment + run: The development shortcut

The most common development pattern combines ephemeral task preparation and execution in a single command, automatically handling the temporary deployment process when needed.

### Programmatic

```python
import flyte

env = flyte.TaskEnvironment(name="my_env")

@env.task
async def my_task(name: str) -> str:
    return f"Hello, {name}!"

if __name__ == "__main__":
    flyte.init_from_config()

    # Deploy and run in one step
    result = flyte.run(my_task, name="World")
    print(f"Result: {result}")
    print(f"Execution URL: {result.url}")
```

### CLI

```bash
flyte run my_example.py my_task --name "World"
```

With explicit project and domain:

```bash
flyte run --project my-project --domain development my_example.py my_task --name "World"
```

With deployment options:

```bash
flyte run --version v1.0.0 --copy-style all my_example.py my_task --name "World"
```

**How it works:**
1. **Environment discovery**: Flyte loads the specified Python file and identifies task environments
2. **Ephemeral preparation**: Temporarily prepares the task environment for execution (similar to deployment but not persistent)
3. **Task execution**: Immediately runs the specified task with provided arguments in the ephemeral environment
4. **Result return**: Returns execution results and monitoring URL
5. **Cleanup**: The ephemeral environment is not stored permanently in the backend

**Benefits of ephemeral deployment + run:**
- **Development efficiency**: No separate permanent deployment step required
- **Always current**: Uses your latest code changes without polluting the backend
- **Clean development**: Ephemeral environments don't clutter your task registry
- **Integrated workflow**: Single command for complete development cycle

## Running deployed tasks

For production workflows or when you want to use stable deployed versions, you can run tasks that have been **permanently deployed** with `flyte deploy` without triggering any deployment process.

### Programmatic

```python
import flyte

flyte.init_from_config()

# Method 1: Using remote task reference
deployed_task = flyte.remote.Task.get("my_env.my_task", version="v1.0.0")
result = flyte.run(deployed_task, name="World")

# Method 2: Get latest version
deployed_task = flyte.remote.Task.get("my_env.my_task", auto_version="latest")
result = flyte.run(deployed_task, name="World")
```

### CLI

```bash
flyte run deployed-task my_env.my_task --name "World"
```

With a specific project and domain:

```bash
flyte run --project prod --domain production deployed-task my_env.my_task --batch_size 1000
```

**Task reference format:** `{environment_name}.{task_name}`
- `environment_name`: The `name` property of your `TaskEnvironment`
- `task_name`: The function name of your task

>[!NOTE]
> When you deploy a task environment with `flyte deploy`, you specify the `TaskEnvironment` by the variable to which it is assigned.
> Once deployed, you refer to it by its `name` property.

**Benefits of running deployed tasks:**
- **Performance**: No deployment overhead, faster execution startup
- **Stability**: Uses tested, stable versions of your code
- **Production safety**: Isolated from local development changes
- **Version control**: Explicit control over which code version runs

## Local execution

For development, debugging, and testing, you can run tasks locally on your machine without any backend interaction.

### Programmatic

```python
import flyte

env = flyte.TaskEnvironment(name="my_env")

@env.task
async def my_task(name: str) -> str:
    return f"Hello, {name}!"

# Method 1: No client configured (defaults to local)
result = flyte.run(my_task, name="World")

# Method 2: Explicit local mode
flyte.init_from_config()  # Client configured
result = flyte.with_runcontext(mode="local").run(my_task, name="World")
```

### CLI

```bash
flyte run --local my_example.py my_task --name "World"
```

With development data:

```bash
flyte run --local data_pipeline.py process_data --input_path "/local/data" --debug true
```

**Benefits of local execution:**
- **Rapid development**: Instant feedback without network latency
- **Debugging**: Full access to local debugging tools
- **Offline development**: Works without backend connectivity
- **Resource efficiency**: Uses local compute resources

## Running tasks through the Union UI

If you are running your Flyte code on a Union backend, the UI provides an interactive way to run deployed tasks with form-based input and real-time monitoring.

### Accessing task execution in the Union UI

1. **Navigate to tasks**: Go to your project → domain → Tasks section
2. **Select task**: Choose the task environment and specific task
3. **Launch execution**: Click "Launch" to open the execution form
4. **Provide inputs**: Fill in task parameters through the web interface
5. **Monitor progress**: Watch real-time execution progress and logs

**UI execution benefits:**
- **User-friendly**: No command-line expertise required
- **Visual monitoring**: Real-time progress visualization
- **Input validation**: Built-in parameter validation and type checking
- **Execution history**: Easy access to previous runs and results
- **Sharing**: Shareable execution URLs for collaboration

Here is a short video demonstrating task execution through the Union UI:

📺 [Watch on YouTube](https://www.youtube.com/watch?v=id="8jbau9yGoDg)

## Execution flow and architecture

### Fast registration architecture

Flyte v2 uses "fast registration" to enable rapid development cycles:

#### How it works

1. **Container images** contain the runtime environment and dependencies
2. **Code bundles** contain your Python source code (stored separately)
3. **At runtime**: Code bundles are downloaded and injected into running containers

#### Benefits

- **Rapid iteration**: Update code without rebuilding images
- **Resource efficiency**: Share images across multiple deployments
- **Version flexibility**: Run different code versions with same base image
- **Caching optimization**: Separate caching for images vs. code

#### When code gets injected

At task execution time, the fast registration process follows these steps:

1. **Container starts** with the base image containing runtime environment and dependencies
2. **Code bundle download**: The Flyte agent downloads your Python code bundle from storage
3. **Code extraction**: The code bundle is extracted and mounted into the running container
4. **Task execution**: Your task function executes with the injected code

### Ephemeral preparation logic

When using ephemeral deploy + run mode, Flyte determines whether temporary preparation is needed:

```mermaid
graph TD
    A[flyte run command] --> B{Need preparation?}
    B -->|Yes| C[Ephemeral preparation]
    B -->|No| D[Use cached preparation]
    C --> E[Execute task]
    D --> E
    E --> F[Cleanup ephemeral environment]
```

### Execution modes comparison

| Mode | Deployment | Performance | Use Case | Code Version |
|------|------------|-------------|-----------|--------------|
| Ephemeral Deploy + Run | Ephemeral (temporary) | Medium | Development, testing | Latest local |
| Run Deployed | None (uses permanent deployment) | Fast | Production, stable runs | Deployed version |
| Local | None | Variable | Development, debugging | Local |
| UI | None | Fast | Interactive, collaboration | Deployed version |


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-deployment/interacting-with-runs ===

# Interact with runs and actions

When a task is launched, the resulting execution is called a **run**.
Because tasks typically call other tasks, a run will almost always involve multiple sub-task executions. Each such execution is called an **action**.

Through the Flyte SDK and CLI, you can interact with the run and its actions to monitor progress, retrieve results, and access data. This section explains how to work with runs and actions programmatically and through the CLI.

## Understanding runs and actions

Runs are not declared explicitly in the code of the entry point task.
Instead, they are simply a result of the task being invoked in a specific way:
* User with `flyte run`
* User via the UI
* Other code calling `flyte.run()`
* [Trigger](../task-configuration/triggers)

When a task is invoked in one of these ways, it creates a run to represent the execution of that task and all its nested tasks, considered together.
Each task execution within that run is represented by an **action**.
The entry point task execution is represented by the main action (usually called `a0`), and then every nested call of one task from another creates an additional action.

```mermaid
graph TD
    A[Run] --> B[Action a0 - Main task]
    B --> C[Action a1 - Nested task]
    B --> D[Action a2 - Nested task]
    D --> E[Action a3 - Deeply nested task]
```

Because what constitutes a run depends only on how a task is invoked, the same task can execute as a deeply nested action in one run and the main action in another run.
Unlike Flyte 1, there is no explicit `@workflow` construct in Flyte 2; instead, "workflows" are defined implicitly by the structure of task composition and the entry point chosen at runtime.

> [!NOTE]
> Despite there being no explicit `@workflow` decorator, you'll often see the assemblage of tasks referred to as a "workflow" in documentation and discussions. The top-most task in a run is sometimes referred to as the "parent", "driver", or "entry point" task of the "workflow".
> In these docs we will sometime use "workflow" informally to refer to the collection of tasks (considered statically) involved in a run.

### Key concepts

- **Attempts**: Each action can have multiple attempts due to retries. Retries occur for two reasons:
  - User-configured retries for handling transient failures
  - Automatic system retries for infrastructure issues

- **Phases**: Both runs and actions progress through phases (e.g., QUEUED, RUNNING, SUCCEEDED, FAILED) until reaching a terminal state

- **Durability**: Flyte is a durable execution engine, so every input, output, failure, and attempt is recorded for each action. All data is persisted, allowing you to retrieve information about runs and actions even after completion

## Working with runs

Runs are created when you execute tasks using `flyte run` or `flyte.run()`. For details on running tasks, see [how task run works](./how-task-run-works). To learn about running previously deployed remote tasks, see [remote tasks](../task-programming/remote-tasks).

### Retrieving a run

### Programmatic

Use `flyte.remote.Run.get()` to retrieve information about a run:

```python
import flyte

flyte.init_from_config()

# Get a run by name
run = flyte.remote.Run.get("my_run_name")

# Access basic information
print(run.url)        # UI URL for the run
print(run.action.phase)  # Phase of the main action
```

### CLI

Get a specific run:

```bash
flyte get run my_run_name
```

List all runs:

```bash
flyte get run
```

Use `--project` and `--domain` to scope results to a specific [project-domain pair](../projects-and-domains).
For all available options, see the [CLI reference](../../api-reference/flyte-cli#flyte-get-run).

### Watching run progress

Monitor a run as it progresses through phases:

```python
# Wait for run to complete
run = flyte.run(my_task, input_data="test")
run.wait()  # Blocks until terminal state

# Check if done
if run.action.done():
    print("Run completed!")
```

### Getting detailed run information

Use `flyte.remote.RunDetails` for comprehensive information including nested actions and metadata:

```python
run_details = flyte.remote.RunDetails.get(name="my_run_name")

# Access detailed information
print(run_details.pb2)  # Full protobuf representation
```

## Working with actions

Actions represent individual task executions within a run. Each action has a unique identifier within its parent run.

### Retrieving an action

### Programmatic

```python
# Get a specific action by run name and action name
action = flyte.remote.Action.get(
    run_name="my_run_name",
    name="a0"  # Main action
)

# Access action information
print(action.phase)       # Current phase
print(action.task_name)   # Task being executed
print(action.start_time)  # Execution start time
```

### CLI

Get a specific action:

```bash
flyte get action my_run_name a0
```

List all actions for a run:

```bash
flyte get action my_run_name
```

For all available options, see the [CLI reference](../../api-reference/flyte-cli#flyte-get-action).

### Nested actions

Deeply nested actions are uniquely identified by their path under the run:

```python
# Get a nested action
nested_action = flyte.remote.Action.get(
    run_name="my_run_name",
    name="a1"  # Nested action identifier
)
```

### Getting detailed action information

Use `flyte.remote.ActionDetails` for comprehensive action information:

```python
action_details = flyte.remote.ActionDetails.get(
    run_name="my_run_name",
    name="a0"
)

# Access detailed information
print(action_details.pb2)  # Full protobuf representation
```

## Retrieving inputs and outputs

### Programmatic

Both `Run` and `Action` objects provide methods to retrieve inputs and outputs:

```python
run = flyte.remote.Run.get("my_run_name")

# Get inputs - returns ActionInputs (dict-like)
inputs = run.inputs()
print(inputs)  # {"param_name": value, ...}

# Get outputs - returns tuple
outputs = run.outputs()
print(outputs)  # (result1, result2, ...)

# Single output
single_output = outputs[0]

# No outputs are represented as (None,)
```

**Important notes:**

- **Inputs**: Returned as `flyte.remote.ActionInputs`, a dictionary with parameter names as keys and values as the actual data passed in
- **Outputs**: Always returned as `flyte.remote.ActionOutputs` tuple, even for single outputs or no outputs
- **No outputs**: Represented as `(None,)`
- **Availability**: Outputs are only available if the action completed successfully
- **Type safety**: Flyte's rich type system converts data to an intermediate representation, allowing retrieval even without the original dependencies installed

### CLI

Get inputs and outputs for a run:

```bash
flyte get io my_run_name
```

Get inputs and outputs for a specific action:

```bash
flyte get io my_run_name a1
```

For all available options, see the [CLI reference](../../api-reference/flyte-cli#flyte-get-io).

### Handling failures

If an action fails, outputs are not available, but you can retrieve error information:

```python
action = flyte.remote.Action.get(run_name="my_run_name", name="a0")

if action.phase == flyte.models.ActionPhase.FAILED:
    # Outputs will raise an error
    try:
        outputs = action.outputs()
    except RuntimeError as e:
        print("Action failed, outputs not available")

    # Get error details instead
    action_details = flyte.remote.ActionDetails.get(
        run_name="my_run_name",
        name="a0"
    )
    print(action_details.pb2.error_info)
```

## Understanding data storage

Flyte handles different types of data differently, as explained in [data flow](../run-scaling/data-flow):

- **Parameterized data** (primitives, small objects): Returned directly in inputs/outputs
- **Large data** (files, directories, DataFrames, models): Stored in cloud storage (S3, GCS, Azure Blob Storage)

When you retrieve outputs containing large data, Flyte returns references rather than the actual data. To access the actual raw data, you need proper cloud storage permissions and configuration.

## Accessing large data from cloud storage

To download and work with files, directories, and DataFrames stored in cloud object storage, you must configure storage access with appropriate credentials.

### S3 storage access

To access data stored in Amazon S3:

**1. Set environment variables:**

```bash
export FLYTE_AWS_ACCESS_KEY_ID="your-access-key-id"
export FLYTE_AWS_SECRET_ACCESS_KEY="your-secret-access-key"
```

These are standard AWS credential environment variables that Flyte recognizes.

**2. Initialize Flyte with S3 storage configuration:**

```python
import flyte
import flyte.storage

# Auto-configure from environment variables
flyte.init_from_config(
    storage=flyte.storage.S3.auto(region="us-east-2")
)

# Or provide credentials explicitly
flyte.init_from_config(
    storage=flyte.storage.S3(
        access_key_id="your-access-key-id",
        secret_access_key="your-secret-access-key",
        region="us-east-2"
    )
)
```

**3. Access data from outputs:**

```python
run = flyte.remote.Run.get("my_run_name")
outputs = run.outputs()

# Outputs containing files, dataframes, etc. can now be downloaded
dataframe = outputs[0]
df = await dataframe.open(pd.DataFrame).all()
```

### GCS storage access

To access data stored in Google Cloud Storage:

**1. Set environment variables:**

```bash
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
```

This is the standard Google Cloud authentication method using service account credentials.

**2. Initialize Flyte with GCS storage configuration:**

```python
import flyte
import flyte.storage

# Auto-configure from environment
flyte.init_from_config(
    storage=flyte.storage.GCS.auto()
)

# Or configure explicitly
flyte.init_from_config(
    storage=flyte.storage.GCS()
)
```

**3. Access data from outputs:**

```python
run = flyte.remote.Run.get("my_run_name")
outputs = run.outputs()

# Download data as needed
file_output = outputs[0]
# Work with file output
```

### Azure Blob Storage access

To access data stored in Azure Blob Storage (ABFS):

**1. Set environment variables:**

For storage account key authentication:
```bash
export AZURE_STORAGE_ACCOUNT_NAME="your-storage-account"
export AZURE_STORAGE_ACCOUNT_KEY="your-account-key"
```

For service principal authentication:
```bash
export AZURE_TENANT_ID="your-tenant-id"
export AZURE_CLIENT_ID="your-client-id"
export AZURE_CLIENT_SECRET="your-client-secret"
export AZURE_STORAGE_ACCOUNT_NAME="your-storage-account"
```

**2. Initialize Flyte with Azure storage configuration:**

```python
import flyte
import flyte.storage

# Auto-configure from environment variables
flyte.init_from_config(
    storage=flyte.storage.ABFS.auto()
)

# Or provide credentials explicitly
flyte.init_from_config(
    storage=flyte.storage.ABFS(
        account_name="your-storage-account",
        account_key="your-account-key"
    )
)

# Or use service principal
flyte.init_from_config(
    storage=flyte.storage.ABFS(
        account_name="your-storage-account",
        tenant_id="your-tenant-id",
        client_id="your-client-id",
        client_secret="your-client-secret"
    )
)
```

**3. Access data from outputs:**

```python
run = flyte.remote.Run.get("my_run_name")
outputs = run.outputs()

# Download data as needed
directory_output = outputs[0]
# Work with directory output
```

## Complete example

Here's a complete example showing how to launch a run and interact with it:

```python
import flyte
import flyte.storage

# Initialize with storage access
flyte.init_from_config(
    storage=flyte.storage.S3.auto(region="us-east-2")
)

# Define and run a task
env = flyte.TaskEnvironment(name="data_processing")

@env.task
async def process_data(input_value: str) -> str:
    return f"Processed: {input_value}"

# Launch the run
run = flyte.run(process_data, input_value="test_data")

# Monitor progress
print(f"Run URL: {run.url}")
run.wait()

# Check status
if run.action.done():
    print(f"Run completed with phase: {run.action.phase}")

    # Get inputs and outputs
    inputs = run.inputs()
    print(f"Inputs: {inputs}")

    outputs = run.outputs()
    print(f"Outputs: {outputs}")

    # Access the result
    result = outputs[0]
    print(f"Result: {result}")
```

## API reference

### Key classes

- `flyte.remote.Run` - Represents a run with basic information
- `flyte.remote.RunDetails` - Detailed run information including all actions
- `flyte.remote.Action` - Represents an action with basic information
- `flyte.remote.ActionDetails` - Detailed action information including error details
- `flyte.remote.ActionInputs` - Dictionary-like object containing action inputs
- `flyte.remote.ActionOutputs` - Tuple containing action outputs

### CLI commands

For complete CLI documentation and all available options, see the [Flyte CLI reference](../../api-reference/flyte-cli):
- [`flyte get run`](../../api-reference/flyte-cli#flyte-get-run) - Get run information
- [`flyte get action`](../../api-reference/flyte-cli#flyte-get-action) - Get action information
- [`flyte get io`](../../api-reference/flyte-cli#flyte-get-io) - Get inputs and outputs
- [`flyte get logs`](../../api-reference/flyte-cli#flyte-get-logs) - Get action logs

### Storage configuration

- `flyte.storage.S3` - Amazon S3 configuration
- `flyte.storage.GCS` - Google Cloud Storage configuration
- `flyte.storage.ABFS` - Azure Blob Storage configuration

For more details on data flow and storage, see [data flow](../run-scaling/data-flow).


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-deployment/work-with-local-data ===

# Work with local data

When running Flyte tasks that take inputs like DataFrames, files, or directories, data is passed between actions through the configured blob store. For details on how data flows through your workflows, see [data flow](../run-scaling/data-flow).

Flyte provides several built-in types for handling data:
- `flyte.io.DataFrame` for tabular data
- `flyte.io.File` for individual files
- `flyte.io.Dir` for directories

You can also create custom type extensions for specialized data types. See [custom types](../task-programming/handling-custom-types) for details.

## Local execution

One of the most powerful features of Flyte is the ability to work with data entirely locally, without creating a remote run. When you run tasks in local mode, all inputs, outputs, and intermediate data stay on your local machine.

```python
import flyte

env = flyte.TaskEnvironment(name="local_data")

@env.task
async def process_data(data: str) -> str:
    return f"Processed: {data}"

# Run locally - no remote storage needed
run = flyte.with_runcontext(mode="local").run(process_data, data="test")
run.wait()
print(run.outputs()[0])
```

For more details on local execution, see [how task run works](./how-task-run-works#local-execution).

## Uploading local data to remote runs

When you want to send local data to a remote task, you need to upload it first. Flyte provides a secure data uploading system that handles this automatically. The same system used for [code bundling](./packaging) can upload files, DataFrames, and directories.

To upload local data, use the Flyte core representation for that type with the `from_local_sync()` method.

### Uploading DataFrames

Use `flyte.io.DataFrame.from_local_sync()` to upload a local DataFrame:

```python
from typing import Annotated

import pandas as pd

import flyte
import flyte.io

img = flyte.Image.from_debian_base()
img = img.with_pip_packages("pandas", "pyarrow")

env = flyte.TaskEnvironment(
    "dataframe_usage",
    image=img,
    resources=flyte.Resources(cpu="1", memory="2Gi"),
)

@env.task
async def process_dataframe(df: pd.DataFrame) -> pd.DataFrame:
    """Process a DataFrame and return the result."""
    df["processed"] = True
    return df

if __name__ == "__main__":
    flyte.init_from_config()

    # Create a local pandas DataFrame
    local_df = pd.DataFrame({
        "name": ["Alice", "Bob", "Charlie"],
        "value": [10, 20, 30]
    })

    # Upload the local DataFrame for remote execution
    uploaded_df = flyte.io.DataFrame.from_local_sync(local_df)

    # Pass to a remote task
    run = flyte.run(process_dataframe, df=uploaded_df)
    print(f"Run URL: {run.url}")
    run.wait()
    print(run.outputs()[0])
```

### Uploading files

Use `flyte.io.File.from_local_sync()` to upload a local file:

```python
import tempfile

import flyte
from flyte.io import File

env = flyte.TaskEnvironment(name="file-local")

@env.task
async def process_file(file: File) -> str:
    """Read and process a file."""
    async with file.open("rb") as f:
        content = bytes(await f.read())
        return content.decode("utf-8")

if __name__ == "__main__":
    flyte.init_from_config()

    # Create a temporary local file
    with tempfile.NamedTemporaryFile(mode="w", delete=False, suffix=".txt") as temp:
        temp.write("Hello, Flyte!")
        temp_path = temp.name

    # Upload the local file for remote execution
    file = File.from_local_sync(temp_path)

    # Pass to a remote task
    run = flyte.run(process_file, file=file)
    print(f"Run URL: {run.url}")
    run.wait()
    print(run.outputs()[0])
```

### Uploading directories

Use `flyte.io.Dir.from_local_sync()` to upload a local directory:

```python
import os
import tempfile

import flyte
from flyte.io import Dir

env = flyte.TaskEnvironment(name="dir-local")

@env.task
async def process_dir(dir: Dir) -> dict[str, str]:
    """Process a directory and return file contents."""
    file_contents = {}
    async for file in dir.walk(recursive=False):
        if file.name.endswith(".py"):
            async with file.open("rb") as f:
                content = bytes(await f.read())
                file_contents[file.name] = content.decode("utf-8")[:100]
    return file_contents

if __name__ == "__main__":
    flyte.init_from_config()

    # Create a temporary directory with test files
    with tempfile.TemporaryDirectory() as temp_dir:
        for i in range(3):
            with open(os.path.join(temp_dir, f"file{i}.py"), "w") as f:
                f.write(f"print('Hello from file {i}!')")

        # Upload the local directory for remote execution
        dir = Dir.from_local_sync(temp_dir)

        # Pass to a remote task
        run = flyte.run(process_dir, dir=dir)
        print(f"Run URL: {run.url}")
        run.wait()
        print(run.outputs()[0])
```

## Passing outputs between runs

If you're passing outputs from a previous run to a new run, no upload is needed. Flyte's data is represented using native references that point to storage locations, so passing them between runs works automatically:

```python
import flyte

flyte.init_from_config()

# Get outputs from a previous run
previous_run = flyte.remote.Run.get("my_previous_run")
previous_output = previous_run.outputs()[0]  # Already a Flyte reference

# Pass directly to a new run - no upload needed
new_run = flyte.run(my_task, data=previous_output)
```

## Performance considerations

The `from_local_sync()` method uses HTTP to upload data. This is convenient but not the most performant option for large datasets.

**Best suited for:**
- Small to medium test datasets
- Development and debugging
- Quick prototyping

**For larger data uploads**, configure cloud storage access and use `flyte.storage` directly:

```python
import flyte
import flyte.storage

# Configure storage access
flyte.init_from_config(
    storage=flyte.storage.S3.auto(region="us-east-2")
)
```

For details on configuring storage access, see [interact with runs and actions](./interacting-with-runs#accessing-large-data-from-cloud-storage).

## Summary

| Scenario | Approach |
|----------|----------|
| Local development and testing | Use local execution mode |
| Small test data to remote tasks | Use `from_local_sync()` |
| Passing data between runs | Pass outputs directly (automatic) |
| Large datasets | Configure `flyte.storage` for direct cloud access |


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-deployment/run-command-options ===

# Run command options

The `flyte run` command provides the following options:

**`flyte run [OPTIONS] <PATH>|deployed_task <TASK_NAME>`**

| Option                      | Short | Type   | Default                   | Description                                            |
|-----------------------------|-------|--------|---------------------------|--------------------------------------------------------|
| `--project`                 | `-p`  | text   | *from config*             | Project to run tasks in                                |
| `--domain`                  | `-d`  | text   | *from config*             | Domain to run tasks in                                 |
| `--local`                   |       | flag   | `false`                   | Run the task locally                                   |
| `--copy-style`              |       | choice | `loaded_modules|all|none` | Code bundling strategy                                 |
| `--root-dir`                |       | path   | *current dir*             | Override source root directory                         |
| `--raw-data-path`           |       | text   |                           | Override the output location for offloaded data types. |
| `--service-account`         |       | text   |                           | Kubernetes service account.                            |
| `--name`                    |       | text   |                           | Name of the run.                                       |
| `--follow`                  | `-f`  | flag   | `false`                   | Wait and watch logs for the parent action.             |
| `--image`                   |       | text   |                           | Image to be used in the run (format: `name=uri`).      |
| `--no-sync-local-sys-paths` |       | flag   | `false`                   | Disable synchronization of local sys.path entries.      |
| `--run-project`             |       | text   | *from config*             | Execute deployed task in this project (`deployed-task` only). |
| `--run-domain`              |       | text   | *from config*             | Execute deployed task in this domain (`deployed-task` only).  |

## `--project`, `--domain`

**`flyte run --domain <DOMAIN> --project <PROJECT> <PATH>|deployed_task <TASK_NAME>`**

You can specify `--project` and `--domain` which will override any defaults defined in your `config.yaml`:

```bash
flyte run my_example.py my_task
```

Specify a target project and domain:

```bash
flyte run --project my-project --domain development my_example.py my_task
```

## `--run-project`, `--run-domain`

**`flyte run --run-project <PROJECT> --run-domain <DOMAIN> deployed-task <TASK_REF>`**

When using the `deployed-task` subcommand, `--run-project` and `--run-domain` specify the [project-domain pair](../projects-and-domains) in which to *execute* the task. This lets you run a deployed task in a different project or domain than the one configured in your `config.yaml`:

```bash
flyte run --run-project prod-project --run-domain production deployed-task my_env.my_task
```

If not provided, these default to the `task.project` and `task.domain` values in your configuration file. These options only apply to the `deployed-task` subcommand and are ignored for file-based runs.

## `--local`

**`flyte run --local <PATH> <TASK_NAME>`**

The `--local` option runs tasks locally instead of submitting them to the remote Flyte backend:

```bash
flyte run --local my_example.py my_task --input "test_data"
```

Compare with remote execution:

```bash
flyte run my_example.py my_task --input "test_data"
```

### When to use local execution

- **Development and testing**: Quick iteration without deployment overhead
- **Debugging**: Full access to local debugging tools and environment
- **Resource constraints**: When remote resources are unavailable or expensive
- **Data locality**: When working with large local datasets

## `--copy-style`

**`flyte run --copy-style [loaded_modules|all|none] <PATH> <TASK_NAME>`**

The `--copy-style` option controls code bundling for remote execution.
This applies to the ephemeral preparation step of the `flyte run` command and works similarly to `flyte deploy`:

Smart bundling (default) — includes only imported project modules:

```bash
flyte run --copy-style loaded_modules my_example.py my_task
```

Include all project files:

```bash
flyte run --copy-style all my_example.py my_task
```

No code bundling (task must be pre-deployed):

```bash
flyte run --copy-style none deployed_task my_deployed_task
```

### Copy style options

- **`loaded_modules` (default)**: Bundles only imported Python modules from your project
- **`all`**: Includes all files in the project directory
- **`none`**: No bundling; requires permanently deployed tasks

## `--root-dir`

**`flyte run --root-dir <DIRECTORY> <PATH> <TASK_NAME>`**

Override the source directory for code bundling and import resolution:

Run from a monorepo root with a specific root directory:

```bash
flyte run --root-dir ./services/ml ./services/ml/my_example.py my_task
```

Handle cross-directory imports:

```bash
flyte run --root-dir .. my_example.py my_workflow
```
This applies to the ephemeral preparation step of the `flyte run` command.
It works identically to the `flyte deploy` command's `--root-dir` option.

## `--raw-data-path`

**`flyte run --raw-data-path <PATH> <SOURCE> <TASK_NAME>`**

Override the default output location for offloaded data types (large objects, DataFrames, etc.):

Use a custom S3 location for large outputs:

```bash
flyte run --raw-data-path s3://my-bucket/custom-path/ my_example.py process_large_data
```

Use a local directory for development:

```bash
flyte run --local --raw-data-path ./output/ my_example.py my_task
```

### Use cases

- **Custom storage locations**: Direct outputs to specific S3 buckets or paths
- **Cost optimization**: Use cheaper storage tiers for temporary data
- **Access control**: Ensure outputs go to locations with appropriate permissions
- **Local development**: Store large outputs locally when testing

## `--service-account`

**`flyte run --service-account <ACCOUNT_NAME> <PATH> <TASK_NAME>`**

Specify a Kubernetes service account for task execution:

```bash
flyte run --service-account ml-service-account my_example.py train_model
flyte run --service-account data-reader-sa my_example.py load_data
```

### Use cases

- **Cloud resource access**: Service accounts with permissions for S3, GCS, etc.
- **Security isolation**: Different service accounts for different workload types
- **Compliance requirements**: Enforcing specific identity and access policies

## `--name`

**`flyte run --name <EXECUTION_NAME> <PATH> <TASK_NAME>`**

Provide a custom name for the execution run:

```bash
flyte run --name "daily-training-run-2024-12-02" my_example.py train_model
flyte run --name "experiment-lr-0.01-batch-32" my_example.py hyperparameter_sweep
```

### Benefits of custom names

- **Easy identification**: Find specific runs in the Flyte console
- **Experiment tracking**: Include key parameters or dates in names
- **Automation**: Programmatically generate meaningful names for scheduled runs

## `--follow`

**`flyte run --follow <PATH> <TASK_NAME>`**

Wait and watch logs for the execution in real-time:

```bash
flyte run --follow my_example.py long_running_task
```

Combine with other options:

```bash
flyte run --follow --name "training-session" my_example.py train_model
```

### Behavior

- **Log streaming**: Real-time output from task execution
- **Blocking execution**: Command waits until task completes
- **Exit codes**: Returns appropriate exit code based on task success/failure

## `--image`

**`flyte run --image <IMAGE_MAPPING> <PATH> <TASK_NAME>`**

Override container images during ephemeral preparation, same as the equivalent `flyte deploy` option:

Override a specific named image:

```bash
flyte run --image gpu=ghcr.io/org/gpu:v2.1 my_example.py gpu_task
```

Override the default image:

```bash
flyte run --image ghcr.io/org/custom:latest my_example.py my_task
```

Multiple image overrides:

```bash
flyte run \
  --image base=ghcr.io/org/base:v1.0 \
  --image gpu=ghcr.io/org/gpu:v2.0 \
  my_example.py multi_env_workflow
```

### Image mapping formats

- **Named mapping**: `name=uri` overrides images created with `Image.from_ref_name("name")`
- **Default mapping**: `uri` overrides the default "auto" image
- **Multiple mappings**: Use multiple `--image` flags for different image references

## `--no-sync-local-sys-paths`

**`flyte run --no-sync-local-sys-paths <PATH> <TASK_NAME>`**

Disable synchronization of local `sys.path` entries to the remote execution environment during ephemeral preparation.
Identical to the `flyte deploy` command's `--no-sync-local-sys-paths` option:

```bash
flyte run --no-sync-local-sys-paths my_example.py my_task
```

This advanced option works identically to the deploy command equivalent, useful for:
- **Container isolation**: Prevent local development paths from affecting remote execution
- **Custom environments**: When containers have pre-configured Python paths
- **Security**: Avoiding exposure of local directory structures

## Task argument passing

Arguments are passed directly as function parameters:

CLI — arguments as flags:

```bash
flyte run my_file.py my_task --name "World" --count 5 --debug true
```

SDK — arguments as function parameters:

```python
result = flyte.run(my_task, name="World", count=5, debug=True)
```

## SDK options

The core `flyte run` functionality is also available programmatically through the `flyte.run()` function.
For SDK-level configuration of all run parameters (storage, caching, identity, logging, and more),
see [Run context](./run-context).


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-deployment/how-task-deployment-works ===

# How task deployment works

In this section, we will take a deep dive into how the `flyte deploy` command and the `flyte.deploy()` SDK function work under the hood to deploy tasks to your Flyte backend.

When you perform a deployment, here's what happens:

## 1. Module loading and task environment discovery

In the first step, Flyte determines which files to load in order to search for task environments, based on the command line options provided:

### Single file (default)

```bash
flyte deploy my_example.py env
```

- The file `my_example.py` is executed,
- All declared `TaskEnvironment` objects in the file are instantiated,
  but only the one assigned to the variable `env` is selected for deployment.

### `--all` option

```bash
flyte deploy --all my_example.py
```
- The file `my_example.py` is executed,
- All declared `TaskEnvironment` objects in the file are instantiated and selected for deployment.
- No specific variable name is required.

### `--recursive` option

```bash
flyte deploy --recursive ./directory
```

- The directory is recursively traversed and all Python files are executed and all `TaskEnvironment` objects are instantiated.
- All `TaskEnvironment` objects across all files are selected for deployment.

## 2. Task analysis and serialization

- For every task environment selected for deployment, all of its tasks are identified.
- Task metadata is extracted: parameter types, return types, and resource requirements.
- Each task is serialized into a Flyte `TaskTemplate`.
- Dependency graphs between environments are built (see below).

## 3. Task environment dependency resolution

In many cases, a task in one environment may invoke a task in another environment, establishing a dependency between the two environments.
For example, if `env_a` has a task that calls a task in `env_b`, then `env_a` depends on `env_b`.
This means that when deploying `env_a`, `env_b` must also be deployed to ensure that all tasks can be executed correctly.

To handle this, `TaskEnvironment`s can declare dependencies on other `TaskEnvironment`s using the `depends_on` parameter.
During deployment, the system performs the following steps to resolve these dependencies:

1. Starting with specified environment(s)
2. Recursively discovering all transitive dependencies
3. Including all dependencies in the deployment plan
4. Processing dependencies depth-first to ensure correct order

```python
# Define environments with dependencies
prep_env = flyte.TaskEnvironment(name="preprocessing")
ml_env = flyte.TaskEnvironment(name="ml_training", depends_on=[prep_env])
viz_env = flyte.TaskEnvironment(name="visualization", depends_on=[ml_env])

# Deploy only viz_env - automatically includes ml_env and prep_env
deployment = flyte.deploy(viz_env, version="v2.0.0")

# Or deploy multiple environments explicitly
deployment = flyte.deploy(data_env, ml_env, viz_env, version="v2.0.0")
```

For detailed information about working with multiple environments, see [Multiple Environments](../task-configuration/multiple-environments).

## 4. Code bundle creation and upload

Once the task environments and their dependencies are resolved, Flyte proceeds to package your code into a bundle based on the `copy_style` option:

### `--copy_style loaded_modules` (default)

This is the smart bundling approach that analyzes which Python modules were actually imported during the task environment discovery phase.
It examines the runtime module registry (`sys.modules`) and includes only those modules that meet specific criteria:
they must have source files located within your project directory (not in system locations like `site-packages`), and they must not be part of the Flyte SDK itself.
This selective approach results in smaller, faster-to-upload bundles that contain exactly the code needed to run your tasks, making it ideal for most development and production scenarios.

### `--copy_style all`

This comprehensive bundling strategy takes a directory-walking approach, recursively traversing your entire project directory and including every file it encounters.
Unlike the smart bundling that only includes imported Python modules, this method captures all project files regardless of whether they were imported during discovery.
This is particularly useful for projects that use dynamic imports, load configuration files or data assets at runtime, or have dependencies that aren't captured through normal Python import mechanisms.

### `--copy_style none`

This option completely skips code bundle creation, meaning no source code is packaged or uploaded to cloud storage.
When using this approach, you must provide an explicit version parameter since there's no code bundle to generate a version from.
This strategy is designed for scenarios where your code is already baked into custom container images, eliminating the need for separate code injection during task execution.
It results in the fastest deployment times but requires more complex image management workflows.

### `--root-dir` option

By default, Flyte uses your current working directory as the root for code bundling.
You can override this with `--root-dir` to specify a different base directory - particularly useful for monorepos or when deploying from subdirectories. This affects all copy styles: `loaded_modules` will look for imported modules relative to the root directory, `all` will walk the directory tree starting from the root, and the root directory setting works with any copy style. See the [Deploy command options](./deploy-command-options#--root-dir) for detailed usage examples.

After the code bundle is created (if applicable), it is uploaded to a cloud storage location (like S3 or GCS) accessible by your Flyte backend. It is now ready to be run.

## 5. Image building

If your `TaskEnvironment` specifies [custom images](../task-configuration/container-images), Flyte builds and pushes container images before deploying tasks.
The build process varies based on your configuration and backend type:

### Local image building

When `image.builder` is set to `local` in [your `config.yaml`](../connecting-to-a-cluster), images are built on your local machine using Docker. This approach:
- Requires Docker to be installed and running on your development machine
- Uses Docker BuildKit to build images from generated Dockerfiles or your custom Dockerfile
- Pushes built images to the container registry specified in your `Image` configuration
- Is the only option available for Flyte OSS instances

### Remote image building

When `image.builder` is set to `remote` in [your `config.yaml`](../connecting-to-a-cluster), images are built on cloud infrastructure. This approach:
- Builds images using Union's ImageBuilder service (currently only available for Union backends, not OSS Flyte)
- Requires no local Docker installation or configuration
- Can push to Union's internal registry or external registries you specify
- Provides faster, more consistent builds by leveraging cloud resources

> [!NOTE]
> Remote building is currently exclusive to Union backends. OSS Flyte installations must use `local`

## Understanding option relationships

It's important to understand how the various deployment options work together.
The **discovery options** (`--recursive` and `--all`) operate independently of the **bundling options** (`--copy-style`),
giving you flexibility in how you structure your deployments.

Environment discovery determines which files Flyte will examine to find `TaskEnvironment` objects,
while code bundling controls what gets packaged and uploaded for execution.
You can freely combine these approaches.
For example, discovering environments recursively across your entire project while using smart bundling to include only the necessary code modules.

When multiple environments are discovered, they all share the same code bundle, which is efficient for related services or components that use common dependencies:

```bash
flyte deploy --recursive --copy-style loaded_modules ./project
```

> [!NOTE]
> All discovered environments share the same code bundle.

For a full overview of all deployment options, see **Flyte CLI > flyte > flyte deploy**.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-deployment/deploy-command-options ===

# Deploy command options

The `flyte deploy` command provides extensive configuration options:

**`flyte deploy [OPTIONS] <PATH> [TASK_ENV_VARIABLE]`**

| Option                      | Short | Type   | Default                   | Description                                       |
|-----------------------------|-------|--------|---------------------------|---------------------------------------------------|
| `--project`                 | `-p`  | text   | *from config*             | Project to deploy to                              |
| `--domain`                  | `-d`  | text   | *from config*             | Domain to deploy to                               |
| `--version`                 |       | text   | *auto-generated*          | Explicit version tag for deployment               |
| `--dry-run`/`--dryrun`      |       | flag   | `false`                   | Preview deployment without executing              |
| `--all`                     |       | flag   | `false`                   | Deploy all environments in specified path         |
| `--recursive`               | `-r`  | flag   | `false`                   | Deploy environments recursively in subdirectories |
| `--copy-style`              |       | choice | `loaded_modules|all|none` | Code bundling strategy                            |
| `--root-dir`                |       | path   | *current dir*             | Override source root directory                    |
| `--image`                   |       | text   |                           | Image URI mappings (format: `name=uri`)           |
| `--ignore-load-errors`      | `-i`  | flag   | `false`                   | Continue deployment despite module load failures  |
| `--no-sync-local-sys-paths` |       | flag   | `false`                   | Disable local `sys.path` synchronization          |

## `--project`, `--domain`

**`flyte deploy --domain <DOMAIN> --project <PROJECT> <SOURCE_FILE> <TASK_ENV_VARIABLE>`**

You can specify `--project` and `--domain` which will override any defaults defined in your `config.yaml`:

```bash
flyte deploy my_example.py env
```

Specify a target project and domain:

```bash
flyte deploy --project my-project --domain development my_example.py env
```

## `--version`

**`flyte deploy --version <VERSION> <SOURCE_FILE> <TASK_ENV_VARIABLE>`**

The `--version` option controls how deployed tasks are tagged and identified in the Flyte backend:

Auto-generated version (default):

```bash
flyte deploy my_example.py env
```

Explicit version:

```bash
flyte deploy --version v1.0.0 my_example.py env
```

> [!NOTE]
> An explicit version is required when using `--copy-style none`, since there is no code bundle to generate a hash from.

```bash
flyte deploy --copy-style none --version v1.0.0 my_example.py env
```

### When versions are used

- **Explicit versioning**: Provides human-readable task identification (e.g., `v1.0.0`, `prod-2024-12-01`)
- **Auto-generated versions**: When no version is specified, Flyte creates an MD5 hash from the code bundle, environment configuration, and image cache
- **Version requirement**: `copy-style none` mandates explicit versions since there's no code bundle to hash
- **Task referencing**: Versions enable precise task references in `flyte run deployed-task` and workflow invocations

## `--dry-run`

**`flyte deploy --dry-run <SOURCE_FILE> <TASK_ENV_VARIABLE>`**

The `--dry-run` option allows you to preview what would be deployed without actually performing the deployment:

```bash
flyte deploy --dry-run my_example.py env
```

## `--all` and `--recursive`

**`flyte deploy --all <SOURCE_FILE>`**

**`flyte deploy --recursive <DIRECTORY_PATH>`**

Control which environments get discovered and deployed:

**Single environment (default):**

```bash
flyte deploy my_example.py env
```

**All environments in file:**

```bash
flyte deploy --all my_example.py
```

**Recursive directory deployment:**

```bash
flyte deploy --recursive ./src
```

Combine with comprehensive bundling:

```bash
flyte deploy --recursive --copy-style all ./project
```

## `--copy-style`

**`flyte deploy --copy_style [loaded_modules|all|none] <SOURCE_FILE> <TASK_ENV_VARIABLE>`**

The `--copy-style` option controls what gets packaged:

### `--copy-style loaded_modules` (default)

```bash
flyte deploy --copy-style loaded_modules my_example.py env
```

- **Includes**: Only imported Python modules from your project
- **Excludes**: Site-packages, system modules, Flyte SDK
- **Best for**: Most projects (optimal size and speed)

### `--copy-style all`

```bash
flyte deploy --copy-style all my_example.py env
```

- **Includes**: All files in project directory
- **Best for**: Projects with dynamic imports or data files

### `--copy-style none`

```bash
flyte deploy --copy-style none --version v1.0.0 my_example.py env
```

- **Requires**: Explicit version parameter
- **Best for**: Pre-built container images with baked-in code

## `--root-dir`

**`flyte deploy --root-dir <DIRECTORY> <SOURCE_FILE> <TASK_ENV_VARIABLE>`**

The `--root-dir` option overrides the default source directory that Flyte uses as the base for code bundling and import resolution.
This is particularly useful for monorepos and projects with complex directory structures.

### Default behavior (without `--root-dir`)

- Flyte uses the current working directory as the root
- Code bundling starts from this directory
- Import paths are resolved relative to this location

### Common use cases

**Monorepos:**
Deploy a service from the monorepo root:

```bash
flyte deploy --root-dir ./services/ml ./services/ml/my_example.py env
```

Deploy from anywhere in the monorepo:

```bash
cd ./docs/
flyte deploy --root-dir ../services/ml ../services/ml/my_example.py env
```

**Cross-directory imports:**
When a workflow imports modules from sibling directories (e.g., `project/workflows/my_example.py` imports `project/src/utils.py`):

```bash
cd project/workflows/
flyte deploy --root-dir .. my_example.py env
```

**Working directory independence:**
```bash
flyte deploy --root-dir /path/to/project /path/to/project/my_example.py env
```

### How it works

1. **Code bundling**: Files are collected starting from `--root-dir` instead of the current working directory
2. **Import resolution**: Python imports are resolved relative to the specified root directory
3. **Path consistency**: Ensures the same directory structure in local and remote execution environments
4. **Dependency packaging**: Captures all necessary modules that may be located outside the workflow file's immediate directory

### Example with complex project structure
```
my-project/
├── services/
│   ├── ml/
│   │   └── my_example.py     # imports shared.utils
│   └── api/
└── shared/
    └── utils.py
```

```bash
flyte deploy --root-dir ./my-project ./my-project/services/ml/my_example.py env
```

This ensures that both `services/ml/` and `shared/` directories are included in the code bundle, allowing the workflow to successfully import `shared.utils` during remote execution.

## `--image`

**`flyte deploy --image <IMAGE_MAPPING> <SOURCE_FILE> <TASK_ENV_VARIABLE>`**

The `--image` option allows you to override image URIs at deployment time without modifying your code. Format: `imagename=imageuri`

### Named image mappings

```bash
flyte deploy --image base=ghcr.io/org/base:v1.0 my_example.py env
```

Multiple named image mappings:

```bash
flyte deploy \
  --image base=ghcr.io/org/base:v1.0 \
  --image gpu=ghcr.io/org/gpu:v2.0 \
  my_example.py env
```

### Default image mapping

```bash
flyte deploy --image ghcr.io/org/default:latest my_example.py env
```

### How it works

- Named mappings (e.g., `base=URI`) override images created with `Image.from_ref_name("base")`.
- Unnamed mappings (e.g., just `URI`) override the default "auto" image.
- Multiple `--image` flags can be specified.
- Mappings are resolved during the image building phase of deployment.

## `--ignore-load-errors`

**`flyte deploy --ignore-load-errors <SOURCE_PATH> <TASK_ENV_VARIABLE>`**

The `--ignore-load-errors` option allows the deployment process to continue even if some modules fail to load during the environment discovery phase. This is particularly useful for large projects or monorepos where certain modules may have missing dependencies or other issues that prevent them from being imported successfully.

```bash
flyte deploy --recursive --ignore-load-errors ./large-project
```

## `--no-sync-local-sys-paths`

**`flyte deploy --no-sync-local-sys-paths <SOURCE_FILE> <TASK_ENV_VARIABLE>`**

The `--no-sync-local-sys-paths` option disables the automatic synchronization of local `sys.path` entries to the remote container environment. This is an advanced option for specific deployment scenarios.

### Default behavior (path synchronization enabled)

- Flyte captures local `sys.path` entries that are under the root directory
- These paths are passed to the remote container via the `_F_SYS_PATH` environment variable
- At runtime, the remote container adds these paths to its `sys.path`, maintaining the same import environment

### When to disable path synchronization

```bash
flyte deploy --no-sync-local-sys-paths my_example.py env
```

### Use cases for disabling

- **Custom container images**: When your container already has the correct `sys.path` configuration
- **Conflicting path structures**: When local development paths would interfere with container paths
- **Security concerns**: When you don't want to expose local development directory structures
- **Minimal environments**: When you want precise control over what gets added to the container's Python path

### How it works

- **Enabled (default)**: Local paths like `./my_project/utils` get synchronized and added to remote `sys.path`
- **Disabled**: Only the container's native `sys.path` is used, along with the deployed code bundle

Most users should leave path synchronization enabled unless they have specific requirements for container path isolation or are using pre-configured container environments.

## SDK deployment options

The core deployment functionality is available programmatically through the `flyte.deploy()` function, though some CLI-specific options are not applicable:

```python
import flyte

env = flyte.TaskEnvironment(name="my_env")

@env.task
async def process_data(data: str) -> str:
    return f"Processed: {data}"

if __name__ == "__main__":
    flyte.init_from_config()

    # Comprehensive deployment configuration
    deployment = flyte.deploy(
        env,                          # Environment to deploy
        dryrun=False,                 # Set to True for dry run
        version="v1.2.0",             # Explicit version tag
        copy_style="loaded_modules"   # Code bundling strategy
    )
    print(f"Deployment successful: {deployment[0].summary_repr()}")
```


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-deployment/packaging ===

# Code packaging for remote execution

When you run Flyte tasks remotely, your code needs to be available in the execution environment. Flyte SDK provides two main approaches for packaging your code:

1. **Code bundling** - Bundle code dynamically at runtime
2. **Container-based deployment** - Embed code directly in container images

## Quick comparison

| Aspect | Code bundling | Container-based |
|--------|---------------|-----------------|
| **Speed** | Fast (no image rebuild) | Slower (requires image build) |
| **Best for** | Rapid development, iteration | Production, immutable deployments |
| **Code changes** | Immediate effect | Requires image rebuild |
| **Setup** | Automatic by default | Manual configuration needed |
| **Reproducibility** | Excellent (hash-based versioning) | Excellent (immutable images) |
| **Rollback** | Requires version control | Tag-based, straightforward |

---

## Code bundling

**Default approach** - Automatically bundles and uploads your code to remote storage at runtime.

### How it works

When you run `flyte run` or call `flyte.run()`, Flyte automatically:

1. **Scans loaded modules** from your codebase
2. **Creates a tarball** (gzipped, without timestamps for consistent hashing)
3. **Uploads to blob storage** (S3, GCS, Azure Blob)
4. **Deduplicates** based on content hashes
5. **Downloads in containers** at runtime

This process happens transparently - every container downloads and extracts the code bundle before execution.

> [!NOTE]
> Code bundling is optimized for speed:
> - Bundles are created without timestamps for consistent hashing
> - Identical code produces identical hashes, enabling deduplication
> - Only modified code triggers new uploads
> - Containers cache downloaded bundles
>
> **Reproducibility:** Flyte automatically versions code bundles based on content hash. The same code always produces the same hash, guaranteeing reproducibility without manual versioning. However, version control is still recommended for rollback capabilities.

### Automatic code bundling

**Default behavior** - Bundles all loaded modules automatically.

#### What gets bundled

Flyte includes modules that are:
- ✅ **Loaded when environment is parsed** (imported at module level)
- ✅ **Part of your codebase** (not system packages)
- ✅ **Within your project directory**
- ❌ **NOT lazily loaded** (imported inside functions)
- ❌ **NOT system-installed packages** (e.g., from site-packages)

#### Example: Basic automatic bundling

```python
# app.py
import flyte
from my_module import helper  # ✅ Bundled automatically

env = flyte.TaskEnvironment(
    name="default",
    image=flyte.Image.from_debian_base().with_pip_packages("pandas", "numpy")
)

@env.task
def process_data(x: int) -> int:
    # This import won't be bundled (lazy load)
    from another_module import util  # ❌ Not bundled automatically
    return helper.transform(x)

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(process_data, x=42)
    print(run.url)
```

When you run this:
```bash
flyte run app.py process_data --x 42
```

Flyte automatically:
1. Bundles `app.py` and `my_module.py`
2. Preserves the directory structure
3. Uploads to blob storage
4. Makes it available in the remote container

#### Project structure example

```
my_project/
├── app.py              # Main entry point
├── tasks/
│   ├── __init__.py
│   ├── data_tasks.py   # Flyte tasks
│   └── ml_tasks.py
└── utils/
    ├── __init__.py
    ├── preprocessing.py # Business logic
    └── models.py
```

```python
# app.py
import flyte
from tasks.data_tasks import load_data    # ✅ Bundled
from tasks.ml_tasks import train_model    # ✅ Bundled
# utils modules imported in tasks are also bundled

@flyte.task
def pipeline(dataset: str) -> float:
    data = load_data(dataset)
    accuracy = train_model(data)
    return accuracy

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(pipeline, dataset="train.csv")
```

**All modules are bundled with their directory structure preserved.**

### Manual code bundling

Control exactly what gets bundled by configuring the copy style.

#### Copy styles

Three options available:

1. **`"auto"`** (default) - Bundle loaded modules only
2. **`"all"`** - Bundle everything in the working directory
3. **`"none"`** - Skip bundling entirely (requires code in container)

#### Using `copy_style="all"`

Bundle all files under your project directory:

```python
import flyte

flyte.init_from_config()

# Bundle everything in current directory
run = flyte.with_runcontext(copy_style="all").run(
    my_task,
    input_data="sample.csv"
)
```

Or via CLI:
```bash
flyte run --copy-style=all app.py my_task --input-data sample.csv
```

**Use when:**
- You have data files or configuration that tasks need
- You use dynamic imports or lazy loading
- You want to ensure all project files are available

#### Using `copy_style="none"`

Skip code bundling (see **Run and deploy tasks > Code packaging for remote execution > Container-based deployment**):

```python
run = flyte.with_runcontext(copy_style="none").run(my_task, x=10)
```

### Controlling the root directory

The `root_dir` parameter controls which directory serves as the bundling root.

#### Why root directory matters

1. **Determines what gets bundled** - All code paths are relative to root_dir
2. **Preserves import structure** - Python imports must match the bundle structure
3. **Affects path resolution** - Files and modules are located relative to root_dir

#### Setting root directory

##### Via CLI

```bash
flyte run --root-dir /path/to/project app.py my_task
```

##### Programmatically

```python
import pathlib
import flyte

flyte.init_from_config(
    root_dir=pathlib.Path(__file__).parent
)
```

#### Root directory use cases

##### Use case 1: Multi-module project

```
project/
├── src/
│   ├── workflows/
│   │   └── pipeline.py
│   └── utils/
│       └── helpers.py
└── config.yaml
```

```python
# src/workflows/pipeline.py
import pathlib
import flyte
from utils.helpers import process  # Relative import from project root

# Set root to project root (not src/)
flyte.init_from_config(
    root_dir=pathlib.Path(__file__).parent.parent.parent
)

@flyte.task
def my_task():
    return process()
```

**Root set to `project/` so imports like `from utils.helpers` work correctly.**

##### Use case 2: Shared utilities

```
workspace/
├── shared/
│   └── common.py
└── project/
    └── app.py
```

```python
# project/app.py
import flyte
import pathlib
from shared.common import shared_function  # Import from parent directory

# Set root to workspace/ to include shared/
flyte.init_from_config(
    root_dir=pathlib.Path(__file__).parent.parent
)
```

##### Use case 3: Monorepo

```
monorepo/
├── libs/
│   ├── data/
│   └── models/
└── services/
    └── ml_service/
        └── workflows.py
```

```python
# services/ml_service/workflows.py
import flyte
import pathlib
from libs.data import loader  # Import from monorepo root
from libs.models import predictor

# Set root to monorepo/ to include libs/
flyte.init_from_config(
    root_dir=pathlib.Path(__file__).parent.parent.parent
)
```

#### Root directory best practices

1. **Set root_dir at project initialization** before importing any task modules
2. **Use absolute paths** with `pathlib.Path(__file__).parent` navigation
3. **Match your import structure** - if imports are relative to project root, set root_dir to project root
4. **Keep consistent** - use the same root_dir for both `flyte run` and `flyte.init()`

### Code bundling examples

#### Example: Standard Python package

```
my_package/
├── pyproject.toml
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── main.py
│       ├── data/
│       │   ├── loader.py
│       │   └── processor.py
│       └── models/
│           └── analyzer.py
```

```python
# src/my_package/main.py
import flyte
import pathlib
from my_package.data.loader import fetch_data
from my_package.data.processor import clean_data
from my_package.models.analyzer import analyze

env = flyte.TaskEnvironment(
    name="pipeline",
    image=flyte.Image.from_debian_base().with_uv_project(
        pyproject_file=pathlib.Path(__file__).parent.parent.parent / "pyproject.toml"
    )
)

@env.task
async def fetch_task(url: str) -> dict:
    return await fetch_data(url)

@env.task
def process_task(raw_data: dict) -> list[dict]:
    return clean_data(raw_data)

@env.task
def analyze_task(data: list[dict]) -> str:
    return analyze(data)

if __name__ == "__main__":
    import flyte.git

    # Set root to project root for proper imports
    flyte.init_from_config(
        flyte.git.config_from_root(),
        root_dir=pathlib.Path(__file__).parent.parent.parent
    )

    # All modules bundled automatically
    run = flyte.run(analyze_task, data=[{"value": 1}, {"value": 2}])
    print(f"Run URL: {run.url}")
```

**Run with:**
```bash
cd my_package
flyte run src/my_package/main.py analyze_task --data '[{"value": 1}]'
```

#### Example: Dynamic environment based on domain

```python
# environment_picker.py
import flyte

def create_env():
    """Create different environments based on domain."""
    if flyte.current_domain() == "development":
        return flyte.TaskEnvironment(
            name="dev",
            image=flyte.Image.from_debian_base(),
            env_vars={"ENV": "dev", "DEBUG": "true"}
        )
    elif flyte.current_domain() == "staging":
        return flyte.TaskEnvironment(
            name="staging",
            image=flyte.Image.from_debian_base(),
            env_vars={"ENV": "staging", "DEBUG": "false"}
        )
    else:  # production
        return flyte.TaskEnvironment(
            name="prod",
            image=flyte.Image.from_debian_base(),
            env_vars={"ENV": "production", "DEBUG": "false"},
            resources=flyte.Resources(cpu="2", memory="4Gi")
        )

env = create_env()

@env.task
async def process(n: int) -> int:
    import os
    print(f"Running in {os.getenv('ENV')} environment")
    return n * 2

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(process, n=5)
    print(run.url)
```

**Why this works:**
- `flyte.current_domain()` is set correctly when Flyte re-instantiates modules remotely
- Environment configuration is deterministic and reproducible
- Code automatically bundled with domain-specific settings

> [!NOTE]
> `flyte.current_domain()` only works after `flyte.init()` is called:
> - ✅ Works with `flyte run` and `flyte deploy` (auto-initialize)
> - ✅ Works in `if __name__ == "__main__"` after explicit `flyte.init()`
> - ❌ Does NOT work at module level without initialization

### When to use code bundling

✅ **Use code bundling when:**
- Rapid development and iteration
- Frequently changing code
- Multiple developers testing changes
- Jupyter notebook workflows
- Quick prototyping and experimentation

❌ **Consider container-based instead when:**
- Need easy rollback to previous versions (container tags are simpler than finding git commits)
- Working with air-gapped environments (no blob storage access)
- Code changes require coordinated dependency updates

---

## Container-based deployment

**Advanced approach** - Embed code directly in container images for immutable deployments.

### How it works

Instead of bundling code at runtime:

1. **Build container image** with code copied inside
2. **Disable code bundling** with `copy_style="none"`
3. **Container has everything** needed at runtime

**Trade-off:** Every code change requires a new image build (slower), but provides complete reproducibility.

### Configuration

Three key steps:

#### 1. Set `copy_style="none"`

Disable runtime code bundling:

```python
flyte.with_runcontext(copy_style="none").run(my_task, n=10)
```

Or via CLI:
```bash
flyte run --copy-style=none app.py my_task --n 10
```

#### 2. Copy Code into Image

Use `Image.with_source_file()` or `Image.with_source_folder()`:

```python
import pathlib
import flyte

env = flyte.TaskEnvironment(
    name="embedded",
    image=flyte.Image.from_debian_base().with_source_folder(
        src=pathlib.Path(__file__).parent,
        copy_contents_only=True
    )
)
```

#### 3. Set Correct `root_dir`

Match your image copy configuration:

```python
flyte.init_from_config(
    root_dir=pathlib.Path(__file__).parent
)
```

### Image source copying methods

#### `with_source_file()` - Copy individual files

Copy a single file into the container:

```python
image = flyte.Image.from_debian_base().with_source_file(
    src=pathlib.Path(__file__),
    dst="/app/main.py"
)
```

**Use for:**
- Single-file workflows
- Copying configuration files
- Adding scripts to existing images

#### `with_source_folder()` - Copy directories

Copy entire directories into the container:

```python
image = flyte.Image.from_debian_base().with_source_folder(
    src=pathlib.Path(__file__).parent,
    dst="/app",
    copy_contents_only=False  # Copy folder itself
)
```

**Parameters:**
- `src`: Source directory path
- `dst`: Destination path in container (optional, defaults to workdir)
- `copy_contents_only`: If `True`, copies folder contents; if `False`, copies folder itself

##### `copy_contents_only=True` (Recommended)

Copies only the contents of the source folder:

```python
# Project structure:
# my_project/
#   ├── app.py
#   └── utils.py

image = flyte.Image.from_debian_base().with_source_folder(
    src=pathlib.Path(__file__).parent,
    copy_contents_only=True
)

# Container will have:
# /app/app.py
# /app/utils.py

# Set root_dir to match:
flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
```

##### `copy_contents_only=False`

Copies the folder itself with its name:

```python
# Project structure:
# workspace/
#   └── my_project/
#       ├── app.py
#       └── utils.py

image = flyte.Image.from_debian_base().with_source_folder(
    src=pathlib.Path(__file__).parent,  # Points to my_project/
    copy_contents_only=False
)

# Container will have:
# /app/my_project/app.py
# /app/my_project/utils.py

# Set root_dir to parent to match:
flyte.init_from_config(root_dir=pathlib.Path(__file__).parent.parent)
```

### Complete container-based example

```python
# full_build.py
import pathlib
import flyte
from dep import helper  # Local module

# Configure environment with source copying
env = flyte.TaskEnvironment(
    name="full_build",
    image=flyte.Image.from_debian_base()
        .with_pip_packages("numpy", "pandas")
        .with_source_folder(
            src=pathlib.Path(__file__).parent,
            copy_contents_only=True
        )
)

@env.task
def square(x: int) -> int:
    return x ** helper.get_exponent()

@env.task
def main(n: int) -> list[int]:
    return list(flyte.map(square, range(n)))

if __name__ == "__main__":
    import flyte.git

    # Initialize with matching root_dir
    flyte.init_from_config(
        flyte.git.config_from_root(),
        root_dir=pathlib.Path(__file__).parent
    )

    # Run with copy_style="none" and explicit version
    run = flyte.with_runcontext(
        copy_style="none",
        version="v1.0.0"  # Explicit version for image tagging
    ).run(main, n=10)

    print(f"Run URL: {run.url}")
    run.wait()
```

**Project structure:**
```
project/
├── full_build.py
├── dep.py          # Local dependency
└── .flyte/
    └── config.yaml
```

**Run with:**
```bash
python full_build.py
```

This will:
1. Build a container image with `full_build.py` and `dep.py` embedded
2. Tag it as `v1.0.0`
3. Push to registry
4. Execute remotely without code bundling

### Using externally built images

When containers are built outside of Flyte (e.g., in CI/CD), use `Image.from_ref_name()`:

#### Step 1: Build your image externally

```dockerfile
# Dockerfile
FROM python:3.11-slim

WORKDIR /app

# Copy your code
COPY src/ /app/

# Install dependencies
RUN pip install flyte pandas numpy

# Ensure flyte executable is available
RUN flyte --help
```

Build and push the image:

```bash
docker build -t myregistry.com/my-app:v1.2.3 .
docker push myregistry.com/my-app:v1.2.3
```

#### Step 2: Reference image by name

```python
# app.py
import flyte

env = flyte.TaskEnvironment(
    name="external",
    image=flyte.Image.from_ref_name("my-app-image")  # Reference name
)

@env.task
def process(x: int) -> int:
    return x * 2

if __name__ == "__main__":
    flyte.init_from_config()

    # Pass actual image URI at deploy/run time
    run = flyte.with_runcontext(
        copy_style="none",
        images={"my-app-image": "myregistry.com/my-app:v1.2.3"}
    ).run(process, x=10)
```

Or via CLI:
```bash
flyte run \
  --copy-style=none \
  --image my-app-image=myregistry.com/my-app:v1.2.3 \
  app.py process --x 10
```

**For deployment:**
```bash
flyte deploy \
  --image my-app-image=myregistry.com/my-app:v1.2.3 \
  app.py
```

#### Why use reference names?

1. **Decouples code from image URIs** - Change images without modifying code
2. **Supports multiple environments** - Different images for dev/staging/prod
3. **Integrates with CI/CD** - Build images in pipelines, reference in code
4. **Enables image reuse** - Multiple tasks can reference the same image

#### Example: Multi-environment deployment

```python
import flyte
import os

# Code references image by name
env = flyte.TaskEnvironment(
    name="api",
    image=flyte.Image.from_ref_name("api-service")
)

@env.task
def api_call(endpoint: str) -> dict:
    # Implementation
    return {"status": "success"}

if __name__ == "__main__":
    flyte.init_from_config()

    # Determine image based on environment
    environment = os.getenv("ENV", "dev")
    image_uri = {
        "dev": "myregistry.com/api-service:dev",
        "staging": "myregistry.com/api-service:staging",
        "prod": "myregistry.com/api-service:v1.2.3"
    }[environment]

    run = flyte.with_runcontext(
        copy_style="none",
        images={"api-service": image_uri}
    ).run(api_call, endpoint="/health")
```

### Container-based best practices

1. **Always set explicit versions** when using `copy_style="none"`:
   ```python
   flyte.with_runcontext(copy_style="none", version="v1.0.0")
   ```

2. **Match `root_dir` to `copy_contents_only`**:
   - `copy_contents_only=True` → `root_dir=Path(__file__).parent`
   - `copy_contents_only=False` → `root_dir=Path(__file__).parent.parent`

3. **Ensure `flyte` executable is in container** - Add to PATH or install flyte package

4. **Use `.dockerignore`** to exclude unnecessary files:
   ```
   # .dockerignore
   __pycache__/
   *.pyc
   .git/
   .venv/
   *.egg-info/
   ```

5. **Test containers locally** before deploying:
   ```bash
   docker run -it myimage:latest /bin/bash
   python -c "import mymodule"  # Verify imports work
   ```

### When to use container-based deployment

✅ **Use container-based when:**
- Deploying to production
- Need immutable, reproducible environments
- Working with complex system dependencies
- Deploying to air-gapped or restricted environments
- CI/CD pipelines with automated builds
- Code changes are infrequent

❌ **Don't use container-based when:**
- Rapid development and frequent code changes
- Quick prototyping
- Interactive development (Jupyter notebooks)
- Learning and experimentation

---

## Choosing the right approach

### Decision tree

```
Are you iterating quickly on code?
├─ Yes → Use Code Bundling (Default)
│         (Development, prototyping, notebooks)
│         Both approaches are fully reproducible via hash/tag
└─ No  → Do you need easy version rollback?
          ├─ Yes → Use Container-based
          │         (Production, CI/CD, straightforward tag-based rollback)
          └─ No  → Either works
                    (Code bundling is simpler, container-based for air-gapped)
```

### Hybrid approach

You can use different approaches for different tasks:

```python
import flyte
import pathlib

# Fast iteration for development tasks
dev_env = flyte.TaskEnvironment(
    name="dev",
    image=flyte.Image.from_debian_base().with_pip_packages("pandas")
    # Code bundling (default)
)

# Immutable containers for production tasks
prod_env = flyte.TaskEnvironment(
    name="prod",
    image=flyte.Image.from_debian_base()
        .with_pip_packages("pandas")
        .with_source_folder(pathlib.Path(__file__).parent, copy_contents_only=True)
    # Requires copy_style="none"
)

@dev_env.task
def experimental_task(x: int) -> int:
    # Rapid development with code bundling
    return x * 2

@prod_env.task
def stable_task(x: int) -> int:
    # Production with embedded code
    return x ** 2

if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)

    # Use code bundling for dev task
    dev_run = flyte.run(experimental_task, x=5)

    # Use container-based for prod task
    prod_run = flyte.with_runcontext(
        copy_style="none",
        version="v1.0.0"
    ).run(stable_task, x=5)
```

---

## Troubleshooting

### Import errors

**Problem:** `ModuleNotFoundError` when task executes remotely

**Solutions:**

1. **Check loaded modules** - Ensure modules are imported at module level:
   ```python
   # ✅ Good - bundled automatically
   from mymodule import helper

   @flyte.task
   def my_task():
       return helper.process()
   ```

   ```python
   # ❌ Bad - not bundled (lazy load)
   @flyte.task
   def my_task():
       from mymodule import helper
       return helper.process()
   ```

2. **Verify `root_dir`** matches your import structure:
   ```python
   # If imports are: from mypackage.utils import foo
   # Then root_dir should be parent of mypackage/
   flyte.init_from_config(root_dir=pathlib.Path(__file__).parent.parent)
   ```

3. **Use `copy_style="all"`** to bundle everything:
   ```bash
   flyte run --copy-style=all app.py my_task
   ```

### Code changes not reflected

**Problem:** Remote execution uses old code despite local changes

> [!NOTE]
> This is rare with code bundling - Flyte automatically versions based on content hash, so code changes should be detected automatically. This issue typically occurs with caching problems or when using `copy_style="none"`.

**Solutions:**

1. **Use explicit version bump** (mainly for container-based deployments):
   ```python
   run = flyte.with_runcontext(version="v2").run(my_task)
   ```

2. **Check if `copy_style="none"`** is set - this requires image rebuild:
   ```python
   # If using copy_style="none", rebuild image
   run = flyte.with_runcontext(
       copy_style="none",
       version="v2"  # Bump version to force rebuild
   ).run(my_task)
   ```

### Files missing in container

**Problem:** Task can't find data files or configs

**Solutions:**

1. **Use `copy_style="all"`** to bundle all files:
   ```bash
   flyte run --copy-style=all app.py my_task
   ```

2. **Copy files explicitly in image**:
   ```python
   image = flyte.Image.from_debian_base().with_source_file(
       src=pathlib.Path("config.yaml"),
       dst="/app/config.yaml"
   )
   ```

3. **Store data in remote storage** instead of bundling:
   ```python
   @flyte.task
   def my_task():
       # Read from S3/GCS instead of local files
       import flyte.io
       data = flyte.io.File("s3://bucket/data.csv").open().read()
   ```

### Container build failures

**Problem:** Image build fails with `copy_style="none"`

**Solutions:**

1. **Check `root_dir` matches `copy_contents_only`**:
   ```python
   # copy_contents_only=True
   image = Image.from_debian_base().with_source_folder(
       src=Path(__file__).parent,
       copy_contents_only=True
   )
   flyte.init(root_dir=Path(__file__).parent)  # Match!
   ```

2. **Ensure `flyte` executable available**:
   ```python
   image = Image.from_debian_base()  # Has flyte pre-installed
   ```

3. **Check file permissions** in source directory:
   ```bash
   chmod -R +r project/
   ```

### Version conflicts

**Problem:** Multiple versions of same image causing confusion

**Solutions:**

1. **Use explicit versions**:
   ```python
   run = flyte.with_runcontext(
       copy_style="none",
       version="v1.2.3"  # Explicit, not auto-generated
   ).run(my_task)
   ```

2. **Clean old images**:
   ```bash
   docker image prune -a
   ```

3. **Use semantic versioning** for clarity:
   ```python
   version = "v1.0.0"  # Major.Minor.Patch
   ```


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-deployment/invoke-webhook ===

# Running Tasks via Webhooks

On Union, you can deploy apps (see [Apps documentation](../build-apps/_index)) that can run any deployed Flyte tasks. These apps can be REST API services, like FastAPI, that accept HTTP requests and run tasks on behalf of the caller.

A key feature of this approach is **passthrough authentication** - the app can carry forward the identity of the caller and use their credentials to run the task. This ensures proper authorization and audit trails, as tasks are executed with the permissions of the actual user making the request.

## How passthrough authentication works

When you deploy a webhook service on Union:

1. The caller sends an HTTP request with their authentication token (typically in the `Authorization` header)
2. Your webhook app extracts the authentication headers from the request
3. The app forwards these headers to the Flyte control plane when running the task
4. The task executes with the caller's identity and permissions

This is different from using a service API key, where all tasks would run with the same service account permissions regardless of who made the request.

## Setting up passthrough authentication

### Initialize with `flyte.init_passthrough()`

To enable passthrough authentication, initialize your app using `flyte.init_passthrough()`:

```python
import flyte

# Initialize Flyte with passthrough authentication
await flyte.init_passthrough.aio(
    endpoint="dns:///your-endpoint.hosted.unionai.cloud",
    project="my-project",      # Optional: default project
    domain="development",       # Optional: default domain
)
```

The `init_passthrough()` function configures the Flyte SDK to accept authentication metadata from the request context rather than using a static token or interactive authentication flow.

**Parameters:**

- `endpoint`: **Required**. The Flyte control plane endpoint URL
- `project`: Optional. Default project to use if not specified per request
- `domain`: Optional. Default domain to use if not specified per request
- `org`: Optional. Organization name
- `insecure`: Optional. Whether to use an insecure connection (default: `False`)

> [!IMPORTANT]
> The `endpoint` parameter is required when using passthrough authentication. Unlike other authentication modes, passthrough cannot infer the endpoint from environment variables or config files since it needs explicit initialization.

### Passing authentication metadata

Once initialized, you need to provide the caller's authentication headers when making requests to the Flyte control plane. There are two approaches:

#### Option 1: Using FastAPI middleware (recommended if using fastapi)

For FastAPI applications, Flyte provides a convenient middleware that automatically extracts authentication headers from incoming requests and sets them in the Flyte context:

```python
from fastapi import FastAPI
from flyte.app.extras import FastAPIPassthroughAuthMiddleware

app = FastAPI()

# Add the middleware - automatically handles auth for all endpoints
app.add_middleware(
    FastAPIPassthroughAuthMiddleware,
    excluded_paths={"/health"}  # Optional: skip auth for specific paths
)

@app.post("/run-task")
async def run_task():
    # No need to manually extract headers!
    # The middleware automatically sets auth context
    task = remote.Task.get(project="my-project", domain="development", name="my_task")
    run = await flyte.run.aio(task, x=42)
    return {"run_url": run.url}
```

**Middleware features:**

- **Automatic header extraction**: Extracts `Authorization` and `Cookie` headers by default
- **Path exclusions**: Skip auth for specific endpoints like `/health` or `/metrics`
- **Custom extractors**: Add custom header extraction logic
- **Thread-safe**: Properly isolates authentication per request using context variables

**Middleware parameters:**

- `excluded_paths`: Set of URL paths that bypass authentication extraction
- `header_extractors`: Custom list of header extractor functions (optional)

**Custom header extractors:**

```python
from flyte.app.extras import FastAPIPassthroughAuthMiddleware

app.add_middleware(
    FastAPIPassthroughAuthMiddleware,
    header_extractors=[
        FastAPIPassthroughAuthMiddleware.extract_authorization_header,
        FastAPIPassthroughAuthMiddleware.extract_custom_header("x-api-key"),
    ],
    excluded_paths={"/health", "/metrics"},
)
```

#### Option 2: Using the `auth_metadata()` context manager (any script, web serving framework)

The `flyte.remote.auth_metadata()` context manager allows you to explicitly set authentication headers for a block of code:

```python
import flyte.remote as remote

@app.post("/run-task")
async def run_task(request: Request):
    # Extract authentication from the request
    auth_header = request.headers.get("authorization")

    # Use auth_metadata to forward the caller's credentials
    with remote.auth_metadata(("authorization", auth_header)):
        # Get and run the task with the caller's identity
        task = remote.Task.get(project="my-project", domain="development", name="my_task")
        run = await flyte.run.aio(task, x=42)
        return {"run_url": run.url}
```

The `auth_metadata()` context manager accepts one or more tuples of `(header_name, header_value)`:

```python
with remote.auth_metadata(
    ("authorization", auth_header),
    ("cookie", cookie_header),
):
    # All Flyte API calls within this block use these headers
    ...
```

## Complete example

Here's a complete FastAPI webhook service that runs Flyte tasks with passthrough authentication:

```python
import os
from contextlib import asynccontextmanager

from fastapi import FastAPI, HTTPException
from starlette import status

import flyte
import flyte.errors
import flyte.remote as remote
from flyte.app.extras import FastAPIAppEnvironment, FastAPIPassthroughAuthMiddleware

@asynccontextmanager
async def lifespan(app: FastAPI):
    """Initialize Flyte with passthrough auth on startup."""
    endpoint = os.getenv("FLYTE_ENDPOINT")
    if not endpoint:
        raise RuntimeError("FLYTE_ENDPOINT environment variable not set")

    await flyte.init_passthrough.aio(
        endpoint=endpoint,
        project=os.getenv("FLYTE_INTERNAL_EXECUTION_PROJECT"),
        domain=os.getenv("FLYTE_INTERNAL_EXECUTION_DOMAIN"),
    )
    yield

app = FastAPI(
    title="Flyte Webhook Runner",
    description="A webhook service that runs Flyte tasks",
    lifespan=lifespan,
)

# Add passthrough auth middleware
app.add_middleware(FastAPIPassthroughAuthMiddleware, excluded_paths={"/health"})

@app.get("/health")
async def health_check():
    """Health check endpoint (no auth required)."""
    return {"status": "healthy"}

@app.get("/me")
async def get_current_user():
    """Get information about the authenticated user."""
    user = await remote.User.get.aio()
    return {
        "subject": user.subject(),
        "name": user.name(),
    }

@app.post("/run-task/{project}/{domain}/{name}")
async def run_task(
    project: str,
    domain: str,
    name: str,
    inputs: dict,
    version: str | None = None,
):
    """
    Run a Flyte task with the caller's credentials.

    Args:
        project: Flyte project name
        domain: Flyte domain (e.g., development, staging, production)
        name: Task name
        inputs: Dictionary of input parameters for the task
        version: Task version (optional, defaults to "latest")

    Returns:
        Dictionary containing the run information
    """
    try:
        # Get the task
        task = remote.Task.get(
            project=project,
            domain=domain,
            name=name,
            version=version,
            auto_version="latest" if version is None else None,
        )

        # Run the task with the caller's identity
        run = await flyte.run.aio(task, **inputs)

        return {"url": run.url, "name": run.name}

    except flyte.errors.RemoteTaskNotFoundError:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"Task {name} with {version} in {project} and {domain} not found",
        )
    except flyte.errors.RemoteTaskUsageError as e:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail=str(e),
        )
    except Exception as e:
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=str(e),
        )

# Configure the app deployment
image = flyte.Image.from_debian_base().with_pip_packages("fastapi", "uvicorn")

app_env = FastAPIAppEnvironment(
    name="webhook-runner",
    app=app,
    description="A webhook service that runs Flyte tasks with passthrough auth",
    image=image,
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=True,  # Platform handles auth at gateway
    env_vars={
        "FLYTE_ENDPOINT": "your-endpoint.hosted.unionai.cloud",
    },
)
```

For a complete working example, see [`examples/apps/run_webhook.py`](https://github.com/unionai/flyte-sdk/blob/main/examples/apps/run_webhook.py) in the Flyte SDK repository.

## Calling the webhook

Once deployed, you can call your webhook using standard HTTP tools:

Get your API key:

```bash
flyte get api-key my-webhook-key
```

Call the webhook to run a task:

```bash
curl -X POST \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"x": 42, "y": "hello"}' \
  https://your-app.apps.unionai.cloud/run-task/my-project/development/my_task
```

The task will execute with the permissions associated with the API key used in the request.

## Best practices

1. **Always set an endpoint**: The `endpoint` parameter is required for `init_passthrough()`

2. **Use middleware for FastAPI**: The `FastAPIPassthroughAuthMiddleware` eliminates boilerplate and ensures consistent auth handling

3. **Exclude public endpoints**: Use `excluded_paths` to skip auth for health checks and public endpoints

4. **Set default project/domain**: If most requests target the same project/domain, set them during initialization to simplify your endpoint handlers

5. **Handle errors gracefully**: Catch `flyte.errors.RemoteTaskNotFoundError` or `flyte.errors.RemoteTaskUsageError` and other exceptions to return appropriate HTTP status codes

6. **Validate inputs**: Always validate task inputs before passing them to `flyte.run()`

7. **Use the caller's identity**: Passthrough auth ensures proper authorization and audit trails - avoid using static service credentials when possible

## Troubleshooting

### "FLYTE_ENDPOINT environment variable not set"

Ensure you set the `FLYTE_ENDPOINT` environment variable in your app configuration, or pass it explicitly to `init_passthrough()`.

### "Authentication credentials required"

The middleware returns this error when no authentication headers are found. Ensure:
- The client includes an `Authorization` header with a valid token
- The endpoint is not in the `excluded_paths` set
- Header extractors are configured correctly

### "Task not found"

Verify:
- The task exists in the specified project/domain
- The task name is correct (use the fully qualified name: `package.module.task_name`)
- The caller has permission to view the task

### Tasks run with wrong permissions

If tasks aren't respecting the caller's permissions:
- Verify `init_passthrough()` is called with `auth_type="Passthrough"`
- Ensure auth headers are being extracted and forwarded correctly
- Check that the middleware is added before route handlers


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-deployment/deployment-patterns ===

# Deployment patterns

Once you understand the basics of task deployment, you can leverage various deployment patterns to handle different project structures, dependency management approaches, and deployment requirements. This section covers the most common patterns with practical examples.

## Overview of deployment patterns

Flyte supports multiple deployment patterns to accommodate different project structures and requirements:

1. ****Run and deploy tasks > Deployment patterns > Simple file deployment**** - Single file with tasks and environments
2. ****Run and deploy tasks > Deployment patterns > Custom Dockerfile deployment**** - Full control over container environment
3. ****Run and deploy tasks > Deployment patterns > PyProject package deployment**** - Structured Python packages with dependencies and async tasks
4. ****Run and deploy tasks > Deployment patterns > Package structure deployment**** - Organized packages with shared environments
5. ****Run and deploy tasks > Deployment patterns > Full build deployment**** - Complete code embedding in containers
6. ****Run and deploy tasks > Deployment patterns > Python path deployment**** - Multi-directory project structures
7. ****Run and deploy tasks > Deployment patterns > Dynamic environment deployment**** - Environment selection based on domain context

Each pattern serves specific use cases and can be combined as needed for complex projects.

## Simple file deployment

The simplest deployment pattern involves defining both your tasks and task environment in a single Python file. This pattern works well for:

- Prototyping and experimentation
- Simple tasks with minimal dependencies
- Educational examples and tutorials

### Example structure

```python
import flyte

env = flyte.TaskEnvironment(name="simple_env")

@env.task
async def my_task(name: str) -> str:
    return f"Hello, {name}!"

if __name__ == "__main__":
    flyte.init_from_config()
    flyte.deploy(env)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/deployment-patterns/simple_file.py*

### Deployment commands

Deploy the environment:

```bash
flyte deploy my_example.py env
```

Run the task ephemerally:

```bash
flyte run my_example.py my_task --name "World"
```

### When to use

- Quick prototypes and experiments
- Single-purpose scripts
- Learning Flyte basics
- Tasks with no external dependencies

## Custom Dockerfile deployment

When you need full control over the container environment, you can specify a custom Dockerfile. This pattern is ideal for:

- Complex system dependencies
- Specific OS or runtime requirements
- Custom base images
- Multi-stage builds

### Example structure

```dockerfile
# syntax=docker/dockerfile:1.5
FROM ghcr.io/astral-sh/uv:0.8 as uv
FROM python:3.12-slim-bookworm

USER root

# Copy in uv so that later commands don't have to mount it in
COPY --from=uv /uv /usr/bin/uv

# Configure default envs
ENV UV_COMPILE_BYTECODE=1 \
    UV_LINK_MODE=copy \
    VIRTUALENV=/opt/venv \
    UV_PYTHON=/opt/venv/bin/python \
    PATH="/opt/venv/bin:$PATH"

# Create a virtualenv with the user specified python version
RUN uv venv /opt/venv --python=3.12

WORKDIR /root

# Install dependencies
COPY requirements.txt .
RUN uv pip install --pre -r /root/requirements.txt
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/deployment-patterns/dockerfile/Dockerfile*

```python
from pathlib import Path

import flyte

env = flyte.TaskEnvironment(
    name="docker_env",
    image=flyte.Image.from_dockerfile(
        # relative paths in python change based on where you call, so set it relative to this file
        Path(__file__).parent / "Dockerfile",
        registry="ghcr.io/flyteorg",
        name="docker_env_image",
    ),
)

@env.task
def main(x: int) -> int:
    return x * 2

if __name__ == "__main__":
    import flyte.git

    flyte.init_from_config(flyte.git.config_from_root())

    run = flyte.run(main, x=10)
    print(run.url)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/deployment-patterns/dockerfile/dockerfile_env.py*

### Alternative: Dockerfile in different directory

You can also reference Dockerfiles from subdirectories:

```python
from pathlib import Path

import flyte

env = flyte.TaskEnvironment(
    name="docker_env_in_dir",
    image=flyte.Image.from_dockerfile(
        # relative paths in python change based on where you call, so set it relative to this file
        Path(__file__).parent.parent / "Dockerfile.workdir",
        registry="ghcr.io/flyteorg",
        name="docker_env_image",
    ),
)

@env.task
def main(x: int) -> int:
    return x * 2

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main, x=10)
    print(run.url)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/deployment-patterns/dockerfile/src/docker_env_in_dir.py*

```dockerfile
# syntax=docker/dockerfile:1.5
FROM ghcr.io/astral-sh/uv:0.8 as uv
FROM python:3.12-slim-bookworm

USER root

# Copy in uv so that later commands don't have to mount it in
COPY --from=uv /uv /usr/bin/uv

# Configure default envs
ENV UV_COMPILE_BYTECODE=1 \
    UV_LINK_MODE=copy \
    VIRTUALENV=/opt/venv \
    UV_PYTHON=/opt/venv/bin/python \
    PATH="/opt/venv/bin:$PATH"

# Create a virtualenv with the user specified python version
RUN uv venv /opt/venv --python=3.12

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN uv pip install --pre -r /app/requirements.txt
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/deployment-patterns/dockerfile/Dockerfile.workdir*

### Key considerations

- **Path handling**: Use `Path(__file__).parent` for relative Dockerfile paths
  ```python
  # relative paths in python change based on where you call, so set it relative to this file
  Path(__file__).parent / "Dockerfile"
  ```
- **Registry configuration**: Specify a registry for image storage
- **Build context**: The directory containing the Dockerfile becomes the build context
- **Flyte installation**: Ensure Flyte is installed in the container and available on `$PATH`
  ```dockerfile
  # Install Flyte in your Dockerfile
  RUN pip install flyte
  ```
- **Dependencies**: Include all application requirements in the Dockerfile or requirements.txt

### When to use

- Need specific system packages or tools
- Custom base image requirements
- Complex installation procedures
- Multi-stage build optimization

## PyProject package deployment

For structured Python projects with proper package management, use the PyProject pattern. This approach demonstrates a **realistic Python project structure** that provides:

- Proper dependency management with `pyproject.toml` and external packages like `httpx`
- Clean separation of business logic and Flyte tasks across multiple modules
- Professional project structure with `src/` layout
- Async task execution with API calls and data processing
- Entrypoint patterns for both command-line and programmatic execution

### Example structure

```
pyproject_package/
├── pyproject.toml          # Project metadata and dependencies
├── README.md              # Documentation
└── src/
    └── pyproject_package/
        ├── __init__.py     # Package initialization
        ├── main.py         # Entrypoint script
        ├── data/
        │   ├── __init__.py
        │   ├── loader.py   # Data loading utilities (no Flyte)
        │   └── processor.py # Data processing utilities (no Flyte)
        ├── models/
        │   ├── __init__.py
        │   └── analyzer.py # Analysis utilities (no Flyte)
        └── tasks/
            ├── __init__.py
            └── tasks.py    # Flyte task definitions
```

### Business logic modules

The business logic is completely separate from Flyte and can be used independently:

#### Data Loading (`data/loader.py`)
```python
import json
from pathlib import Path
from typing import Any

import httpx

async def fetch_data_from_api(url: str) -> list[dict[str, Any]]:
    async with httpx.AsyncClient() as client:
        response = await client.get(url, timeout=10.0)
        response.raise_for_status()
        return response.json()

def load_local_data(file_path: str | Path) -> dict[str, Any]:
    path = Path(file_path)

    if not path.exists():
        raise FileNotFoundError(f"File not found: {file_path}")

    with path.open("r") as f:
        return json.load(f)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/deployment-patterns/pyproject_package/src/pyproject_package/data/loader.py*

#### Data Processing (`data/processor.py`)
```python
import asyncio
from typing import Any

from pydantic import BaseModel, Field, field_validator

class DataItem(BaseModel):
    id: int = Field(gt=0, description="Item ID must be positive")
    value: float = Field(description="Item value")
    category: str = Field(min_length=1, description="Item category")

    @field_validator("category")
    @classmethod
    def category_must_be_lowercase(cls, v: str) -> str:
        return v.lower()

def clean_data(raw_data: dict[str, Any]) -> dict[str, Any]:
    # Remove None values
    cleaned = {k: v for k, v in raw_data.items() if v is not None}

    # Validate items if present
    if "items" in cleaned:
        validated_items = []
        for item in cleaned["items"]:
            try:
                validated = DataItem(**item)
                validated_items.append(validated.model_dump())
            except Exception as e:
                print(f"Skipping invalid item {item}: {e}")
                continue
        cleaned["items"] = validated_items

    return cleaned

def transform_data(data: dict[str, Any]) -> list[dict[str, Any]]:
    items = data.get("items", [])

    # Add computed fields
    transformed = []
    for item in items:
        transformed_item = {
            **item,
            "value_squared": item["value"] ** 2,
            "category_upper": item["category"].upper(),
        }
        transformed.append(transformed_item)

    return transformed

async def aggregate_data(items: list[dict[str, Any]]) -> dict[str, Any]:
    # Simulate async processing
    await asyncio.sleep(0.1)

    aggregated: dict[str, dict[str, Any]] = {}

    for item in items:
        category = item["category"]

        if category not in aggregated:
            aggregated[category] = {
                "count": 0,
                "total_value": 0.0,
                "values": [],
            }

        aggregated[category]["count"] += 1
        aggregated[category]["total_value"] += item["value"]
        aggregated[category]["values"].append(item["value"])

    # Calculate averages
    for category, v in aggregated.items():
        total = v["total_value"]
        count = v["count"]
        v["average_value"] = total / count if count > 0 else 0.0

    return {"categories": aggregated, "total_items": len(items)}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/deployment-patterns/pyproject_package/src/pyproject_package/data/processor.py*

#### Analysis (`models/analyzer.py`)
```python
from typing import Any

import numpy as np

def calculate_statistics(data: list[dict[str, Any]]) -> dict[str, Any]:
    if not data:
        return {
            "count": 0,
            "mean": 0.0,
            "median": 0.0,
            "std_dev": 0.0,
            "min": 0.0,
            "max": 0.0,
        }

    values = np.array([item["value"] for item in data])

    stats = {
        "count": len(values),
        "mean": float(np.mean(values)),
        "median": float(np.median(values)),
        "std_dev": float(np.std(values)),
        "min": float(np.min(values)),
        "max": float(np.max(values)),
        "percentile_25": float(np.percentile(values, 25)),
        "percentile_75": float(np.percentile(values, 75)),
    }

    return stats

def generate_report(stats: dict[str, Any]) -> str:
    report_lines = [
        "=" * 60,
        "DATA ANALYSIS REPORT",
        "=" * 60,
    ]

    # Basic statistics section
    if "basic" in stats:
        basic = stats["basic"]
        report_lines.extend(
            [
                "",
                "BASIC STATISTICS:",
                f"  Count:       {basic.get('count', 0)}",
                f"  Mean:        {basic.get('mean', 0.0):.2f}",
                f"  Median:      {basic.get('median', 0.0):.2f}",
                f"  Std Dev:     {basic.get('std_dev', 0.0):.2f}",
                f"  Min:         {basic.get('min', 0.0):.2f}",
                f"  Max:         {basic.get('max', 0.0):.2f}",
                f"  25th %ile:   {basic.get('percentile_25', 0.0):.2f}",
                f"  75th %ile:   {basic.get('percentile_75', 0.0):.2f}",
            ]
        )

    # Category aggregations section
    if "aggregated" in stats and "categories" in stats["aggregated"]:
        categories = stats["aggregated"]["categories"]
        total_items = stats["aggregated"].get("total_items", 0)

        report_lines.extend(
            [
                "",
                "CATEGORY BREAKDOWN:",
                f"  Total Items: {total_items}",
                "",
            ]
        )

        for category, cat_stats in sorted(categories.items()):
            report_lines.extend(
                [
                    f"  Category: {category.upper()}",
                    f"    Count:         {cat_stats.get('count', 0)}",
                    f"    Total Value:   {cat_stats.get('total_value', 0.0):.2f}",
                    f"    Average Value: {cat_stats.get('average_value', 0.0):.2f}",
                    "",
                ]
            )

    report_lines.append("=" * 60)

    return "\n".join(report_lines)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/deployment-patterns/pyproject_package/src/pyproject_package/models/analyzer.py*

These modules demonstrate:
- **No Flyte dependencies** - can be tested and used independently
- **Pydantic models** for data validation with custom validators
- **Async patterns** with proper context managers and error handling
- **NumPy integration** for statistical calculations
- **Professional error handling** with timeouts and validation

### Flyte orchestration layer

The Flyte tasks orchestrate the business logic with proper async execution:

```python
import pathlib
from typing import Any

import flyte
from pyproject_package.data import loader, processor
from pyproject_package.models import analyzer

UV_PROJECT_ROOT = pathlib.Path(__file__).parent.parent.parent.parent

env = flyte.TaskEnvironment(
    name="data_pipeline",
    image=flyte.Image.from_debian_base().with_uv_project(pyproject_file=UV_PROJECT_ROOT / "pyproject.toml"),
    resources=flyte.Resources(memory="512Mi", cpu="500m"),
)

@env.task
async def fetch_task(url: str) -> list[dict[str, Any]]:
    print(f"Fetching data from: {url}")
    data = await loader.fetch_data_from_api(url)
    print(f"Fetched {len(data)} top-level keys")
    return data

@env.task
async def process_task(raw_data: dict[str, Any]) -> list[dict[str, Any]]:
    print("Cleaning data...")
    cleaned = processor.clean_data(raw_data)

    print("Transforming data...")
    transformed = processor.transform_data(cleaned)

    print(f"Processed {len(transformed)} items")
    return transformed

@env.task
async def analyze_task(processed_data: list[dict[str, Any]]) -> str:
    print("Aggregating data...")
    aggregated = await processor.aggregate_data(processed_data)

    print("Calculating statistics...")
    stats = analyzer.calculate_statistics(processed_data)

    print("Generating report...")
    report = analyzer.generate_report({"basic": stats, "aggregated": aggregated})

    print("\n" + report)
    return report

@env.task
async def pipeline(api_url: str) -> str:
    # Chain tasks together
    raw_data = await fetch_task(url=api_url)
    processed_data = await process_task(raw_data=raw_data[0])
    report = await analyze_task(processed_data=processed_data)

    return report
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/deployment-patterns/pyproject_package/src/pyproject_package/tasks/tasks.py*

### Entrypoint configuration

The main entrypoint demonstrates proper initialization and execution patterns:

```python
import pathlib

import flyte
from pyproject_package.tasks.tasks import pipeline

def main():
    # Initialize Flyte connection
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent.parent)

    # Example API URL with mock data
    # In a real scenario, this would be a real API endpoint
    example_url = "https://jsonplaceholder.typicode.com/posts"

    # For demonstration, we'll use mock data instead of the actual API
    # to ensure the example works reliably
    print("Starting data pipeline...")
    print(f"Target API: {example_url}")

    # To run remotely, uncomment the following:
    run = flyte.run(pipeline, api_url=example_url)
    print(f"\nRun Name: {run.name}")
    print(f"Run URL: {run.url}")
    run.wait()

if __name__ == "__main__":
    main()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/deployment-patterns/pyproject_package/src/pyproject_package/main.py*

### Dependencies and configuration

```toml
[project]
name = "pyproject-package"
version = "0.1.0"
description = "Example Python package with Flyte tasks and modular business logic"
readme = "README.md"
authors = [
    { name = "Ketan Umare", email = "kumare3@users.noreply.github.com" }
]
requires-python = ">=3.10"
dependencies = [
    "flyte>=2.0.0b52",
    "httpx>=0.27.0",
    "numpy>=1.26.0",
    "pydantic>=2.0.0",
]

[project.scripts]
run-pipeline = "pyproject_package.main:main"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/deployment-patterns/pyproject_package/pyproject.toml*

### Key features

- **Async task chains**: Tasks can be chained together with proper async/await patterns
- **External dependencies**: Demonstrates integration with external libraries (`httpx`, `pyyaml`)
- **uv integration**: Uses `.with_uv_project()` for dependency management
- **Resource specification**: Shows how to set memory and CPU requirements
- **Proper error handling**: Includes timeout and error handling in API calls

### Key learning points

1. **Separation of concerns**: Business logic (`data/`, `models/`) separate from orchestration (`main.py`)
2. **Reusable code**: Non-Flyte modules can be tested independently and reused
3. **Async support**: Demonstrates async Flyte tasks for I/O-bound operations
4. **Dependency management**: Shows how external packages integrate with Flyte
5. **Realistic structure**: Mirrors real-world Python project organization
6. **Entrypoint script**: Shows how to create runnable entry points

### Usage patterns

**Run locally:**
```bash
python -m pyproject_package.main
```

**Deploy to Flyte:**
```bash
flyte deploy .
```

**Run remotely:**
```bash
python -m pyproject_package.main  # Uses remote execution
```

### What this example demonstrates

- Multiple files and modules in a package
- Async Flyte tasks with external API calls
- Separation of business logic from orchestration
- External dependencies (`httpx`, `numpy`, `pydantic`)
- **Data validation with Pydantic models** for robust data processing
- **Professional error handling** with try/catch for data validation
- **Timeout configuration** for external API calls (`timeout=10.0`)
- **Async context managers** for proper resource management (`async with httpx.AsyncClient()`)
- Entrypoint script pattern with `project.scripts`
- Realistic project structure with `src/` layout
- Task chaining and data flow
- How non-Flyte code integrates with Flyte tasks

### When to use

- Production-ready, maintainable projects
- Projects requiring external API integration
- Complex data processing pipelines
- Team development with proper separation of concerns
- Applications needing async execution patterns

## Package structure deployment

For organizing Flyte workflows in a package structure with shared task environments and utilities, use this pattern. It's particularly useful for:

- Multiple workflows that share common environments and utilities
- Organized code structure with clear module boundaries
- Projects where you want to reuse task environments across workflows

### Example structure

```
lib/
├── __init__.py
└── workflows/
    ├── __init__.py
    ├── workflow1.py    # First workflow
    ├── workflow2.py    # Second workflow
    ├── env.py          # Shared task environment
    └── utils.py        # Shared utilities
```

### Key concepts

- **Shared environments**: Define task environments in `env.py` and import across workflows
- **Utility modules**: Common functions and utilities shared between workflows
- **Root directory handling**: Use `--root-dir` flag for proper Python path configuration

### Running with root directory

When running workflows with a package structure, specify the root directory:

```bash
flyte run --root-dir . lib/workflows/workflow1.py process_workflow
flyte run --root-dir . lib/workflows/workflow2.py math_workflow --n 6
```

### How `--root-dir` works

The `--root-dir` flag automatically configures the Python path (`sys.path`) to ensure:

1. **Local execution**: Package imports work correctly when running locally
2. **Consistent behavior**: Same Python path configuration locally and at runtime
3. **No manual PYTHONPATH**: Eliminates need to manually export environment variables
4. **Runtime packaging**: Flyte packages and copies code correctly to execution environment
5. **Runtime consistency**: The same package structure is preserved in the runtime container

### Alternative: Using a Python project

For larger projects, create a proper Python project with `pyproject.toml`:

```toml
# pyproject.toml
[project]
name = "lib"
version = "0.1.0"

[build-system]
requires = ["setuptools>=45", "wheel"]
build-backend = "setuptools.build_meta"
```

Then install in editable mode:

```bash
pip install -e .
```

After installation, you can run workflows without `--root-dir`:

```bash
flyte run lib/workflows/workflow1.py process_workflow
```

However, for deployment and remote execution, still use `--root-dir` for consistency:

```bash
flyte run --root-dir . lib/workflows/workflow1.py process_workflow
flyte deploy --root-dir . lib/workflows/workflow1.py
```

### When to use

- Multiple related workflows in one project
- Shared task environments and utilities
- Team projects with multiple contributors
- Applications requiring organized code structure
- Projects that benefit from proper Python packaging

## Full build deployment

When you need complete reproducibility and want to embed all code directly in the container image, use the full build pattern. This disables Flyte's fast deployment system in favor of traditional container builds.

### Overview

By default, Flyte uses a fast deployment system that:
- Creates a tar archive of your files
- Skips the full image build and push process
- Provides faster iteration during development

However, sometimes you need to **completely embed your code into the container image** for:
- Full reproducibility with immutable container images
- Environments where fast deployment isn't available
- Production deployments with all dependencies baked in
- Air-gapped or restricted deployment environments

### Key configuration

```python
import pathlib

from dep import foo

import flyte

env = flyte.TaskEnvironment(
    name="full_build",
    image=flyte.Image.from_debian_base().with_source_folder(
        pathlib.Path(__file__).parent,
        copy_contents_only=True  # Avoid nested folders
    ),
)

@env.task
def square(x) -> int:
    return x ** foo()

@env.task
def main(n: int) -> list[int]:
    return list(flyte.map(square, range(n)))

if __name__ == "__main__":
    # copy_contents_only=True requires root_dir=parent, False requires root_dir=parent.parent
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    run = flyte.with_runcontext(copy_style="none", version="x").run(main, n=10)
    print(run.url)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/deployment-patterns/full_build/main.py*

### Local dependency example

The main.py file imports from a local dependency that gets included in the build:

```python
def foo() -> int:
    return 1
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/deployment-patterns/full_build/dep.py*

### Critical configuration components

1. **Set `copy_style` to `"none"`**:
   ```python
   flyte.with_runcontext(copy_style="none", version="x").run(main, n=10)
   ```
   This disables Flyte's fast deployment system and forces a full container build.

2. **Set a custom version**:
   ```python
   flyte.with_runcontext(copy_style="none", version="x").run(main, n=10)
   ```
   The `version` parameter should be set to a desired value (not auto-generated) for consistent image tagging.

3. **Configure image source copying**:
   ```python
   image=flyte.Image.from_debian_base().with_source_folder(
       pathlib.Path(__file__).parent,
       copy_contents_only=True
   )
   ```
   Use `.with_source_folder()` to specify what code to copy into the container.

4. **Set `root_dir` correctly**:
   ```python
   flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
   ```
   - If `copy_contents_only=True`: Set `root_dir` to the source folder (contents are copied)
   - If `copy_contents_only=False`: Set `root_dir` to parent directory (folder is copied)

### Configuration options

#### Option A: Copy Folder Structure
```python
# Copies the entire folder structure into the container
image=flyte.Image.from_debian_base().with_source_folder(
    pathlib.Path(__file__).parent,
    copy_contents_only=False  # Default
)

# When copy_contents_only=False, set root_dir to parent.parent
flyte.init_from_config(root_dir=pathlib.Path(__file__).parent.parent)
```

#### Option B: Copy Contents Only (Recommended)
```python
# Copies only the contents of the folder (flattens structure)
# This is useful when you want to avoid nested folders - for example all your code is in the root of the repo
image=flyte.Image.from_debian_base().with_source_folder(
    pathlib.Path(__file__).parent,
    copy_contents_only=True
)

# When copy_contents_only=True, set root_dir to parent
flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
```

### Version management best practices

When using `copy_style="none"`, always specify an explicit version:
- Use semantic versioning: `"v1.0.0"`, `"v1.1.0"`
- Use build numbers: `"build-123"`
- Use git commits: `"abc123"`

Avoid auto-generated versions to ensure reproducible deployments.

### Performance considerations

- **Full builds take longer** than fast deployment
- **Container images will be larger** as they include all source code
- **Better for production** where immutability is important
- **Use during development** when testing the full deployment pipeline

### When to use

✅ **Use full build when:**
- Deploying to production environments
- Need immutable, reproducible container images
- Working with complex dependency structures
- Deploying to air-gapped or restricted environments
- Building CI/CD pipelines

❌ **Don't use full build when:**
- Rapid development and iteration
- Working with frequently changing code
- Development environments where speed matters
- Simple workflows without complex dependencies

### Troubleshooting

**Common issues:**
1. **Import errors**: Check your `root_dir` configuration matches `copy_contents_only`
2. **Missing files**: Ensure all dependencies are in the source folder
3. **Version conflicts**: Use explicit, unique version strings
4. **Build failures**: Check that the base image has all required system dependencies

**Debug tips:**
- Add print statements to verify file paths in containers
- Use `docker run -it <image> /bin/bash` to inspect built images
- Check Flyte logs for build errors and warnings
- Verify that relative imports work correctly in the container context

## Python path deployment

For projects where workflows are separated from business logic across multiple directories, use the Python path pattern with proper `root_dir` configuration.

### Example structure

```
pythonpath/
├── workflows/
│   └── workflow.py      # Flyte workflow definitions
├── src/
│   └── my_module.py     # Business logic modules
├── run.sh               # Execute from project root
└── run_inside_folder.sh # Execute from workflows/ directory
```

### Implementation

```python
import pathlib

from src.my_module import env, say_hello

import flyte

env = flyte.TaskEnvironment(
    name="workflow_env",
    depends_on=[env],
)

@env.task
async def greet(name: str) -> str:
    return await say_hello(name)

if __name__ == "__main__":
    current_dir = pathlib.Path(__file__).parent
    flyte.init_from_config(root_dir=current_dir.parent)
    r = flyte.run(greet, name="World")
    print(r.url)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/deployment-patterns/pythonpath/workflows/workflow.py*

```python
import flyte

env = flyte.TaskEnvironment(
    name="my_module",
)

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

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/deployment-patterns/pythonpath/src/my_module.py*

### Task environment dependencies

Note how the workflow imports both the task environment and the task function:

```python
from src.my_module import env, say_hello

env = flyte.TaskEnvironment(
    name="workflow_env",
    depends_on=[env],  # Depends on the imported environment
)
```

This pattern allows sharing task environments across modules while maintaining proper dependency relationships.

### Key considerations

- **Import resolution**: `root_dir` enables proper module imports across directories
- **File packaging**: Flyte packages all files starting from `root_dir`
- **Execution flexibility**: Works regardless of where you execute the script
- **PYTHONPATH handling**: Different behavior for CLI vs direct Python execution

### CLI vs Direct Python execution

#### Using Flyte CLI with `--root-dir` (Recommended)

When using `flyte run` with `--root-dir`, you don't need to export PYTHONPATH:

```bash
flyte run --root-dir . workflows/workflow.py greet --name "World"
```

The CLI automatically:
- Adds the `--root-dir` location to `sys.path`
- Resolves all imports correctly
- Packages files from the root directory for remote execution

#### Using Python directly

When running Python scripts directly, you must set PYTHONPATH manually:

```bash
PYTHONPATH=.:$PYTHONPATH python workflows/workflow.py
```

This is because:
- Python doesn't automatically know about your project structure
- You need to explicitly tell Python where to find your modules
- The `root_dir` parameter handles remote packaging, not local path resolution

### Best practices

1. **Always set `root_dir`** when workflows import from multiple directories
2. **Use pathlib** for cross-platform path handling
3. **Set `root_dir` to your project root** to ensure all dependencies are captured
4. **Test both execution patterns** to ensure deployment works from any directory

### Common pitfalls

- **Forgetting `root_dir`**: Results in import errors during remote execution
- **Wrong `root_dir` path**: May package too many or too few files
- **Not setting PYTHONPATH when using Python directly**: Use `flyte run --root-dir .` instead
- **Mixing execution methods**: If you use `flyte run --root-dir .`, you don't need PYTHONPATH

### When to use

- Legacy projects with established directory structures
- Separation of concerns between workflows and business logic
- Multiple workflow definitions sharing common modules
- Projects with complex import hierarchies

**Note:** This pattern is an escape hatch for larger projects where code organization requires separating workflows from business logic. Ideally, structure projects with `pyproject.toml` for cleaner dependency management.

## Dynamic environment deployment

For environments that need to change based on deployment context (development vs production), use dynamic environment selection based on Flyte domains.

### Domain-based environment selection

Use `flyte.current_domain()` to deterministically create different task environments based on the deployment domain:

```python
# NOTE: flyte.init() invocation at the module level is strictly discouraged.
# At runtime, Flyte controls initialization and configuration files are not present.

import os

import flyte

def create_env():
    if flyte.current_domain() == "development":
        return flyte.TaskEnvironment(name="dev", image=flyte.Image.from_debian_base(), env_vars={"MY_ENV": "dev"})
    return flyte.TaskEnvironment(name="prod", image=flyte.Image.from_debian_base(), env_vars={"MY_ENV": "prod"})

env = create_env()

@env.task
async def my_task(n: int) -> int:
    print(f"Environment Variable MY_ENV = {os.environ['MY_ENV']}", flush=True)
    return n + 1

@env.task
async def entrypoint(n: int) -> int:
    print(f"Environment Variable MY_ENV = {os.environ['MY_ENV']}", flush=True)
    return await my_task(n)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/deployment-patterns/dynamic_environments/environment_picker.py*

### Why this pattern works

**Environment reproducibility in local and remote clusters is critical.** Flyte re-instantiates modules in remote clusters, so `current_domain()` will be set correctly based on where the code executes.

✅ **Do use `flyte.current_domain()`** - Flyte automatically sets this based on the execution context

❌ **Don't use environment variables directly** - They won't yield correct results unless manually passed to the downstream system

### How it works

1. Flyte sets the domain context when initializing
2. `current_domain()` returns the domain string (e.g., "development", "staging", "production")
3. Your code deterministically configures resources based on this domain
4. When Flyte executes remotely, it re-instantiates modules with the correct domain context
5. The same environment configuration logic runs consistently everywhere

### Important constraints

`flyte.current_domain()` only works **after** `flyte.init()` is called:

- ✅ Works with `flyte run` and `flyte deploy` CLI commands (they init automatically)
- ✅ Works when called from `if __name__ == "__main__"` after explicit `flyte.init()`
- ❌ Does NOT work at module level without initialization

**Critical:** `flyte.init()` invocation at the module level is **strictly discouraged**. The reason is that at runtime, Flyte controls the initialization and configuration files are not present at runtime.

### Alternative: Environment variable approach

For cases where you need to pass domain information as environment variables to the container runtime, use this approach:

```python
import os

import flyte

def create_env(domain: str):
    # Pass domain as environment variable so tasks can see which domain they're running in
    if domain == "development":
        return flyte.TaskEnvironment(name="dev", image=flyte.Image.from_debian_base(), env_vars={"DOMAIN_NAME": domain})
    return flyte.TaskEnvironment(name="prod", image=flyte.Image.from_debian_base(), env_vars={"DOMAIN_NAME": domain})

env = create_env(os.getenv("DOMAIN_NAME", "development"))

@env.task
async def my_task(n: int) -> int:
    print(f"Environment Variable MY_ENV = {os.environ['DOMAIN_NAME']}", flush=True)
    return n + 1

@env.task
async def entrypoint(n: int) -> int:
    print(f"Environment Variable MY_ENV = {os.environ['DOMAIN_NAME']}", flush=True)
    return await my_task(n)

if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(entrypoint, n=5)
    print(r.url)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/deployment-patterns/dynamic_environments_with_envvars/environment_picker.py*

#### Key differences from domain-based approach

- **Environment variable access**: The domain name is available inside tasks via `os.environ['DOMAIN_NAME']`
- **External control**: Can be controlled via system environment variables before execution
- **Runtime visibility**: Tasks can inspect which environment they're running in during execution
- **Default fallback**: Uses `"development"` as default when `DOMAIN_NAME` is not set

#### Usage with environment variables

Set the environment variable and run:

```bash
export DOMAIN_NAME=production
flyte run environment_picker.py entrypoint --n 5
```

Or set it inline:

```bash
DOMAIN_NAME=development flyte run environment_picker.py entrypoint --n 5
```

#### When to use environment variables vs domain-based

**Use environment variables when:**
- Tasks need runtime access to environment information
- External systems set environment configuration
- You need flexibility to override environment externally
- Debugging requires visibility into environment selection

**Use domain-based approach when:**
- Environment selection should be automatic based on Flyte domain
- You want tighter integration with Flyte's domain system
- No need for runtime environment inspection within tasks

You can vary multiple aspects based on context:

- **Base images**: Different images for dev vs prod
- **Environment variables**: Configuration per environment
- **Resource requirements**: Different CPU/memory per domain
- **Dependencies**: Different package versions
- **Registry settings**: Different container registries

### Usage patterns

```bash
flyte run environment_picker.py entrypoint --n 5
flyte deploy environment_picker.py
```

For programmatic usage, ensure proper initialization:

```python
import flyte

flyte.init_from_config()
from environment_picker import entrypoint

if __name__ == "__main__":
    r = flyte.run(entrypoint, n=5)
    print(r.url)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/deployment-patterns/dynamic_environments/main.py*

### When to use dynamic environments

**General use cases:**
- Multi-environment deployments (dev/staging/prod)
- Different resource requirements per environment
- Environment-specific dependencies or settings
- Context-sensitive configuration needs

**Domain-based approach for:**
- Automatic environment selection tied to Flyte domains
- Simpler configuration without external environment variables
- Integration with Flyte's built-in domain system

**Environment variable approach for:**
- Runtime visibility into environment selection within tasks
- External control over environment configuration
- Debugging and logging environment-specific behavior
- Integration with external deployment systems that set environment variables

## Best practices

### Project organization

1. **Separate concerns**: Keep business logic separate from Flyte task definitions
2. **Use proper imports**: Structure projects for clean import patterns
3. **Version control**: Include all necessary files in version control
4. **Documentation**: Document deployment requirements and patterns

### Image management

1. **Registry configuration**: Use consistent registry settings across environments
2. **Image tagging**: Use meaningful tags for production deployments
3. **Base image selection**: Choose appropriate base images for your needs
4. **Dependency management**: Keep container images lightweight but complete

### Configuration management

1. **Root directory**: Set `root_dir` appropriately for your project structure
2. **Path handling**: Use `pathlib.Path` for cross-platform compatibility
3. **Environment variables**: Use environment-specific configurations
4. **Secrets management**: Handle sensitive data appropriately

### Development workflow

1. **Local testing**: Test tasks locally before deployment
2. **Incremental development**: Use `flyte run` for quick iterations
3. **Production deployment**: Use `flyte deploy` for permanent deployments
4. **Monitoring**: Monitor deployed tasks and environments

## Choosing the right pattern

| Pattern | Use Case | Complexity | Best For |
|---------|----------|------------|----------|
| Simple file | Quick prototypes, learning | Low | Single tasks, experiments |
| Custom Dockerfile | System dependencies, custom environments | Medium | Complex dependencies |
| PyProject package | Professional projects, async pipelines | Medium-High | Production applications |
| Package structure | Multiple workflows, shared utilities | Medium | Organized team projects |
| Full build | Production, reproducibility | High | Immutable deployments |
| Python path | Legacy structures, separated concerns | Medium | Existing codebases |
| Dynamic environment | Multi-environment, domain-aware deployments | Medium | Context-aware deployments |

Start with simpler patterns and evolve to more complex ones as your requirements grow. Many projects will combine multiple patterns as they scale and mature.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/task-deployment/run-context ===

# Run context

Every Flyte run has a **run context** — a set of invocation-time parameters that control where the run executes, where its outputs are stored, how caching behaves, and more.

There are two sides to run context:

- **Write side**: `flyte.with_runcontext()` — set run parameters before the run starts (programmatic) or via CLI flags.
- **Read side**: `flyte.ctx()` — access run parameters inside a running task.

## Configuring a run with `flyte.with_runcontext()`

`flyte.with_runcontext()` returns a runner object. Call `.run(task, ...)` on it to start the run with the specified context:

```
import flyte

env = flyte.TaskEnvironment("run-context-example")

@env.task
async def process(n: int) -> int:
    return n * 2

@env.task
async def root() -> int:
    return await process(21)

if __name__ == "__main__":
    flyte.init_from_config()
    flyte.with_runcontext(
        name="my-run",
        project="my-project",
        domain="development",
    ).run(root)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/run-context/run_context.py*

All parameters are optional. Unset parameters inherit from the configuration file (`config.yaml`) or system defaults.

### Execution target

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `mode` | `"local"` \| `"remote"` \| `"hybrid"` | *from config* | Where the run executes. `"remote"` runs on the Flyte backend; `"local"` runs in-process. |
| `project` | `str` | *from config* | Project to run in. |
| `domain` | `str` | *from config* | Domain to run in (e.g. `"development"`, `"production"`). |
| `name` | `str` | *auto-generated* | Custom name for the run, visible in the UI. |
| `version` | `str` | *from code bundle* | Version string for the ephemeral task deployment. |
| `queue` | `str` | *from config* | Cluster queue to schedule tasks on. |
| `interruptible` | `bool` | *per-task setting* | Override the interruptible setting for all tasks in the run. `True` allows spot/preemptible instances; `False` forces non-interruptible instances. |

### Storage

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `raw_data_path` | `str` | *from config* | Storage prefix for offloaded data types ([Files](../task-programming/files-and-directories), [Dirs](../task-programming/files-and-directories), [DataFrames](../task-programming/dataframes), checkpoints). Accepts `s3://`, `gs://`, or local paths. |
| `run_base_dir` | `str` | *auto-generated* | Base directory for run metadata passed between tasks. Distinct from `raw_data_path`. |

To direct all task outputs to a specific bucket for a run:

```
if __name__ == "__main__":
    flyte.init_from_config()
    flyte.with_runcontext(
        # Store all task outputs in a dedicated S3 prefix for this run
        raw_data_path="s3://my-bucket/runs/experiment-42/",
    ).run(root)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/run-context/run_context.py*

The equivalent CLI flag is `--raw-data-path`. See [Run command options](./run-command-options#--raw-data-path) for CLI usage.

### Caching

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `overwrite_cache` | `bool` | `False` | Re-execute all tasks even if a cached result exists, and overwrite the cache with new results. |
| `disable_run_cache` | `bool` | `False` | Skip cache lookups and writes entirely for this run. |
| `cache_lookup_scope` | `"global"` \| ... | `"global"` | Scope for cache lookups. |

### Identity and resources

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `service_account` | `str` | *from config* | Kubernetes service account for task pods. |
| `env_vars` | `Dict[str, str]` | `None` | Additional environment variables to inject into task containers. |
| `labels` | `Dict[str, str]` | `None` | Kubernetes labels to apply to task pods. |
| `annotations` | `Dict[str, str]` | `None` | Kubernetes annotations to apply to task pods. |

### Logging

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `log_level` | `int` | *from config* | Python log level (e.g. `logging.DEBUG`). |
| `log_format` | `"console"` \| ... | `"console"` | Log output format. |
| `reset_root_logger` | `bool` | `False` | If `True`, preserve the root logger unchanged. |

### Code bundling

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `copy_style` | `"loaded_modules"` \| `"all"` \| `"none"` | `"loaded_modules"` | Code bundling strategy. See [Run command options](./run-command-options#--copy-style). |
| `dry_run` | `bool` | `False` | Build and upload the code bundle without executing the run. |
| `copy_bundle_to` | `Path` | `None` | When `dry_run=True`, copy the bundle to this local path. |
| `interactive_mode` | `bool` | *auto-detected* | Override interactive mode detection (set automatically for Jupyter notebooks). |
| `preserve_original_types` | `bool` | `False` | Keep native DataFrame types (e.g. `pd.DataFrame`) rather than converting to `flyte.io.DataFrame` when deserializing outputs. |

### Context propagation

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `custom_context` | `Dict[str, str]` | `None` | Metadata propagated through the entire task hierarchy. Readable inside any task via `flyte.ctx().custom_context`. See [Custom context](../task-programming/custom-context). |

---

## Reading context inside a task with `flyte.ctx()`

Inside a running task, `flyte.ctx()` returns a `TaskContext` object with information about the current execution. Outside of a task, it returns `None`.

```
@env.task
async def inspect_context() -> str:
    ctx = flyte.ctx()
    action = ctx.action
    return (
        f"run={action.run_name}, "
        f"action={action.name}, "
        f"mode={ctx.mode}, "
        f"in_cluster={ctx.is_in_cluster()}"
    )
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/run-context/run_context.py*

### `TaskContext` fields

| Field | Type | Description |
|-------|------|-------------|
| `action` | `ActionID` | Identity of this specific action (task invocation) within the run. |
| `mode` | `"local"` \| `"remote"` \| `"hybrid"` | Execution mode of the current run. |
| `version` | `str` | Version of the deployed task code bundle. |
| `raw_data_path` | `str` | Storage prefix where offloaded outputs are written. |
| `run_base_dir` | `str` | Base directory for run metadata. |
| `custom_context` | `Dict[str, str]` | Propagated context metadata from `with_runcontext()`. |
| `disable_run_cache` | `bool` | Whether run caching is disabled for this run. |
| `is_in_cluster()` | method | Returns `True` when `mode == "remote"`. Useful for branching local/remote behavior. |

### `ActionID` fields

The `ctx.action` object identifies this specific task invocation:

| Field | Type | Description |
|-------|------|-------------|
| `name` | `str` | Unique identifier for this action. |
| `run_name` | `str` | Name of the parent run (defaults to `name` if not set). |
| `project` | `str \| None` | Project the action runs in. |
| `domain` | `str \| None` | Domain the action runs in. |
| `org` | `str \| None` | Organization. |

### Naming external resources

`ctx.action.run_name` is useful for tying external tool runs (experiment trackers, dashboards) to the corresponding Flyte run:

```
import wandb  # type: ignore[import]

@env.task
async def train_model(epochs: int) -> float:
    ctx = flyte.ctx()
    # Use run_name to tie the W&B run to this Flyte run
    run = wandb.init(
        project="my-project",
        name=ctx.action.run_name,
        config={"epochs": epochs},
    )
    # ... training logic ...
    loss = 0.42
    run.log({"loss": loss})
    run.finish()
    return loss
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/task-deployment/run-context/run_context.py*

This ensures that when you look up a run in Weights & Biases (or any other tool), its name matches what you see in the Flyte UI.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/run-scaling ===

# Scale your runs

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

This guide helps you understand and optimize the performance of your Flyte workflows. Whether you're building latency-sensitive applications or high-throughput data pipelines, these docs will help you make the right architectural choices.

## Understanding Flyte execution

Before optimizing performance, it's important to understand how Flyte executes your workflows:

- ****Scale your runs > Data flow****: Learn how data moves between tasks, including inline vs. reference data types, caching mechanisms, and storage configuration.
- ****Scale your runs > Life of a run****: Understand what happens when you invoke `flyte.run()`, from code analysis and image building to task execution and state management.

## Performance optimization

Once you understand the fundamentals, dive into performance tuning:

- ****Scale your runs > Scale your workflows****: A comprehensive guide to optimizing workflow performance, covering latency vs. throughput, task overhead analysis, batching strategies, reusable containers, and more.

## Key concepts for scaling

When scaling your workflows, keep these principles in mind:

1. **Task overhead matters**: The overhead of creating a task (uploading data, enqueuing, creating containers) should be much smaller than the task runtime.
2. **Batch for throughput**: For large-scale data processing, batch multiple items into single tasks to reduce overhead.
3. **Reusable containers**: Eliminate container startup overhead and enable concurrent execution with reusable containers.
4. **Traces for lightweight ops**: Use traces instead of tasks for lightweight operations that need checkpointing.
5. **Limit fanout**: Keep the total number of actions per run below 50k (target 10k-20k for best performance).
6. **Choose the right data types**: Use reference types (files, directories, DataFrames) for large data and inline types for small data.

For detailed guidance on each of these topics, see **Scale your runs > Scale your workflows**.

## Subpages
- **Scale your runs > Data flow**
- **Scale your runs > Life of a run**
- **Scale your runs > Scale your workflows**
- **Scale your runs > Maximize GPU utilization for batch inference**


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/run-scaling/data-flow ===

# Data flow

Understanding how data flows between tasks is critical for optimizing workflow performance in Flyte. Tasks take inputs and produce outputs, with data flowing seamlessly through your workflow using an efficient transport layer.

## Overview

Flyte tasks are run to completion. Each task takes inputs and produces exactly one output. Even if multiple instances run concurrently (such as in retries), only one output will be accepted. This deterministic data flow model provides several key benefits:

1. **Reduced boilerplate**: Automatic handling of files, DataFrames, directories, custom types, data classes, Pydantic models, and primitive types without manual serialization.
2. **Type safety**: Optional type annotations enable deeper type understanding, automatic UI form generation, and runtime type validation.
3. **Efficient transport**: Data is passed by reference (files, directories, DataFrames) or by value (primitives) based on type.
4. **Durable storage**: All data is stored durably and accessible through APIs and the UI.
5. **Caching support**: Efficient caching using shallow immutable references for referenced data.

## Data types and transport

Flyte handles different data types with different transport mechanisms:

### Passed by reference

These types are not copied but passed as references to storage locations:

- **Files**: `flyte.io.File`
- **Directories**: `flyte.io.Dir`
- **Dataframes**: `flyte.io.DataFrame`, `pd.DataFrame`, `pl.DataFrame`, etc.

Dataframes are automatically converted to Parquet format and read using Apache Arrow for zero-copy reads. Use `flyte.io.DataFrame` for lazy materialization to any supported type like pandas or polars. [Learn more about the Flyte Dataframe type](../../user-guide/task-programming/dataframes)

### Passed by value (inline I/O)

Primitive and structured types are serialized and passed inline:

| Type Category | Examples | Serialization |
|--------------|----------|---------------|
| **Primitives** | `int`, `float`, `str`, `bool`, `None` | MessagePack |
| **Time types** | `datetime.datetime`, `datetime.date`, `datetime.timedelta` | MessagePack |
| **Collections** | `list`, `dict`, `tuple` | MessagePack |
| **Data structures** | data classes, Pydantic `BaseModel` | MessagePack |
| **Enums** | `enum.Enum` subclasses | MessagePack |
| **Unions** | `Union[T1, T2]`, `Optional[T]` | MessagePack |
| **Protobuf** | `google.protobuf.Message` | Binary |

Flyte uses efficient MessagePack serialization for most types, providing compact binary representation with strong type safety.

> [!NOTE]
> If type annotations are not used, or if `typing.Any` or unrecognized types are used, data will be pickled. By default, pickled objects smaller than 10KB are passed inline, while larger pickled objects are automatically passed as a file. Pickling allows for progressive typing but should be used carefully.

## Task execution and data flow

### Input download

When a task starts:

1. **Inline inputs download**: The task downloads inline inputs from the configured Flyte object store.
2. **Size limits**: By default, inline inputs are limited to 10MB, but this can be adjusted using `flyte.TaskEnvironment`'s `max_inline_io` parameter.
3. **Memory consideration**: Inline data is materialized in memory, so adjust your task resources accordingly.
4. **Reference materialization**: Reference data (files, directories) is passed using special types in `flyte.io`. Dataframes are automatically materialized if using `pd.DataFrame`. Use `flyte.io.DataFrame` to avoid automatic materialization.

### Output upload

When a task returns data:

1. **Inline data**: Uploaded to the Flyte object store configured at the organization, project, or domain level.
2. **Reference data**: Stored in the same metadata store by default, or configured using `flyte.with_runcontext(raw_data_storage=...)`.
3. **Separate prefixes**: Each task creates one output per retry attempt in separate prefixes, making data incorruptible by design.

## Task-to-task data flow

When a task invokes downstream tasks:

1. **Input recording**: The input to the downstream task is recorded to the object store.
2. **Reference upload**: All referenced objects are uploaded (if not already present).
3. **Task invocation**: The downstream task is invoked on the remote server.
4. **Parallel execution**: When multiple tasks are invoked in parallel using `flyte.map` or `asyncio`, inputs are written in parallel.
5. **Storage layer**: Data writing uses the `flyte.storage` layer, backed by the Rust-based `object-store` crate and optionally `fsspec` plugins.
6. **Output download**: Once the downstream task completes, inline outputs are downloaded and returned to the calling task.

## Caching and data hashing

Understanding how Flyte caches data is essential for performance optimization.

### Cache key computation

A cache hit occurs when the following components match:

- **Task name**: The fully-qualified task name
- **Computed input hash**: Hash of all inputs (excluding `ignored_inputs`)
- **Task interface hash**: Hash of input and output types
- **Task config hash**: Hash of task configuration
- **Cache version**: User-specified or automatically computed

### Inline data caching

All inline data is cached using a consistent hashing system. The cache key is derived from the data content.

### Reference data hashing

Reference data (files, directories) is hashed shallowly by default using the hash of the storage location. You can customize hashing:

- Use `flyte.io.File.new_remote()` or `flyte.io.File.from_existing_remote()` with custom hash functions or values.
- Provide explicit hash values for deep content hashing if needed.

### Cache control

Control caching behavior using `flyte.with_runcontext`:

- **Scope**: Set `cache_lookup_scope` to `"global"` or `"project/domain"`.
- **Disable cache**: Set `overwrite_cache=True` to force re-execution.

For more details on caching configuration, see [Caching](../task-configuration/caching).

## Traces and data flow

When using [traces](../task-programming/traces), the data flow behavior is different:

1. **Full execution first**: The trace is fully executed before inputs and outputs are recorded.
2. **Checkpoint behavior**: Recording happens like a checkpoint at the end of trace execution.
3. **Streaming iterators**: The entire output is buffered and recorded after the stream completes. Buffering is pass-through, allowing caller functions to consume output while buffering.
4. **Chained traces**: All traces are recorded after the last one completes consumption.
5. **Same process with `asyncio`**: Traces run within the same Python process and support `asyncio` parallelism, so failures can be retried, effectively re-running the trace.
6. **Lightweight overhead**: Traces only have the overhead of data storage (no task orchestration overhead).

> [!NOTE]
> Traces are not a substitute for tasks if you need caching. Tasks provide full caching capabilities, while traces provide lightweight checkpointing with storage overhead. However, traces support concurrent execution using `asyncio` patterns within a single task.

## Object stores and latency considerations

By default, Flyte uses object stores like S3, GCS, Azure Storage, and R2 as metadata stores. These have high latency for smaller objects, so:

- **Minimum task duration**: Tasks should take at least a second to run to amortize storage overhead.
- **Future improvements**: High-performance metastores like Redis and PostgreSQL may be supported in the future. Contact the Union team if you're interested.

## Configuring data storage

### Organization and project level

Object stores are configured at the organization level or per project/domain. Documentation for this configuration is coming soon.

### Per-run configuration

Configure raw data storage on a per-run basis using `flyte.with_runcontext`:

```python
run = flyte.with_runcontext(
    raw_data_storage="s3://my-bucket/custom-path"
).run(my_task, input_data=data)
```

This allows you to control where reference data (files, directories, DataFrames) is stored for specific runs.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/run-scaling/life-of-a-run ===

# Life of a run

Understanding what happens when you invoke `flyte.run()` is crucial for optimizing workflow performance and debugging issues. This guide walks through each phase of task execution from submission to completion.

## Overview

When you execute `flyte.run()`, the system goes through several phases:

1. **Code analysis and preparation**: Discover environments and images
2. **Image building**: Build container images if changes are detected
3. **Code bundling**: Package your Python code
4. **Upload**: Transfer the code bundle to object storage
5. **Run creation**: Submit the run to the backend
6. **Task execution**: Execute the task in the data plane
7. **State management**: Track and persist execution state

## Phase 1: Code analysis and preparation

When `flyte.run()` is invoked:

1. **Environment discovery**: Flyte analyzes your code and finds all relevant `flyte.TaskEnvironment` instances by walking the `depends_on` hierarchy.
2. **Image identification**: Discovers unique `flyte.Image` instances used across all environments.
3. **Image building**: Starts the image building process. Images are only built if a change is detected.

> [!NOTE]
> If you invoke `flyte.run()` multiple times within the same Python process without changing code (such as in a notebook or script), the code bundling and image building steps are done only once. This can dramatically speed up iteration.

## Phase 2: Image building

Container images provide the runtime environment for your tasks:

- **Change detection**: Images are only rebuilt if changes are detected in dependencies or configuration.
- **Caching**: Previously built images are reused when possible.
- **Parallel builds**: Multiple images can be built concurrently.

For more details on container images, see [Container Images](../task-configuration/container-images).

## Phase 3: Code bundling

After images are built, your project files are bundled:

### Default: `copy_style="loaded_modules"`

By default, all Python modules referenced by the invoked tasks through module-level import statements are automatically copied. This provides a good balance between completeness and efficiency.

### Alternative: `copy_style="none"`

Skip bundling by setting `copy_style="none"` in `flyte.with_runcontext()` and adding all code into `flyte.Image`:

```python
# Add code to image
image = flyte.Image().with_source_code("/path/to/code")

# Or use Dockerfile
image = flyte.Image.from_dockerfile("Dockerfile")

# Skip bundling
run = flyte.with_runcontext(copy_style="none").run(my_task, input_data=data)
```

For more details on code packaging, see [Packaging](../task-deployment/packaging).

## Phase 4: Upload code bundle

Once the code bundle is created:

1. **Request signed URL**: The SDK sends the bundle checksum and target path to the Control Plane.
2. **Control Plane obtains URL**: The Control Plane calls the Data Plane to obtain a signed URL for that checksum and path.
3. **Direct upload**: The signed URL is returned to the SDK, which uploads the code bundle directly to the object store.

## Phase 5: Run creation and queuing

The `CreateRun` API is invoked:

1. **Copy inputs**: Input data is copied to the object store.
2. **En-queue a run**: The run is queued into the Union Control Plane.
3. **Hand off to executor**: Union Control Plane hands the task to the Executor Service in your data plane.
4. **Create action**: The parent task action (called `a0`) is created.

## Phase 6: Task execution in data plane

### Container startup

1. **Container starts**: The task container starts in your data plane.
2. **Download code bundle**: The Flyte runtime downloads the code bundle from object storage.
3. **Inflate task**: The task is inflated from the code bundle.
4. **Download inputs**: Inline inputs are downloaded from the object store.
5. **Execute task**: The task is executed with context and inputs.

### Invoking downstream tasks

If the task invokes other tasks:

1. **Controller thread**: A controller thread starts to communicate with the backend Queue Service.
2. **Monitor status**: The controller monitors the status of downstream actions.
3. **Crash recovery**: If the task crashes, the action identifier is deterministic, allowing the task to resurrect its state from Union Control Plane.
4. **Replay**: The controller efficiently replays state (even at large scale) to find missing completions and resume monitoring.

### Execution flow diagram

```mermaid
sequenceDiagram
    participant Client as SDK/Client
    participant Control as Control Plane<br/>(Queue Service)
    participant Data as Data Plane<br/>(Executor)
    participant ObjStore as Object Store
    participant Container as Task Container

    Client->>Client: Analyze code & discover environments
    Client->>Client: Build images (if changed)
    Client->>Client: Bundle code
    Client->>Control: Request signed URL (checksum, path)
    Control->>Data: Get signed URL for bundle
    Data-->>Control: Signed URL
    Control-->>Client: Signed URL
    Client->>ObjStore: Upload code bundle (signed URL)
    Client->>Control: CreateRun API with inputs
    Control->>Data: Copy inputs
    Data->>ObjStore: Write inputs
    Control->>Data: Queue task (create action a0)
    Data->>Container: Start container
    Container->>Data: Request code bundle
    Data->>ObjStore: Read code bundle
    ObjStore-->>Data: Code bundle
    Data-->>Container: Code bundle
    Container->>Container: Inflate task
    Container->>Data: Request inputs
    Data->>ObjStore: Read inputs
    ObjStore-->>Data: Inputs
    Data-->>Container: Inputs
    Container->>Container: Execute task

    alt Invokes downstream tasks
        Container->>Container: Start controller thread
        Container->>Control: Submit downstream tasks
        Control->>Data: Queue downstream actions
        Container->>Control: Monitor downstream status
        Control-->>Container: Status updates
    end

    Container->>Data: Upload outputs
    Data->>ObjStore: Write outputs
    Container->>Control: Complete
    Control-->>Client: Run complete
```

## Action identifiers and crash recovery

Flyte uses deterministic action identifiers to enable robust crash recovery:

- **Consistent identifiers**: Action identifiers are consistently computed based on task and invocation context.
- **Re-run identical**: In any re-run, the action identifier is identical for the same invocation.
- **Multiple invocations**: Multiple invocations of the same task receive unique identifiers.
- **Efficient resurrection**: On crash, the `a0` action resurrects its state from Union Control Plane efficiently, even at large scale.
- **Replay and resume**: The controller replays execution until it finds missing completions and starts watching them.

## Downstream task execution

When downstream tasks are invoked:

1. **Action creation**: Downstream actions are created with unique identifiers.
2. **Queue assignment**: Actions are handed to an executor, which can be selected using a queue or from the general pool.
3. **Parallel execution**: Multiple downstream tasks can execute in parallel.
4. **Result aggregation**: Results are aggregated and returned to the parent task.

## Reusable containers

When using [reusable containers](../task-configuration/reusable-containers), the execution model changes:

1. **Environment spin-up**: The container environment is first spun up with configured replicas.
2. **Task allocation**: Tasks are allocated to available replicas in the environment.
3. **Scaling**: If all replicas are busy, new replicas are spun up (up to the configured maximum), or tasks are backlogged in queues.
4. **Container reuse**: The same container handles multiple task executions, reducing startup overhead.
5. **Lifecycle management**: Containers are managed according to `ReusePolicy` settings (`idle_ttl`, `scaledown_ttl`, etc.).

### Reusable container execution flow

```mermaid
sequenceDiagram
    participant Control as Queue Service
    participant Executor as Executor Service
    participant Pool as Container Pool
    participant Replica as Container Replica

    Control->>Executor: Submit task

    alt Reusable containers enabled
        Executor->>Pool: Request available replica

        alt Replica available
            Pool->>Replica: Allocate task
            Replica->>Replica: Execute task
            Replica->>Pool: Task complete (ready for next)
        else No replica available
            alt Can scale up
                Executor->>Pool: Create new replica
                Pool->>Replica: Spin up new container
                Replica->>Replica: Execute task
                Replica->>Pool: Task complete
            else At max replicas
                Executor->>Pool: Queue task
                Pool-->>Executor: Wait for available replica
                Pool->>Replica: Allocate when available
                Replica->>Replica: Execute task
                Replica->>Pool: Task complete
            end
        end
    else No reusable containers
        Executor->>Replica: Create new container
        Replica->>Replica: Execute task
        Replica->>Executor: Complete & terminate
    end

    Replica-->>Control: Return results
```

## State replication and visualization

### Queue Service to Run Service

1. **Reliable replication**: Queue Service reliably replicates execution state back to Run Service.
2. **Eventual consistency**: The Run Service may be slightly behind the actual execution state.
3. **Visualization**: Run Service paints the entire run onto the UI.

### UI limitations

- **Current limit**: The UI is currently limited to displaying 50k actions per run.
- **Future improvements**: This limit will be increased in future releases. Contact the Union team if you need higher limits.

## Optimization opportunities

Understanding the life of a run reveals several optimization opportunities:

1. **Reuse Python process**: Run `flyte.run()` multiple times in the same process to avoid re-bundling code.
2. **Skip bundling**: Use `copy_style="none"` and bake code into images for faster startup.
3. **Reusable containers**: Use reusable containers to eliminate container startup overhead.
4. **Parallel execution**: Invoke multiple downstream tasks concurrently using `flyte.map()` or `asyncio`.
5. **Efficient data flow**: Minimize data transfer by using reference types (files, directories) instead of inline data.
6. **Caching**: Enable task caching to avoid redundant computation.

For detailed performance tuning guidance, see [Scale your workflows](./scale-your-workflows).


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/run-scaling/scale-your-workflows ===

# Scale your workflows

Performance optimization in Flyte involves understanding the interplay between task execution overhead, data transfer, and concurrency. This guide helps you identify bottlenecks and choose the right patterns for your workload.

## Understanding performance dimensions

Performance optimization focuses on two key dimensions:

### Latency

**Goal**: Minimize end-to-end execution time for individual workflows.

**Characteristics**:
- Fast individual actions (milliseconds to seconds)
- Total action count typically less than 1,000
- Critical for interactive applications and real-time processing
- Multi-step inference, with reusing model or data in memory (use reusable containers with [@alru.cache](https://pypi.org/project/async-lru/))

**Recommended approach**:
- Use tasks for orchestration and parallelism
- Use [traces](../task-programming/traces) for fine-grained checkpointing
- Model parallelism using `asyncio` and use things methods like `asyncio.as_completed` or `asyncio.gather` to join the parallelism
- Leverage [reusable containers](../task-configuration/reusable-containers) with concurrency to eliminate startup overhead and optimize resource utilization

### Throughput

**Goal**: Maximize the number of items processed per unit time.

**Characteristics**:
- Processing large datasets (millions of items)
- High total action count (10k to 50k actions)
- Batch processing, large-scale batch inference and ETL workflows

**Recommended approach**:
- Batch workloads to reduce overhead
- Limit fanout to manage system load
- Use reusable containers with concurrency for maximum utilization
- Balance task granularity with overhead

## Task execution overhead

Understanding task overhead is critical for performance optimization. When you invoke a task, several operations occur:

| Operation | Symbol | Description |
|-----------|--------|-------------|
| **Upload data** | `u` | Time to upload input data to object store |
| **Download data** | `d` | Time to download input data from object store |
| **Enqueue task** | `e` | Time to enqueue task in Queue Service |
| **Create instance** | `t` | Time to create task container instance |

**Total overhead per task**: `2u + 2d + e + t`

This overhead includes:
- Uploading inputs from the parent task (`u`)
- Downloading inputs in the child task (`d`)
- Uploading outputs from the child task (`u`)
- Downloading outputs in the parent task (`d`)
- Enqueuing the task (`e`)
- Creating the container instance (`t`)

### The overhead principle

For efficient execution, task overhead should be much smaller than task runtime:

```
Total overhead (2u + 2d + e + t) << Task runtime
```

If task runtime is comparable to or less than overhead, consider:
1. **Batching**: Combine multiple work items into a single task
2. **Traces**: Use traces instead of tasks for lightweight operations
3. **Reusable containers**: Eliminate container creation overhead (`t`)
4. **Local execution**: Run lightweight operations within the parent task

## System architecture and data flow

To optimize performance, understand how tasks flow through the system:

1. **Control plane to data plane**: Tasks flow from the control plane (Run Service, Queue Service) to the data plane (Executor Service).
2. **Data movement**: Data moves between tasks through object storage. See [Data flow](./data-flow) for details.
3. **State replication**: Queue Service reliably replicates state back to Run Service for visualization. The Run Service may be slightly behind actual execution.

For a detailed walkthrough of task execution, see [Life of a run](./life-of-a-run).

## Optimization strategies

### 1. Use reusable containers for concurrency

[Reusable containers](../task-configuration/reusable-containers) eliminate the container creation overhead (`t`) and enable concurrent task execution:

```python
import flyte
from datetime import timedelta

# Define reusable environment
env = flyte.TaskEnvironment(
    name="high-throughput",
    reuse_policy=flyte.ReusePolicy(
        replicas=(2, 10),           # Auto-scale from 2 to 10 replicas
        concurrency=5,              # 5 tasks per replica = 50 max concurrent
        scaledown_ttl=timedelta(minutes=10),
        idle_ttl=timedelta(hours=1)
    )
)

@env.task
async def process_item(item: dict) -> dict:
    # Process individual item
    return {"processed": item["id"]}
```

**Benefits**:
- Eliminates container startup overhead (`t ≈ 0`)
- Supports concurrent execution (multiple tasks per container)
- Auto-scales based on demand
- Reuses Python environment and loaded dependencies

**Limitations**:
- Concurrency is limited by CPU and I/O resources in the container
- Memory requirements scale with total working set size
- Best for I/O-bound tasks or async operations

### 2. Batch workloads to reduce overhead

For high-throughput processing, batch multiple items into a single task:

```python
@env.task
async def process_batch(items: list[dict]) -> list[dict]:
    """Process a batch of items in a single task."""
    results = []
    for item in items:
        result = await process_single_item(item)
        results.append(result)
    return results

@env.task
async def process_large_dataset(dataset: list[dict]) -> list[dict]:
    """Process 1M items with batching."""
    batch_size = 1000  # Adjust based on overhead calculation
    batches = [dataset[i:i + batch_size] for i in range(0, len(dataset), batch_size)]

    # Process batches in parallel (1000 tasks instead of 1M)
    results = await asyncio.gather(*[process_batch(batch) for batch in batches])

    # Flatten results
    return [item for batch_result in results for item in batch_result]
```

**Benefits**:
- Reduces total number of tasks (e.g., 1000 tasks instead of 1M)
- Amortizes overhead across multiple items
- Lower load on Queue Service and object storage

**Choosing batch size**:
1. Calculate overhead: `overhead = 2u + 2d + e + t`
2. Target task runtime: `runtime > 10 × overhead` (rule of thumb)
3. Adjust batch size to achieve target runtime
4. Consider memory constraints (larger batches require more memory)

### 3. Use traces for lightweight operations

[Traces](../task-programming/traces) provide fine-grained checkpointing with minimal overhead:

```python
@flyte.trace
async def fetch_data(url: str) -> dict:
    """Traced function for API call."""
    response = await http_client.get(url)
    return response.json()

@flyte.trace
async def transform_data(data: dict) -> dict:
    """Traced function for transformation."""
    return {"transformed": data}

@env.task
async def process_workflow(urls: list[str]) -> list[dict]:
    """Orchestrate using traces instead of tasks."""
    results = []
    for url in urls:
        data = await fetch_data(url)
        transformed = await transform_data(data)
        results.append(transformed)
    return results
```

**Benefits**:
- Only storage overhead (no task orchestration overhead)
- Runs in the same Python process with asyncio parallelism
- Provides checkpointing and resumption
- Visible in execution logs and UI

**Trade-offs**:
- No caching (use tasks for cacheable operations)
- Shares resources with the parent task (CPU, memory)
- Storage writes may still be slow due to object store latency

**When to use traces**:
- API calls and external service interactions
- Deterministic transformations that need checkpointing
- Operations taking more than 1 second (to amortize storage overhead)

### 4. Limit fanout for system stability

The UI and system have limits on the number of actions per run:

- **Current limit**: 50k actions per run
- **Future**: Higher limits will be supported (contact the Union team if needed)

**Example: Control fanout with batching**

```python
@env.task
async def process_million_items(items: list[dict]) -> list[dict]:
    """Process 1M items with controlled fanout."""
    # Target 10k tasks, each processing 100 items
    batch_size = 100
    max_fanout = 10000

    batches = [items[i:i + batch_size] for i in range(0, len(items), batch_size)]

    # Use flyte.map for parallel execution
    results = await flyte.map(process_batch, batches)

    return [item for batch in results for item in batch]
```

### 5. Optimize data transfer

Minimize data transfer overhead by choosing appropriate data types:

**Use reference types for large data**:
```python
from flyte.io import File, Directory, DataFrame

@env.task
async def process_large_file(input_file: File) -> File:
    """Files passed by reference, not copied."""
    # Download only when needed
    local_path = input_file.download()

    # Process file
    result_path = process(local_path)

    # Upload result
    return File.new_remote(result_path)
```

**Use inline types for small data**:
```python
@env.task
async def process_metadata(metadata: dict) -> dict:
    """Small dicts passed inline efficiently."""
    return {"processed": metadata}
```

**Guideline**:
- **< 10 MB**: Use inline types (primitives, small dicts, lists)
- **> 10 MB**: Use reference types (File, Directory, DataFrame)
- **Adjust**: Use `max_inline_io` in `TaskEnvironment` to change the threshold

See [Data flow](./data-flow) for details on data types and transport.

### 6. Leverage caching

Enable [caching](../task-configuration/caching) to avoid redundant computation:

```python
@env.task(cache="auto")
async def expensive_computation(input_data: dict) -> dict:
    """Automatically cached based on inputs."""
    # Expensive operation
    return result
```

**Benefits**:
- Skips re-execution for identical inputs
- Reduces overall workflow runtime
- Preserves resources for new computations

**When to use**:
- Deterministic tasks (same inputs → same outputs)
- Expensive computations (model training, large data processing)
- Stable intermediate results

### 7. Parallelize with `flyte.map`

Use [`flyte.map`](../task-programming/fanout) for data-parallel workloads:

```python
@env.task
async def process_item(item: dict) -> dict:
    return {"processed": item}

@env.task
async def parallel_processing(items: list[dict]) -> list[dict]:
    """Process items in parallel using map."""
    results = await flyte.map(process_item, items)
    return results
```

**Benefits**:
- Automatic parallelization
- Dynamic scaling based on available resources
- Built-in error handling and retries

**Best practices**:
- Combine with batching to control fanout
- Use with reusable containers for maximum throughput
- Consider memory and resource limits

## Performance tuning workflow

Follow this workflow to optimize your Flyte workflows:

1. **Profile**: Measure task execution times and identify bottlenecks.
2. **Calculate overhead**: Estimate `2u + 2d + e + t` for your tasks.
3. **Compare**: Check if `task runtime >> overhead`. If not, optimize.
4. **Batch**: Increase batch size to amortize overhead.
5. **Reusable containers**: Enable reusable containers to eliminate `t`.
6. **Traces**: Use traces for lightweight operations within tasks.
7. **Cache**: Enable caching for deterministic, expensive tasks.
8. **Limit fanout**: Keep total actions below 50k (target 10k-20k).
9. **Monitor**: Use the UI to monitor execution and identify issues.
10. **Iterate**: Continuously refine based on performance metrics.

## Real-world example: PyIceberg batch processing

For a comprehensive example of efficient data processing with Flyte, see the [PyIceberg parallel batch aggregation example](https://github.com/flyteorg/flyte-sdk/blob/main/examples/data_processing/pyiceberg_example.py). This example demonstrates:

- **Zero-copy data passing**: Pass file paths instead of data between tasks
- **Reusable containers with concurrency**: Maximize CPU utilization across workers
- **Parallel file processing**: Use `asyncio.gather()` to process multiple files concurrently
- **Efficient batching**: Distribute parquet files across worker tasks

Key pattern from the example:

```python
# Instead of loading entire table, get file paths
file_paths = [task.file.file_path for task in table.scan().plan_files()]

# Distribute files across partitions (zero-copy!)
partition_files = distribute_files(file_paths, num_partitions)

# Process partitions in parallel
results = await asyncio.gather(*[
    aggregate_partition(files, partition_id)
    for partition_id, files in enumerate(partition_files)
])
```

This approach achieves true parallel file processing without loading the entire dataset into memory.

## Example: Optimizing a data pipeline

### Before optimization

```python
@env.task
async def process_item(item: dict) -> dict:
    # Very fast operation (~100ms)
    return {"processed": item["id"]}

@env.task
async def process_dataset(items: list[dict]) -> list[dict]:
    # Create 1M tasks
    results = await asyncio.gather(*[process_item(item) for item in items])
    return results
```

**Issues**:
- 1M tasks created (exceeds UI limit)
- Task overhead >> task runtime (100ms task, seconds of overhead)
- High load on Queue Service and object storage

### After optimization

```python
# Use reusable containers
env = flyte.TaskEnvironment(
    name="optimized-pipeline",
    reuse_policy=flyte.ReusePolicy(
        replicas=(5, 20),
        concurrency=10,
        scaledown_ttl=timedelta(minutes=10),
        idle_ttl=timedelta(hours=1)
    )
)

@env.task
async def process_batch(items: list[dict]) -> list[dict]:
    # Process batch of items
    return [{"processed": item["id"]} for item in items]

@env.task
async def process_dataset(items: list[dict]) -> list[dict]:
    # Create 1000 tasks (batch size 1000)
    batch_size = 1000
    batches = [items[i:i + batch_size] for i in range(0, len(items), batch_size)]

    results = await flyte.map(process_batch, batches)
    return [item for batch in results for item in batch]
```

**Improvements**:
- 1000 tasks instead of 1M (within limits)
- Batch runtime ~100 seconds (100ms × 1000 items)
- Reusable containers eliminate startup overhead
- Concurrency enables high throughput (200 concurrent tasks max)

## When to contact the Union team

Reach out to the Union team if you:

- Need more than 50k actions per run
- Want to use high-performance metastores (Redis, PostgreSQL) instead of object stores
- Have specific performance requirements or constraints
- Need help profiling and optimizing your workflows


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/run-scaling/batch-inference ===

# Maximize GPU utilization for batch inference

GPUs are expensive. When running batch inference, the single biggest cost driver is **idle GPU time** — cycles where the GPU sits waiting with nothing to do. Understanding why this happens and how to fix it is the key to cost-effective batch inference.

## Why GPU utilization drops

A typical inference task does three things:

1. **Load data** — read from storage, deserialize, preprocess (CPU/IO-bound)
2. **Run inference** — forward pass through the model (GPU-bound)
3. **Post-process** — format results, write outputs (CPU/IO-bound)

When these steps run sequentially, the GPU is idle during steps 1 and 3. For many workloads, data loading and preprocessing dominate wall-clock time, leaving the GPU busy for only a fraction of the total:

```mermaid
gantt
    title Sequential execution — GPU idle during CPU/IO work
    dateFormat X
    axisFormat %s

    section Task 1
    Load data (CPU/IO)     :a1, 0, 3
    Inference (GPU)        :a2, after a1, 2
    Post-process (CPU/IO)  :a3, after a2, 1

    section Task 2
    Load data (CPU/IO)     :b1, after a3, 3
    Inference (GPU)        :b2, after b1, 2
    Post-process (CPU/IO)  :b3, after b2, 1

    section GPU
    Idle                   :crit, g1, 0, 3
    Busy                   :active, g2, 3, 5
    Idle                   :crit, g3, 5, 9
    Busy                   :active, g4, 9, 11
    Idle                   :crit, g5, 11, 12
```

In this example, the GPU is busy for only 4 out of 12 time units — **33% utilization**. The rest is wasted waiting for CPU and IO operations.

## Serving vs in-process batch inference

There are two common approaches to batch inference: sending requests to a **hosted model server** (serving), or running the model **in-process** alongside data loading. Each has distinct trade-offs:

| | Hosted serving | In-process (Flyte) |
|---|---|---|
| **Architecture** | Separate inference server (e.g. Triton, vLLM server, TGI) accessed over the network | Model loaded directly in the task process, inference via `DynamicBatcher` |
| **Data transfer** | Every request serialized over the network; large payloads add latency | Zero-copy — data stays in-process, no serialization overhead |
| **Backpressure** | Hard to implement; push-based architecture can overwhelm the server or drop requests | Two levels: `DynamicBatcher` queue blocks producers when full, and Flyte's task scheduling automatically queues new inference tasks when replicas are busy — backpressure propagates end-to-end without any extra code |
| **Utilization** | Servers are often over-provisioned to maintain availability, leading to low average utilization | Batcher continuously fills the GPU with work from concurrent producers |
| **Multi-model** | Each model needs its own serving deployment, load balancer, and scaling config | Multiple models can time-share the same GPU — when one model finishes, the next is loaded automatically via reusable containers, no container orchestration required |
| **Scaling** | Requires separate infrastructure for the serving layer (load balancers, autoscalers, health checks) | Scales with Flyte — replicas auto-scale based on demand |
| **Cost** | Pay for always-on serving infrastructure even during low-traffic periods | Pay only for the duration of the batch job |
| **Fault tolerance** | Need retries, circuit breakers, and timeout handling for network failures | Failures are local; Flyte handles retries and recovery at the task level |
| **Best for** | Real-time / low-latency serving with unpredictable request patterns | Large-scale batch processing with known datasets |

For batch workloads, in-process inference eliminates the network overhead and infrastructure complexity of a serving layer while achieving higher GPU utilization through intelligent batching.

## Solution: `DynamicBatcher`

`DynamicBatcher` from `flyte.extras` solves the utilization problem by **separating data loading from inference** and running them concurrently. Multiple async producers load and preprocess data while a single consumer feeds the GPU in optimally-sized batches:

```mermaid
flowchart LR
    subgraph producers ["Concurrent producers (CPU/IO)"]
        P1["Stream 1: load + preprocess"]
        P2["Stream 2: load + preprocess"]
        P3["Stream N: load + preprocess"]
    end

    subgraph batcher ["DynamicBatcher"]
        Q["Queue with backpressure"]
        A["Aggregation loop<br/>(assembles cost-budgeted batches)"]
        Q --> A
    end

    subgraph consumer ["Processing loop (GPU)"]
        G["process_fn / inference_fn<br/>(batched forward pass)"]
    end

    P1 --> Q
    P2 --> Q
    P3 --> Q
    A --> G
```

The batcher runs two internal loops:

1. **Aggregation loop** — drains the submission queue and assembles batches that respect a cost budget (`target_batch_cost`), a maximum size (`max_batch_size`), and a timeout (`batch_timeout_s`). This ensures the GPU always receives optimally-sized batches.
2. **Processing loop** — pulls assembled batches and calls your processing function, resolving each record's future with its result.

This pipelining means the GPU is processing batch N while data for batch N+1 is being loaded and assembled — **eliminating idle time**.

### Basic usage

```python
from flyte.extras import DynamicBatcher

async def process(batch: list[dict]) -> list[str]:
    """Your batch processing function. Must return results in the same order as the input."""
    return [heavy_computation(item) for item in batch]

async with DynamicBatcher(
    process_fn=process,
    target_batch_cost=1000,   # cost budget per batch
    max_batch_size=64,        # hard cap on records per batch
    batch_timeout_s=0.05,     # max wait time before dispatching a partial batch
    max_queue_size=5_000,     # queue size for backpressure
) as batcher:
    futures = []
    for record in my_records:
        future = await batcher.submit(record, estimated_cost=10)
        futures.append(future)
    results = await asyncio.gather(*futures)
```

Each call to `submit()` is non-blocking — it enqueues the record and immediately returns a `Future`. When the queue is full, `submit()` awaits until space is available, providing natural backpressure to prevent producers from overwhelming the GPU.

### Cost estimation

The batcher uses cost estimates to decide how many records to group into each batch. You can provide costs in several ways (checked in order of precedence):

1. **Explicit** — pass `estimated_cost` to `submit()`
2. **Estimator function** — pass `cost_estimator` to the constructor
3. **Protocol** — implement `estimate_cost()` on your record type
4. **Default** — falls back to `default_cost` (default: 1)

## `TokenBatcher` for LLM inference

For LLM workloads, `TokenBatcher` is a convenience subclass that uses token-aware parameter names:

```python
from dataclasses import dataclass
from flyte.extras import TokenBatcher

@dataclass
class Prompt:
    text: str

    def estimate_tokens(self) -> int:
        """Rough token estimate (~4 chars per token)."""
        return len(self.text) // 4 + 1

async def inference(batch: list[Prompt]) -> list[str]:
    """Run batched inference through your model."""
    texts = [p.text for p in batch]
    outputs = model.generate(texts, sampling_params)
    return [o.outputs[0].text for o in outputs]

async with TokenBatcher(
    inference_fn=inference,
    target_batch_tokens=32_000,  # token budget per batch
    max_batch_size=256,
) as batcher:
    future = await batcher.submit(Prompt(text="What is 2+2?"))
    result = await future
```

`TokenBatcher` checks the `TokenEstimator` protocol (`estimate_tokens()`) in addition to `CostEstimator` (`estimate_cost()`), making it natural to work with prompt types.

## Combining with reusable containers

`DynamicBatcher` on its own improves utilization within a single task. When combined with [reusable containers](../task-configuration/reusable-containers), it becomes significantly more powerful:

- **Amortized model loading** — the model is loaded once per container and reused across many task invocations, avoiding repeated download and initialization costs
- **Cross-task batching** — with `ReusePolicy(concurrency=N)`, multiple task invocations run concurrently on the same replica, all feeding records into the **same shared batcher**. This means the GPU always has a full queue of work.
- **Automatic scaling** — replicas scale between min and max based on demand, and each replica maintains its own model + batcher

```mermaid
flowchart TB
    D["Driver task<br/>fans out chunks"] --> |chunk 1| R1
    D --> |chunk 2| R1
    D --> |chunk 3| R2
    D --> |chunk ...| R1
    D --> |chunk N| R2

    subgraph R1 ["GPU Replica 1"]
        direction TB
        M1["Model (loaded once via alru_cache)"]
        B1["Shared TokenBatcher"]
        T1a["infer_batch call 1"] --> B1
        T1b["infer_batch call 2"] --> B1
        T1c["infer_batch call ..."] --> B1
        B1 --> M1
    end

    subgraph R2 ["GPU Replica 2"]
        direction TB
        M2["Model (loaded once via alru_cache)"]
        B2["Shared TokenBatcher"]
        T2a["infer_batch call 1"] --> B2
        T2b["infer_batch call 2"] --> B2
        T2c["infer_batch call ..."] --> B2
        B2 --> M2
    end
```

The key technique is using `@alru_cache` to create **process-level singletons** — the model and batcher are initialized on the first task invocation and reused by all subsequent invocations on that replica.

### Example: batch LLM inference with vLLM

This example loads math problems from HuggingFace's gsm8k dataset and solves them using batched vLLM inference across GPU replicas.

#### 1. Define the environment

```python
import flyte
from flyte.extras import TokenBatcher

image = (
    flyte.Image.from_debian_base()
    .with_pip_packages("vllm", "hf-transfer", "unionai-reuse")
    .with_env_vars({"HF_HUB_ENABLE_HF_TRANSFER": "1"})
)

gpu_env = flyte.TaskEnvironment(
    name="gpu_worker",
    resources=flyte.Resources(cpu=4, memory="16Gi", gpu="A10G:1"),
    image=image,
    reusable=flyte.ReusePolicy(
        replicas=2,        # 2 GPU replicas
        concurrency=10,    # 10 concurrent tasks per replica
    ),
)

driver_env = flyte.TaskEnvironment(
    name="driver",
    resources=flyte.Resources(cpu=2, memory="2Gi"),
    image=image,
    depends_on=[gpu_env],
)
```

With `replicas=2` and `concurrency=10`, up to 20 `infer_batch` calls run simultaneously across 2 GPUs, all sharing their replica's model and batcher.

#### 2. Create process-level singletons

```python
from async_lru import alru_cache
from dataclasses import dataclass

@dataclass
class Prompt:
    task_id: str
    index: int
    text: str

    def estimate_tokens(self) -> int:
        return len(self.text) // 4 + 1

@alru_cache(maxsize=1)
async def get_inference_fn():
    """Load the model once per container lifetime."""
    from vllm import LLM, SamplingParams
    llm = LLM(model="Qwen/Qwen2.5-7B-Instruct", gpu_memory_utilization=0.9, max_model_len=4096)
    params = SamplingParams(temperature=0.7, max_tokens=512)

    async def inference(batch: list[Prompt]) -> list[str]:
        texts = [p.text for p in batch]
        outputs = llm.generate(texts, params)
        return [o.outputs[0].text for o in outputs]

    return inference

@alru_cache(maxsize=1)
async def get_batcher() -> TokenBatcher[Prompt, str]:
    """Create a single batcher per container — shared across all concurrent tasks."""
    inference_fn = await get_inference_fn()
    batcher = TokenBatcher[Prompt, str](
        inference_fn=inference_fn,
        target_batch_tokens=32_000,
        max_batch_size=256,
        batch_timeout_s=0.05,
        max_queue_size=5_000,
    )
    await batcher.start()
    return batcher
```

#### 3. Define the GPU worker task

```python
import asyncio
import logging

logger = logging.getLogger(__name__)

@gpu_env.task
async def infer_batch(prompts: list[str], task_id: str) -> list[str]:
    """Submit prompts to the shared batcher and return completions."""
    batcher = await get_batcher()

    futures: list[asyncio.Future[str]] = []
    for idx, text in enumerate(prompts):
        record = Prompt(task_id=task_id, index=idx, text=text)
        future = await batcher.submit(record)
        futures.append(future)

    results = await asyncio.gather(*futures)
    logger.info(
        "[%s] completed %d records | utilization: %.1f%% | batches: %d",
        task_id,
        len(results),
        batcher.stats.utilization * 100,
        batcher.stats.total_batches,
    )
    return list(results)
```

Every concurrent `infer_batch` call on the same replica feeds into the same batcher. The batcher continuously assembles token-budgeted batches from all concurrent callers, keeping the GPU saturated.

#### 4. Define the driver task

```python
@driver_env.task
async def main(num_questions: int = 500, chunk_size: int = 50) -> dict[str, list[str]]:
    """Fetch questions and fan out across GPU replicas."""
    questions = await fetch_questions(num_questions)

    chunks = [questions[i:i + chunk_size] for i in range(0, len(questions), chunk_size)]
    task_ids = [f"chunk_{i:03d}" for i in range(len(chunks))]

    all_results = await asyncio.gather(
        *(infer_batch(chunk, tid) for chunk, tid in zip(chunks, task_ids))
    )
    return dict(zip(task_ids, all_results))
```

## Monitoring utilization

`DynamicBatcher` exposes a `stats` property with real-time metrics:

```python
stats = batcher.stats
print(f"Utilization: {stats.utilization:.1%}")         # fraction of time spent processing
print(f"Records processed: {stats.total_completed}")
print(f"Batches dispatched: {stats.total_batches}")
print(f"Avg batch size: {stats.avg_batch_size:.1f}")
print(f"Busy time: {stats.busy_time_s:.1f}s")
print(f"Idle time: {stats.idle_time_s:.1f}s")
```

| Metric | Description |
|---|---|
| `utilization` | Fraction of wall-clock time spent inside `process_fn` (0.0–1.0). Target: > 0.9. |
| `total_submitted` | Total records submitted via `submit()` |
| `total_completed` | Total records whose futures have been resolved |
| `total_batches` | Number of batches dispatched to `process_fn` |
| `avg_batch_size` | Running average records per batch |
| `avg_batch_cost` | Running average cost per batch |
| `busy_time_s` | Cumulative seconds spent inside `process_fn` |
| `idle_time_s` | Cumulative seconds the processing loop waited for batches |

If utilization is low, consider:
- **Increasing concurrency** — more concurrent producers means the batcher has more records to assemble into batches
- **Reducing `batch_timeout_s`** — dispatch partial batches faster instead of waiting
- **Increasing `max_queue_size`** — allow more records to be buffered ahead of the GPU
- **Adding more data streams** — ensure the GPU always has work queued up


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/configure-apps ===

# Configure apps

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

`[[AppEnvironment]]`s allows you to configure the environment in which your app runs, including the container image, compute resources, secrets, domains, scaling behavior, and more.

Similar to `[[TaskEnvironment]]`, configuration can be set when creating the `[[AppEnvironment]]` object. Unlike tasks, apps are long-running services, so they have additional configuration options specific to web services:

- `port`: What port the app listens on
- `command` and `args`: How to start the app
- `scaling`: Autoscaling configuration for handling variable load
- `domain`: Custom domains and subdomains for your app
- `requires_auth`: Whether the app requires authentication to access
- `depends_on`: Other app or task environments that the app depends on

## Hello World example

Here's a complete example of deploying a simple Streamlit "hello world" app with a custom subdomain.

There are two ways to build apps in Flyte:
1. Defining `AppEnvironment(.., args=[...])` to run the app with the underlying `fserve` command.
2. Defining `@app_env.server` to run the app with a custom server function.

### Using fserve args

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

import flyte
import flyte.app

# {{docs-fragment image}}
image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages("streamlit==1.41.1")
# {{/docs-fragment image}}

# {{docs-fragment app-env}}
app_env = flyte.app.AppEnvironment(
    name="hello-world-app",
    image=image,
    args=["streamlit", "hello", "--server.port", "8080"],
    port=8080,
    resources=flyte.Resources(cpu="1", memory="1Gi"),
    requires_auth=False,
    domain=flyte.app.Domain(subdomain="hello"),
)
# {{/docs-fragment app-env}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    flyte.init_from_config()

    # Deploy the app
    app = flyte.serve(app_env)
    print(f"App served at: {app.url}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/configure-apps/hello-world-app.py*

This example demonstrates:

- Creating a custom Docker image with Streamlit
- Setting the `args` to run the Streamlit hello app, which uses the underlying `fserve` command to run the app.
- Configuring the port
- Setting resource limits
- Disabling authentication (for public access)
- Using a custom subdomain

### Using @app_env.server

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

import flyte
import flyte.app

# {{docs-fragment image}}
image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages("streamlit==1.41.1")
# {{/docs-fragment image}}

# {{docs-fragment app-env}}
app_env = flyte.app.AppEnvironment(
    name="hello-world-app-server",
    image=image,
    port=8080,
    resources=flyte.Resources(cpu="1", memory="1Gi"),
    requires_auth=False,
    domain=flyte.app.Domain(subdomain="hello-server"),
)

@app_env.server
def server():
    import subprocess
    subprocess.run(["streamlit", "hello", "--server.port", "8080"], check=False)
# {{/docs-fragment app-env}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    flyte.init_from_config()

    # Deploy the app
    app = flyte.serve(app_env)
    print(f"App served at: {app.url}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/configure-apps/hello-world-app-server.py*

This example demonstrates:

- Creating a custom Docker image with Streamlit
- Using the `@app_env.server` decorator to define a server function that runs the Streamlit hello app.
- Configuring the port
- Setting resource limits
- Disabling authentication (for public access)
- Using a custom subdomain

Once deployed, your app will be accessible at the generated URL or your custom subdomain.

## Differences from TaskEnvironment

While `AppEnvironment` inherits from `Environment` (the same base class as `TaskEnvironment`), it has several app-specific parameters:

| Parameter | AppEnvironment | TaskEnvironment | Description |
|-----------|----------------|-----------------|-------------|
| `type` | ✅ | ❌ | Type of app (e.g., "FastAPI", "Streamlit") |
| `port` | ✅ | ❌ | Port the app listens on |
| `args` | ✅ | ❌ | Arguments to pass to the app |
| `command` | ✅ | ❌ | Command to run the app |
| `requires_auth` | ✅ | ❌ | Whether app requires authentication |
| `scaling` | ✅ | ❌ | Autoscaling configuration |
| `domain` | ✅ | ❌ | Custom domain/subdomain |
| `links` | ✅ | ❌ | Links to include in the App UI page |
| `include` | ✅ | ❌ | Files to include in app |
| `parameters` | ✅ | ❌ | Parameters to pass to app |
| `cluster_pool` | ✅ | ❌ | Cluster pool for deployment |

Parameters like `image`, `resources`, `secrets`, `env_vars`, and `depends_on` are shared between both environment types. See the [task configuration](../task-configuration/_index) docs for details on these shared parameters.

## Configuration topics

Learn more about configuring apps:

- **Configure apps > App environment settings**: Images, resources, secrets, and app-specific settings like `type`, `port`, `args`, `requires_auth`
- **Configure apps > App environment settings > App startup**: Understanding the difference between `args` and `command`
- **Configure apps > Including additional files**: How to include additional files needed by your app
- **Configure apps > Passing parameters into app environments**: Pass parameters to your app at deployment time
- **Configure apps > App environment settings > `scaling`**: Configure scaling up and down based on traffic with idle TTL
- **Configure apps > Apps depending on other environments**: Use `depends_on` to deploy dependent apps together

## Subpages
- **Configure apps > App environment settings**
- **Configure apps > Including additional files**
- **Configure apps > Passing parameters into app environments**
- **Configure apps > /// script**
- **Configure apps > Apps depending on other environments**


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/configure-apps/app-environment-settings ===

# App environment settings

`[[AppEnvironment]]`s control how your apps run in Flyte, including images, resources, secrets, startup behavior, and autoscaling.

## Shared environment settings

`[[AppEnvironment]]`s share many configuration options with `[[TaskEnvironment]]`s:

- **Images**: See [Container images](../task-configuration/container-images/) for details on creating and using container images
- **Resources**: See [Resources](../task-configuration/resources/) for CPU, memory, GPU, and storage configuration
- **Secrets**: See [Secrets](../task-configuration/secrets/) for injecting secrets into your app
- **Environment variables**: Set via the `env_vars` parameter (same as tasks)
- **Cluster pools**: Specify via the `cluster_pool` parameter

## App-specific environment settings

For complete parameter documentation and type signatures, see the [`AppEnvironment` API reference](../../api-reference/flyte-sdk/packages/flyte.app/appenvironment).

### `type`

The `type` parameter is an optional string that identifies what kind of app this is. It's used for organizational purposes and may be used by the UI or tooling to display or filter apps.

```python
app_env = flyte.app.AppEnvironment(
    name="my-fastapi-app",
    type="FastAPI",
    # ...
)
```

When using specialized app environments like `FastAPIAppEnvironment`, the type is automatically set. For custom apps, you can set it to any string value.

### `port`

The `port` parameter specifies which port your app listens on. It can be an integer or a `Port` object.

```python
# Using an integer (simple case)
app_env = flyte.app.AppEnvironment(name="my-app", port=8080, ...)

# Using a Port object (more control)
app_env = flyte.app.AppEnvironment(
    name="my-app",
    port=flyte.app.Port(port=8080),
    # ...
)
```

The default port is `8080`. Your app should listen on this port (or the port you specify).

> [!NOTE]
> Ports 8012, 8022, 8112, 9090, and 9091 are reserved and cannot be used for apps.

### `args`

The `args` parameter specifies arguments to pass to your app's command. This is typically used when you need to pass additional arguments to the command specified in `command`, or when using the default command behavior.

```python
app_env = flyte.app.AppEnvironment(
    name="streamlit-app",
    args="streamlit run main.py --server.port 8080",
    port=8080,
    # ...
)
```

`args` can be either a string (which will be shell-split) or a list of strings:

```python
# String form (will be shell-split)
args="--option1 value1 --option2 value2"

# List form (more explicit)
args=["--option1", "value1", "--option2", "value2"]
```

#### Environment variable substitution

Environment variables are automatically substituted in `args` strings when they start with the `$` character. This works for both:

- Values from `env_vars`
- Secrets that are specified as environment variables (via `as_env_var` in `flyte.Secret`)

The `$VARIABLE_NAME` syntax will be replaced with the actual environment variable value at runtime:

```python
# Using env_vars
app_env = flyte.app.AppEnvironment(
    name="my-app",
    env_vars={"API_KEY": "secret-key-123"},
    args="--api-key $API_KEY",  # $API_KEY will be replaced with "secret-key-123"
    # ...
)

# Using secrets
app_env = flyte.app.AppEnvironment(
    name="my-app",
    secrets=flyte.Secret(key="AUTH_SECRET", as_env_var="AUTH_SECRET"),
    args=["--api-key", "$AUTH_SECRET"],  # $AUTH_SECRET will be replaced with the secret value
    # ...
)
```

This is particularly useful for passing API keys or other sensitive values to command-line arguments without hardcoding them in your code. The substitution happens at runtime, ensuring secrets are never exposed in your code or configuration files.

> [!TIP]
> For most `AppEnvironment`s, use `args` instead of `command` to specify the app startup command
> in the container. This is because `args` will use the `fserve` command to run the app, which
> unlocks features like local code bundling and file/directory mounting via parameter injection.

### `command`

The `command` parameter specifies the full command to run your app. If not specified, Flyte will use a default command that runs your app via `fserve`, which is the Python executable provided
by `flyte` to run apps.

```python
# Explicit command
app_env = flyte.app.AppEnvironment(
    name="streamlit-hello",
    command="streamlit hello --server.port 8080",
    port=8080,
    # ...
)

# Using default command (recommended for most cases)
# When command is None, Flyte generates a command based on your app configuration
app_env = flyte.app.AppEnvironment(name="my-app", ...)  # command=None by default
```

> [!TIP]
> For most apps, especially when using specialized app environments like `FastAPIAppEnvironment`, you don't need to specify `command` as it's automatically configured. Use `command` when you need
> to specify the raw container command, e.g. when running a non-Python app or when you have all
> of the dependencies and data used by the app available in the container.

### `requires_auth`

The `requires_auth` parameter controls whether the app requires authentication to access. By default, apps require authentication (`requires_auth=True`).

```python
# Public app (no authentication required)
app_env = flyte.app.AppEnvironment(
    name="public-dashboard",
    requires_auth=False,
    # ...
)

# Private app (authentication required - default)
app_env = flyte.app.AppEnvironment(
    name="internal-api",
    requires_auth=True,
    # ...
)  # Default
```

When `requires_auth=True`, users must authenticate with Flyte to access the app. When `requires_auth=False`, the app is publicly accessible (though it may still require API keys or other app-level authentication).

### `domain`

The `domain` parameter specifies a custom domain or subdomain for your app. Use `flyte.app.Domain` to configure a subdomain or custom domain.

```python
app_env = flyte.app.AppEnvironment(
    name="my-app",
    domain=flyte.app.Domain(subdomain="myapp"),
    # ...
)
```

### `links`

The `links` parameter adds links to the App UI page. Use `flyte.app.Link` objects to specify relative or absolute links with titles.

```python
app_env = flyte.app.AppEnvironment(
    name="my-app",
    links=[
        flyte.app.Link(path="/docs", title="API Documentation", is_relative=True),
        flyte.app.Link(path="/health", title="Health Check", is_relative=True),
        flyte.app.Link(path="https://www.example.com", title="External link", is_relative=False),
    ],
    # ...
)
```

### `include`

The `include` parameter specifies files and directories to include in the app bundle. Use glob patterns or explicit paths to include code files needed by your app.

```python
app_env = flyte.app.AppEnvironment(
    name="my-app",
    include=["*.py", "models/", "utils/", "requirements.txt"],
    # ...
)
```

> [!NOTE]
> Learn more about including additional files in your app deployment [here](./including-additional-files).

### `parameters`

The `parameters` parameter passes parameters to your app at deployment time. Parameters can be primitive values, files, directories, or delayed values like `RunOutput` or `AppEndpoint`.

```python
app_env = flyte.app.AppEnvironment(
    name="my-app",
    parameters=[
        flyte.app.Parameter(name="config", value="foo", env_var="BAR"),
        flyte.app.Parameter(name="model", value=flyte.io.File(path="s3://bucket/model.pkl"), mount="/mnt/model"),
        flyte.app.Parameter(name="data", value=flyte.io.File(path="s3://bucket/data.pkl"), mount="/mnt/data"),
    ],
    # ...
)
```

> [!NOTE]
> Learn more about passing parameters to your app at deployment time [here](./passing-parameters).

### `scaling`

The `scaling` parameter configures autoscaling behavior for your app. Use `flyte.app.Scaling` to set replica ranges and idle TTL.

```python
app_env = flyte.app.AppEnvironment(
    name="my-app",
    scaling=flyte.app.Scaling(
        replicas=(1, 5),
        scaledown_after=300,  # Scale down after 5 minutes of idle time
    ),
    # ...
)
```

> [!NOTE]
> Learn more about autoscaling apps [here](./auto-scaling-apps).

### `depends_on`

The `depends_on` parameter specifies environment dependencies. When you deploy an app, all dependencies are deployed first.

```python
backend_env = flyte.app.AppEnvironment(name="backend-api", ...)

frontend_env = flyte.app.AppEnvironment(
    name="frontend-app",
    depends_on=[backend_env],  # backend-api will be deployed first
    # ...
)
```

> [!NOTE]
> Learn more about app environment dependencies [her e](./apps-depending-on-environments).

## App startup

There are two ways to start up an app in Flyte:
1. With a server function using `@app_env.server`
2. As a container command using `command` or `args`

### Server decorator via `@app_env.server`

The server function is a Python function that runs the app. It is defined using the `@app_env.server` decorator.

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "fastapi",
#    "uvicorn",
#    "flyte>=2.0.0b52",
# ]
# ///

import fastapi
import uvicorn

import flyte
from flyte.app.extras import FastAPIAppEnvironment

# {{docs-fragment fastapi-app}}
app = fastapi.FastAPI()

env = FastAPIAppEnvironment(
    name="configure-fastapi-example",
    app=app,
    image=flyte.Image.from_uv_script(__file__, name="configure-fastapi-example"),
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
    port=8080,
)

@env.server
def server():
    print("Starting server...")
    uvicorn.run(app, port=8080)

@app.get("/")
async def root() -> dict:
    return {"message": "Hello from FastAPI!"}
# {{/docs-fragment fastapi-app}}

# {{docs-fragment on-startup-decorator}}
state = {}

@env.on_startup
async def app_startup():
    print("App started up")
    state["data"] = ["Here's", "some", "data"]
# {{/docs-fragment on-startup-decorator}}

# {{docs-fragment on-shutdown-decorator}}
@env.on_shutdown
async def app_shutdown():
    print("App shut down")
    state.clear()  # clears the data
# {{/docs-fragment on-shutdown-decorator}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    import logging

    flyte.init_from_config(log_level=logging.DEBUG)
    deployed_app = flyte.serve(env)
    print(f"App served at: {deployed_app.url}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/configure-apps/fastapi-server-example.py*

The `@app_env.server` decorator allows you to define a synchronous or asynchronous function that runs the app, either
with a server start command like `uvicorn.run`, [`HTTPServer.serve_forever`](https://docs.python.org/3/library/http.server.html), etc.

> [!NOTE]
> Generally the `[[FastAPIAppEnvironment]]` handles serving automatically under the hood,
> the example above just shows how the `@app_env.server` decorator can be used to define a server function
> that runs the app.

#### Startup hook

The server function is called after the app is started up, and before the app is shut down. It is defined using the `@app_env.on_startup` decorator. This is useful if you need to load any state or external connections needed to run the
app before it starts.

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "fastapi",
#    "uvicorn",
#    "flyte>=2.0.0b52",
# ]
# ///

import fastapi
import uvicorn

import flyte
from flyte.app.extras import FastAPIAppEnvironment

# {{docs-fragment fastapi-app}}
app = fastapi.FastAPI()

env = FastAPIAppEnvironment(
    name="configure-fastapi-example",
    app=app,
    image=flyte.Image.from_uv_script(__file__, name="configure-fastapi-example"),
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
    port=8080,
)

@env.server
def server():
    print("Starting server...")
    uvicorn.run(app, port=8080)

@app.get("/")
async def root() -> dict:
    return {"message": "Hello from FastAPI!"}
# {{/docs-fragment fastapi-app}}

# {{docs-fragment on-startup-decorator}}
state = {}

@env.on_startup
async def app_startup():
    print("App started up")
    state["data"] = ["Here's", "some", "data"]
# {{/docs-fragment on-startup-decorator}}

# {{docs-fragment on-shutdown-decorator}}
@env.on_shutdown
async def app_shutdown():
    print("App shut down")
    state.clear()  # clears the data
# {{/docs-fragment on-shutdown-decorator}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    import logging

    flyte.init_from_config(log_level=logging.DEBUG)
    deployed_app = flyte.serve(env)
    print(f"App served at: {deployed_app.url}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/configure-apps/fastapi-server-example.py*

#### Shutdown hook

The server function is called before the app instance shuts down during scale down. It is defined using the
`@app_env.on_shutdown` decorator. This is useful if you need to clean up any state or external connections in the
container running the app.

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "fastapi",
#    "uvicorn",
#    "flyte>=2.0.0b52",
# ]
# ///

import fastapi
import uvicorn

import flyte
from flyte.app.extras import FastAPIAppEnvironment

# {{docs-fragment fastapi-app}}
app = fastapi.FastAPI()

env = FastAPIAppEnvironment(
    name="configure-fastapi-example",
    app=app,
    image=flyte.Image.from_uv_script(__file__, name="configure-fastapi-example"),
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
    port=8080,
)

@env.server
def server():
    print("Starting server...")
    uvicorn.run(app, port=8080)

@app.get("/")
async def root() -> dict:
    return {"message": "Hello from FastAPI!"}
# {{/docs-fragment fastapi-app}}

# {{docs-fragment on-startup-decorator}}
state = {}

@env.on_startup
async def app_startup():
    print("App started up")
    state["data"] = ["Here's", "some", "data"]
# {{/docs-fragment on-startup-decorator}}

# {{docs-fragment on-shutdown-decorator}}
@env.on_shutdown
async def app_shutdown():
    print("App shut down")
    state.clear()  # clears the data
# {{/docs-fragment on-shutdown-decorator}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    import logging

    flyte.init_from_config(log_level=logging.DEBUG)
    deployed_app = flyte.serve(env)
    print(f"App served at: {deployed_app.url}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/configure-apps/fastapi-server-example.py*

### Container command via `command` vs `args`

The difference between `args` and `command` is crucial for properly configuring how your app starts.

- **`command`**: The full command to run your app, for example, `"streamlit hello --server.port 8080"`. For most use
  cases, you don't need to specify `command` as it's automatically configured, and uses the `fserve` executable to
  run the app. `fserve` does additional setup for you, like setting up the code bundle and loading [parameters](./passing-parameters) if provided, so it's highly recommended to use the default command.
- **`args`**: Arguments to pass to your app's command (used with the default Flyte command or your custom command). The
  `fserve` executable takes in additional arguments, which you can specify as the arguments needed to run your app, e.g.
  `uvicorn run main.py --server.port 8080`.

#### Default startup behavior

When you don't specify a `command`, Flyte generates a default command that uses `fserve` to run your app. This default command handles:

- Setting up the code bundle
- Configuring the version
- Setting up project/domain context
- Injecting parameters if provided

The default command looks like:

```bash
fserve --version <version> --project <project> --domain <domain> -- <args>
```

So if you specify `args`, they'll be appended after the `--` separator.

#### Using args with the default command

When you use `args` without specifying `command`, the args are passed to the default Flyte command:

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "fastapi",
#    "flyte>=2.0.0b52",
# ]
# ///

import flyte
import flyte.app

# {{docs-fragment args-with-default-command}}
# Using args with default command
app_env = flyte.app.AppEnvironment(
    name="streamlit-app",
    args="streamlit run main.py --server.port 8080",
    port=8080,
    include=["main.py"],
    # command is None, so default Flyte command is used
)
# {{/docs-fragment args-with-default-command}}

# {{docs-fragment explicit-command}}
# Using explicit command
app_env2 = flyte.app.AppEnvironment(
    name="streamlit-hello",
    command="streamlit hello --server.port 8080",
    port=8080,
    # No args needed since command includes everything
)
# {{/docs-fragment explicit-command}}

# {{docs-fragment command-with-args}}
# Using command with args
app_env3 = flyte.app.AppEnvironment(
    name="custom-app",
    command="python -m myapp",
    args="--option1 value1 --option2 value2",
    # This runs: python -m myapp --option1 value1 --option2 value2
)
# {{/docs-fragment command-with-args}}

# {{docs-fragment fastapi-auto-command}}
# FastAPIAppEnvironment automatically sets command
from flyte.app.extras import FastAPIAppEnvironment
from fastapi import FastAPI

app = FastAPI()

env = FastAPIAppEnvironment(
    name="my-api",
    app=app,
    # You typically don't need to specify command or args, since the
    # FastAPIAppEnvironment automatically uses the bundled code to serve the
    # app via uvicorn.
)
# {{/docs-fragment fastapi-auto-command}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/configure-apps/app-startup-examples.py*

This effectively runs:

```bash
fserve --version ... --project ... --domain ... -- streamlit run main.py --server.port 8080
```

#### Using an explicit command

When you specify a `command`, it completely replaces the default command:

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "fastapi",
#    "flyte>=2.0.0b52",
# ]
# ///

import flyte
import flyte.app

# {{docs-fragment args-with-default-command}}
# Using args with default command
app_env = flyte.app.AppEnvironment(
    name="streamlit-app",
    args="streamlit run main.py --server.port 8080",
    port=8080,
    include=["main.py"],
    # command is None, so default Flyte command is used
)
# {{/docs-fragment args-with-default-command}}

# {{docs-fragment explicit-command}}
# Using explicit command
app_env2 = flyte.app.AppEnvironment(
    name="streamlit-hello",
    command="streamlit hello --server.port 8080",
    port=8080,
    # No args needed since command includes everything
)
# {{/docs-fragment explicit-command}}

# {{docs-fragment command-with-args}}
# Using command with args
app_env3 = flyte.app.AppEnvironment(
    name="custom-app",
    command="python -m myapp",
    args="--option1 value1 --option2 value2",
    # This runs: python -m myapp --option1 value1 --option2 value2
)
# {{/docs-fragment command-with-args}}

# {{docs-fragment fastapi-auto-command}}
# FastAPIAppEnvironment automatically sets command
from flyte.app.extras import FastAPIAppEnvironment
from fastapi import FastAPI

app = FastAPI()

env = FastAPIAppEnvironment(
    name="my-api",
    app=app,
    # You typically don't need to specify command or args, since the
    # FastAPIAppEnvironment automatically uses the bundled code to serve the
    # app via uvicorn.
)
# {{/docs-fragment fastapi-auto-command}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/configure-apps/app-startup-examples.py*

This runs exactly:

```bash
streamlit hello --server.port 8080
```

#### Using a command with args

You can combine both, though this is less common:

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "fastapi",
#    "flyte>=2.0.0b52",
# ]
# ///

import flyte
import flyte.app

# {{docs-fragment args-with-default-command}}
# Using args with default command
app_env = flyte.app.AppEnvironment(
    name="streamlit-app",
    args="streamlit run main.py --server.port 8080",
    port=8080,
    include=["main.py"],
    # command is None, so default Flyte command is used
)
# {{/docs-fragment args-with-default-command}}

# {{docs-fragment explicit-command}}
# Using explicit command
app_env2 = flyte.app.AppEnvironment(
    name="streamlit-hello",
    command="streamlit hello --server.port 8080",
    port=8080,
    # No args needed since command includes everything
)
# {{/docs-fragment explicit-command}}

# {{docs-fragment command-with-args}}
# Using command with args
app_env3 = flyte.app.AppEnvironment(
    name="custom-app",
    command="python -m myapp",
    args="--option1 value1 --option2 value2",
    # This runs: python -m myapp --option1 value1 --option2 value2
)
# {{/docs-fragment command-with-args}}

# {{docs-fragment fastapi-auto-command}}
# FastAPIAppEnvironment automatically sets command
from flyte.app.extras import FastAPIAppEnvironment
from fastapi import FastAPI

app = FastAPI()

env = FastAPIAppEnvironment(
    name="my-api",
    app=app,
    # You typically don't need to specify command or args, since the
    # FastAPIAppEnvironment automatically uses the bundled code to serve the
    # app via uvicorn.
)
# {{/docs-fragment fastapi-auto-command}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/configure-apps/app-startup-examples.py*

#### FastAPIAppEnvironment example

When using `FastAPIAppEnvironment`, the command is automatically configured to run uvicorn:

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "fastapi",
#    "flyte>=2.0.0b52",
# ]
# ///

import flyte
import flyte.app

# {{docs-fragment args-with-default-command}}
# Using args with default command
app_env = flyte.app.AppEnvironment(
    name="streamlit-app",
    args="streamlit run main.py --server.port 8080",
    port=8080,
    include=["main.py"],
    # command is None, so default Flyte command is used
)
# {{/docs-fragment args-with-default-command}}

# {{docs-fragment explicit-command}}
# Using explicit command
app_env2 = flyte.app.AppEnvironment(
    name="streamlit-hello",
    command="streamlit hello --server.port 8080",
    port=8080,
    # No args needed since command includes everything
)
# {{/docs-fragment explicit-command}}

# {{docs-fragment command-with-args}}
# Using command with args
app_env3 = flyte.app.AppEnvironment(
    name="custom-app",
    command="python -m myapp",
    args="--option1 value1 --option2 value2",
    # This runs: python -m myapp --option1 value1 --option2 value2
)
# {{/docs-fragment command-with-args}}

# {{docs-fragment fastapi-auto-command}}
# FastAPIAppEnvironment automatically sets command
from flyte.app.extras import FastAPIAppEnvironment
from fastapi import FastAPI

app = FastAPI()

env = FastAPIAppEnvironment(
    name="my-api",
    app=app,
    # You typically don't need to specify command or args, since the
    # FastAPIAppEnvironment automatically uses the bundled code to serve the
    # app via uvicorn.
)
# {{/docs-fragment fastapi-auto-command}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/configure-apps/app-startup-examples.py*

The `FastAPIAppEnvironment` automatically:

1. Detects the module and variable name of your FastAPI app
2. Uses an internal server function to start the app via `uvicorn.run`.
3. Handles all the startup configuration for you

## Shared settings

For more details on shared settings like images, resources, and secrets, refer to the [task configuration](../task-configuration/_index) documentation.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/configure-apps/including-additional-files ===

# Including additional files

When your app needs additional files beyond the main script (like utility modules, configuration files, or data files), you can use the `include` parameter to specify which files to bundle with your app.

## How include works

The `include` parameter takes a list of file paths (relative to the directory containing your app definition). These files are bundled together and made available in the app container at runtime.

```python
include=["main.py", "utils.py", "config.yaml"]
```

## When to use include

Use `include` when:

- Your app spans multiple Python files (modules)
- You have configuration files that your app needs
- You have data files or templates your app uses
- You want to ensure specific files are available in the container

> [!NOTE]
> If you're using specialized app environments like `FastAPIAppEnvironment`, Flyte automatically detects and includes the necessary files, so you may not need to specify `include` explicitly.

## Examples

### Multi-file Streamlit app

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""A custom Streamlit app with multiple files."""

import pathlib
import flyte
import flyte.app

# {{docs-fragment app-env}}
image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
    "streamlit==1.41.1",
    "pandas==2.2.3",
    "numpy==2.2.3",
)

app_env = flyte.app.AppEnvironment(
    name="streamlit-multi-file-app",
    image=image,
    args="streamlit run main.py --server.port 8080",
    port=8080,
    include=["main.py", "utils.py"],  # Include your app files
    resources=flyte.Resources(cpu="1", memory="1Gi"),
    requires_auth=False,
)
# {{/docs-fragment app-env}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    app = flyte.deploy(app_env)
    print(f"Deployed app: {app[0].summary_repr()}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/streamlit/multi_file_streamlit.py*

In this example:
- `main.py` is your main Streamlit app file
- `utils.py` contains helper functions used by `main.py`
- Both files are included in the app bundle

### Multi-file FastAPI app

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
# ]
# ///

"""Multi-file FastAPI app example."""

from fastapi import FastAPI
from module import function  # Import from another file
import pathlib

import flyte
from flyte.app.extras import FastAPIAppEnvironment

# {{docs-fragment app-definition}}
app = FastAPI(title="Multi-file FastAPI Demo")

app_env = FastAPIAppEnvironment(
    name="fastapi-multi-file",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
    ),
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
    # FastAPIAppEnvironment automatically includes necessary files
    # But you can also specify explicitly:
    # include=["app.py", "module.py"],
)
# {{/docs-fragment app-definition}}

# {{docs-fragment endpoint}}
@app.get("/")
async def root():
    return function()  # Uses function from module.py
# {{/docs-fragment endpoint}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    app_deployment = flyte.deploy(app_env)
    print(f"Deployed: {app_deployment[0].summary_repr()}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/multi_file/app.py*

### App with configuration files

```python
include=["app.py", "config.yaml", "templates/"]
```

## File discovery

When using specialized app environments like `FastAPIAppEnvironment`, Flyte uses code introspection to automatically discover and include the necessary files. This means you often don't need to manually specify `include`.

However, if you have files that aren't automatically detected (like configuration files, data files, or templates), you should explicitly list them in `include`.

## Path resolution

Files in `include` are resolved relative to the directory containing your app definition file. For example:

```
project/
├── apps/
│   ├── app.py          # Your app definition
│   ├── utils.py        # Included file
│   └── config.yaml     # Included file
```

In `app.py`:

```python
include=["utils.py", "config.yaml"]  # Relative to apps/ directory
```

## Best practices

1. **Only include what you need**: Don't include unnecessary files as it increases bundle size
2. **Use relative paths**: Always use paths relative to your app definition file
3. **Include directories**: You can include entire directories, but be mindful of size
4. **Test locally**: Verify your includes work by testing locally before deploying
5. **Check automatic discovery**: Specialized app environments may already include files automatically

## Limitations

- Large files or directories can slow down deployment
- Binary files are supported but consider using data storage (S3, etc.) for very large files
- The bundle size is limited by your Flyte cluster configuration


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/configure-apps/passing-parameters ===

# Passing parameters into app environments

`[[AppEnvironment]]`s support various parameter types that can be passed at deployment time. This includes primitive values, files, directories, and delayed values like `RunOutput` and `AppEndpoint`.

## Parameter types overview

There are several parameter types:

- **Primitive values**: Strings, numbers, booleans
- **Files**: `flyte.io.File` objects
- **Directories**: `flyte.io.Dir` objects
- **Delayed values**: `RunOutput` (from task runs) or `AppEndpoint` (inject endpoint urls of other apps)

## Basic parameter types

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
#    "scikit-learn",
#    "joblib",
# ]
# ///

"""Examples showing different ways to pass parameters into apps."""

import flyte
import flyte.app
import flyte.io

# {{docs-fragment basic-parameter-types}}
# String parameters
app_env = flyte.app.AppEnvironment(
    name="configurable-app",
    parameters=[
        flyte.app.Parameter(name="environment", value="production"),
        flyte.app.Parameter(name="log_level", value="INFO"),
    ],
    # ...
)

# File parameters
app_env2 = flyte.app.AppEnvironment(
    name="app-with-model",
    parameters=[
        flyte.app.Parameter(
            name="model_file",
            value=flyte.io.File("s3://bucket/models/model.pkl"),
            mount="/app/models",
        ),
    ],
    # ...
)

# Directory parameters
app_env3 = flyte.app.AppEnvironment(
    name="app-with-data",
    parameters=[
        flyte.app.Parameter(
            name="data_dir",
            value=flyte.io.Dir("s3://bucket/data/"),
            mount="/app/data",
        ),
    ],
    # ...
)
# {{/docs-fragment basic-parameter-types}}

# {{docs-fragment runoutput-example}}
# Delayed parameters with RunOutput
env = flyte.TaskEnvironment(name="training-env")

@env.task
async def train_model() -> flyte.io.File:
    # ... training logic ...
    return await flyte.io.File.from_local("/tmp/trained-model.pkl")

# Use the task output as an app parameter
app_env4 = flyte.app.AppEnvironment(
    name="serving-app",
    parameters=[
        flyte.app.Parameter(
            name="model",
            value=flyte.app.RunOutput(type="file", run_name="training_run", task_name="train_model"),
            mount="/app/model",
        ),
    ],
    # ...
)
# {{/docs-fragment runoutput-example}}

# {{docs-fragment appendpoint-example}}
# Delayed parameters with AppEndpoint
app1_env = flyte.app.AppEnvironment(name="backend-api")

app2_env = flyte.app.AppEnvironment(
    name="frontend-app",
    parameters=[
        flyte.app.Parameter(
            name="backend_url",
            value=flyte.app.AppEndpoint(app_name="backend-api"),
            env_var="BACKEND_URL",  # app1_env's endpoint will be available as an environment variable
        ),
    ],
    # ...
)
# {{/docs-fragment appendpoint-example}}

# {{docs-fragment runoutput-serving-example}}
# Example: Using RunOutput for model serving
import joblib
from sklearn.ensemble import RandomForestClassifier
from flyte.app.extras import FastAPIAppEnvironment
from fastapi import FastAPI

# Training task
training_env = flyte.TaskEnvironment(name="training-env")

@training_env.task
async def train_model_task() -> flyte.io.File:
    """Train a model and return it."""

    model = RandomForestClassifier()

    # ... training logic ...

    path = "./trained-model.pkl"
    joblib.dump(model, path)
    return await flyte.io.File.from_local(path)

# Serving app that uses the trained model
app = FastAPI()
serving_env = FastAPIAppEnvironment(
    name="model-serving-app",
    app=app,
    parameters=[
        flyte.app.Parameter(
            name="model",
            value=flyte.app.RunOutput(
                type="file",
                task_name="training-env.train_model_task"
            ),
            mount="/app/model",
            env_var="MODEL_PATH",
        ),
    ],
)
# {{/docs-fragment runoutput-serving-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/passing-parameters-examples.py*

## Delayed values

Delayed values are parameters whose actual values are materialized at deployment time.

### RunOutput

Use `RunOutput` to pass outputs from task runs as app parameters:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
#    "scikit-learn",
#    "joblib",
# ]
# ///

"""Examples showing different ways to pass parameters into apps."""

import flyte
import flyte.app
import flyte.io

# {{docs-fragment basic-parameter-types}}
# String parameters
app_env = flyte.app.AppEnvironment(
    name="configurable-app",
    parameters=[
        flyte.app.Parameter(name="environment", value="production"),
        flyte.app.Parameter(name="log_level", value="INFO"),
    ],
    # ...
)

# File parameters
app_env2 = flyte.app.AppEnvironment(
    name="app-with-model",
    parameters=[
        flyte.app.Parameter(
            name="model_file",
            value=flyte.io.File("s3://bucket/models/model.pkl"),
            mount="/app/models",
        ),
    ],
    # ...
)

# Directory parameters
app_env3 = flyte.app.AppEnvironment(
    name="app-with-data",
    parameters=[
        flyte.app.Parameter(
            name="data_dir",
            value=flyte.io.Dir("s3://bucket/data/"),
            mount="/app/data",
        ),
    ],
    # ...
)
# {{/docs-fragment basic-parameter-types}}

# {{docs-fragment runoutput-example}}
# Delayed parameters with RunOutput
env = flyte.TaskEnvironment(name="training-env")

@env.task
async def train_model() -> flyte.io.File:
    # ... training logic ...
    return await flyte.io.File.from_local("/tmp/trained-model.pkl")

# Use the task output as an app parameter
app_env4 = flyte.app.AppEnvironment(
    name="serving-app",
    parameters=[
        flyte.app.Parameter(
            name="model",
            value=flyte.app.RunOutput(type="file", run_name="training_run", task_name="train_model"),
            mount="/app/model",
        ),
    ],
    # ...
)
# {{/docs-fragment runoutput-example}}

# {{docs-fragment appendpoint-example}}
# Delayed parameters with AppEndpoint
app1_env = flyte.app.AppEnvironment(name="backend-api")

app2_env = flyte.app.AppEnvironment(
    name="frontend-app",
    parameters=[
        flyte.app.Parameter(
            name="backend_url",
            value=flyte.app.AppEndpoint(app_name="backend-api"),
            env_var="BACKEND_URL",  # app1_env's endpoint will be available as an environment variable
        ),
    ],
    # ...
)
# {{/docs-fragment appendpoint-example}}

# {{docs-fragment runoutput-serving-example}}
# Example: Using RunOutput for model serving
import joblib
from sklearn.ensemble import RandomForestClassifier
from flyte.app.extras import FastAPIAppEnvironment
from fastapi import FastAPI

# Training task
training_env = flyte.TaskEnvironment(name="training-env")

@training_env.task
async def train_model_task() -> flyte.io.File:
    """Train a model and return it."""

    model = RandomForestClassifier()

    # ... training logic ...

    path = "./trained-model.pkl"
    joblib.dump(model, path)
    return await flyte.io.File.from_local(path)

# Serving app that uses the trained model
app = FastAPI()
serving_env = FastAPIAppEnvironment(
    name="model-serving-app",
    app=app,
    parameters=[
        flyte.app.Parameter(
            name="model",
            value=flyte.app.RunOutput(
                type="file",
                task_name="training-env.train_model_task"
            ),
            mount="/app/model",
            env_var="MODEL_PATH",
        ),
    ],
)
# {{/docs-fragment runoutput-serving-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/passing-parameters-examples.py*

The `type` argument is required and must be one of `string`, `file`, or `directory`.
When the app is deployed, it will make the remote calls needed to figure out the
actual value of the parameter.

### AppEndpoint

Use `AppEndpoint` to pass endpoints from other apps:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
#    "scikit-learn",
#    "joblib",
# ]
# ///

"""Examples showing different ways to pass parameters into apps."""

import flyte
import flyte.app
import flyte.io

# {{docs-fragment basic-parameter-types}}
# String parameters
app_env = flyte.app.AppEnvironment(
    name="configurable-app",
    parameters=[
        flyte.app.Parameter(name="environment", value="production"),
        flyte.app.Parameter(name="log_level", value="INFO"),
    ],
    # ...
)

# File parameters
app_env2 = flyte.app.AppEnvironment(
    name="app-with-model",
    parameters=[
        flyte.app.Parameter(
            name="model_file",
            value=flyte.io.File("s3://bucket/models/model.pkl"),
            mount="/app/models",
        ),
    ],
    # ...
)

# Directory parameters
app_env3 = flyte.app.AppEnvironment(
    name="app-with-data",
    parameters=[
        flyte.app.Parameter(
            name="data_dir",
            value=flyte.io.Dir("s3://bucket/data/"),
            mount="/app/data",
        ),
    ],
    # ...
)
# {{/docs-fragment basic-parameter-types}}

# {{docs-fragment runoutput-example}}
# Delayed parameters with RunOutput
env = flyte.TaskEnvironment(name="training-env")

@env.task
async def train_model() -> flyte.io.File:
    # ... training logic ...
    return await flyte.io.File.from_local("/tmp/trained-model.pkl")

# Use the task output as an app parameter
app_env4 = flyte.app.AppEnvironment(
    name="serving-app",
    parameters=[
        flyte.app.Parameter(
            name="model",
            value=flyte.app.RunOutput(type="file", run_name="training_run", task_name="train_model"),
            mount="/app/model",
        ),
    ],
    # ...
)
# {{/docs-fragment runoutput-example}}

# {{docs-fragment appendpoint-example}}
# Delayed parameters with AppEndpoint
app1_env = flyte.app.AppEnvironment(name="backend-api")

app2_env = flyte.app.AppEnvironment(
    name="frontend-app",
    parameters=[
        flyte.app.Parameter(
            name="backend_url",
            value=flyte.app.AppEndpoint(app_name="backend-api"),
            env_var="BACKEND_URL",  # app1_env's endpoint will be available as an environment variable
        ),
    ],
    # ...
)
# {{/docs-fragment appendpoint-example}}

# {{docs-fragment runoutput-serving-example}}
# Example: Using RunOutput for model serving
import joblib
from sklearn.ensemble import RandomForestClassifier
from flyte.app.extras import FastAPIAppEnvironment
from fastapi import FastAPI

# Training task
training_env = flyte.TaskEnvironment(name="training-env")

@training_env.task
async def train_model_task() -> flyte.io.File:
    """Train a model and return it."""

    model = RandomForestClassifier()

    # ... training logic ...

    path = "./trained-model.pkl"
    joblib.dump(model, path)
    return await flyte.io.File.from_local(path)

# Serving app that uses the trained model
app = FastAPI()
serving_env = FastAPIAppEnvironment(
    name="model-serving-app",
    app=app,
    parameters=[
        flyte.app.Parameter(
            name="model",
            value=flyte.app.RunOutput(
                type="file",
                task_name="training-env.train_model_task"
            ),
            mount="/app/model",
            env_var="MODEL_PATH",
        ),
    ],
)
# {{/docs-fragment runoutput-serving-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/passing-parameters-examples.py*

The endpoint URL will be injected as the parameter value when the app starts.

This is particularly useful when you want to chain apps together (for example, a frontend app calling a backend app), without hardcoding URLs.

## Overriding parameters at serve time

You can override parameter values when serving apps (this is not supported for deployment):

```python
# Override parameters when serving
app = flyte.with_servecontext(
    input_values={"my-app": {"model_path": "s3://bucket/new-model.pkl"}}
).serve(app_env)
```

> [!NOTE]
> Parameter overrides are only available when using `flyte.serve()` or `flyte.with_servecontext().serve()`. 
> The `flyte.deploy()` function does not support parameter overrides - parameters must be specified in the `AppEnvironment` definition.

This is useful for:
- Testing different configurations during development
- Using different models or data sources for testing
- A/B testing different app configurations

## Example: FastAPI app with configurable model

Here's a complete example showing how to use parameters in a FastAPI app:

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "fastapi",
#    "uvicorn",
#    "joblib",
#    "scikit-learn",
#    "flyte>=2.0.0b52",
# ]
# ///

from contextlib import asynccontextmanager
from pathlib import Path

import flyte
import flyte.app
import flyte.io
from flyte.app.extras import FastAPIAppEnvironment
from fastapi import FastAPI

# {{docs-fragment model-serving-api}}

image = flyte.Image.from_uv_script(__file__, name="app-parameters-fastapi-example")

task_env = flyte.TaskEnvironment(
    name="model_serving_task",
    image=image,
    resources=flyte.Resources(cpu=2, memory="1Gi"),
    cache="auto",
)

@task_env.task
async def train_model_task() -> flyte.io.File:
    """Train a model and return it."""
    import joblib
    import sklearn.ensemble
    import sklearn.datasets

    X, y = sklearn.datasets.make_classification(n_samples=1000, n_features=5, n_classes=2, random_state=42)
    model = sklearn.ensemble.RandomForestClassifier()
    model.fit(X, y)

    model_dir = Path("/tmp/model")
    model_dir.mkdir(parents=True, exist_ok=True)
    model_path = model_dir / "model.joblib"
    joblib.dump(model, model_path)
    return await flyte.io.File.from_local(model_path)

state = {}

@asynccontextmanager
async def lifespan(app: FastAPI):
    import joblib

    model = joblib.load("/root/models/model.joblib")
    state["model"] = model
    yield

app = FastAPI(lifespan=lifespan)

app_env = FastAPIAppEnvironment(
    name="model-serving-api",
    app=app,
    parameters=[
        flyte.app.Parameter(
            name="model_file",
            # this is a placeholder
            value=flyte.io.File.from_existing_remote("s3://bucket/models/default.pkl"),
            mount="/root/models/",
            download=True,
        ),
    ],
    image=image,
    resources=flyte.Resources(cpu=2, memory="2Gi"),
    requires_auth=False,
)

@app.post("/predict")
async def predict(data: list[float]) -> dict[str, list[float]]:
    model = state["model"]
    return {"prediction": model.predict([data]).tolist()}

if __name__ == "__main__":
    import logging

    flyte.init_from_config(log_level=logging.DEBUG)

    run = flyte.run(train_model_task)
    print(f"Run: {run.url}")
    run.wait()

    model_file = run.outputs()[0]
    print(f"Model file: {model_file.path}")

    app = flyte.with_servecontext(
        parameter_values={
            "model-serving-api": {
                "model_file": flyte.io.File.from_existing_remote(model_file.path)
            }
        }
    ).serve(app_env)
    print(f"API URL: {app.url}")
# {{/docs-fragment model-serving-api}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/configure-apps/app-parameters-fastapi-example.py*

## Example: Using RunOutput for model serving

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
#    "scikit-learn",
#    "joblib",
# ]
# ///

"""Examples showing different ways to pass parameters into apps."""

import flyte
import flyte.app
import flyte.io

# {{docs-fragment basic-parameter-types}}
# String parameters
app_env = flyte.app.AppEnvironment(
    name="configurable-app",
    parameters=[
        flyte.app.Parameter(name="environment", value="production"),
        flyte.app.Parameter(name="log_level", value="INFO"),
    ],
    # ...
)

# File parameters
app_env2 = flyte.app.AppEnvironment(
    name="app-with-model",
    parameters=[
        flyte.app.Parameter(
            name="model_file",
            value=flyte.io.File("s3://bucket/models/model.pkl"),
            mount="/app/models",
        ),
    ],
    # ...
)

# Directory parameters
app_env3 = flyte.app.AppEnvironment(
    name="app-with-data",
    parameters=[
        flyte.app.Parameter(
            name="data_dir",
            value=flyte.io.Dir("s3://bucket/data/"),
            mount="/app/data",
        ),
    ],
    # ...
)
# {{/docs-fragment basic-parameter-types}}

# {{docs-fragment runoutput-example}}
# Delayed parameters with RunOutput
env = flyte.TaskEnvironment(name="training-env")

@env.task
async def train_model() -> flyte.io.File:
    # ... training logic ...
    return await flyte.io.File.from_local("/tmp/trained-model.pkl")

# Use the task output as an app parameter
app_env4 = flyte.app.AppEnvironment(
    name="serving-app",
    parameters=[
        flyte.app.Parameter(
            name="model",
            value=flyte.app.RunOutput(type="file", run_name="training_run", task_name="train_model"),
            mount="/app/model",
        ),
    ],
    # ...
)
# {{/docs-fragment runoutput-example}}

# {{docs-fragment appendpoint-example}}
# Delayed parameters with AppEndpoint
app1_env = flyte.app.AppEnvironment(name="backend-api")

app2_env = flyte.app.AppEnvironment(
    name="frontend-app",
    parameters=[
        flyte.app.Parameter(
            name="backend_url",
            value=flyte.app.AppEndpoint(app_name="backend-api"),
            env_var="BACKEND_URL",  # app1_env's endpoint will be available as an environment variable
        ),
    ],
    # ...
)
# {{/docs-fragment appendpoint-example}}

# {{docs-fragment runoutput-serving-example}}
# Example: Using RunOutput for model serving
import joblib
from sklearn.ensemble import RandomForestClassifier
from flyte.app.extras import FastAPIAppEnvironment
from fastapi import FastAPI

# Training task
training_env = flyte.TaskEnvironment(name="training-env")

@training_env.task
async def train_model_task() -> flyte.io.File:
    """Train a model and return it."""

    model = RandomForestClassifier()

    # ... training logic ...

    path = "./trained-model.pkl"
    joblib.dump(model, path)
    return await flyte.io.File.from_local(path)

# Serving app that uses the trained model
app = FastAPI()
serving_env = FastAPIAppEnvironment(
    name="model-serving-app",
    app=app,
    parameters=[
        flyte.app.Parameter(
            name="model",
            value=flyte.app.RunOutput(
                type="file",
                task_name="training-env.train_model_task"
            ),
            mount="/app/model",
            env_var="MODEL_PATH",
        ),
    ],
)
# {{/docs-fragment runoutput-serving-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/passing-parameters-examples.py*

## Accessing parameters in your app

How you access parameters depends on how they're configured:

1. **Environment variables**: If `env_var` is specified, the parameter is available as an environment variable
2. **Mounted paths**: File and directory parameters are mounted at the specified path
3. **Flyte SDK**: Use the Flyte SDK to access parameter values programmatically

```python
import os

# Parameter with env_var specified
env = flyte.app.AppEnvironment(
    name="my-app",
    parameters=[
        flyte.app.Parameter(
            name="model_file",
            value=flyte.io.File("s3://bucket/model.pkl"),
            mount="/app/models/model.pkl",
            env_var="MODEL_PATH",
        ),
    ],
    # ...
)

# Access in the app via the environment variable
API_KEY = os.getenv("API_KEY")

# Access in the app via the mounted path
with open("/app/models/model.pkl", "rb") as f:
    model = pickle.load(f)

# Access in the app via the Flyte SDK (for string parameters)
parameter_value = flyte.app.get_parameter("model_file")  # Returns string value
```

## Best practices

1. **Use delayed parameters**: Leverage `RunOutput` and `AppEndpoint` to create app dependencies between tasks and apps, or app-to-app chains.
2. **Override for testing**: Use the `input_values` parameter when serving to test different configurations without changing code.
3. **Mount paths clearly**: Use descriptive mount paths for file/directory parameters so your app code is easy to understand.
4. **Use environment variables**: For simple constants that you can hard-code, use `env_var` to inject values as environment variables.
5. **Production deployments**: For production, define parameters in the `AppEnvironment` rather than overriding them at deploy time.

## Limitations

- Large files/directories can slow down app startup.
- Parameter overrides are only available when using `flyte.with_servecontext(...).serve(...)`.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/configure-apps/auto-scaling-apps ===

## Autoscaling apps

Flyte apps support autoscaling, allowing them to scale up and down based on traffic. This helps optimize costs by scaling down when there's no traffic and scaling up when needed.

### Scaling configuration

The `scaling` parameter uses a `[[Scaling]]` object to configure autoscaling behavior:

```python
scaling=flyte.app.Scaling(
    replicas=(min_replicas, max_replicas),
    scaledown_after=idle_ttl_seconds,
)
```

#### Parameters

- **`replicas`**: A tuple `(min_replicas, max_replicas)` specifying the minimum and maximum number of replicas.
- **`scaledown_after`**: Time in seconds to wait before scaling down when idle (idle TTL).

### Basic scaling example

Here's a simple example with scaling from 0 to 1 replica:

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

import flyte
import flyte.app

# {{docs-fragment basic-scaling}}
# Basic example: scale from 0 to 1 replica
app_env = flyte.app.AppEnvironment(
    name="autoscaling-app",
    scaling=flyte.app.Scaling(
        replicas=(0, 1),  # Scale from 0 to 1 replica
        scaledown_after=300,  # Scale down after 5 minutes of inactivity
    ),
    # ...
)
# {{/docs-fragment basic-scaling}}

# {{docs-fragment always-on}}
# Always-on app
app_env2 = flyte.app.AppEnvironment(
    name="always-on-api",
    scaling=flyte.app.Scaling(
        replicas=(1, 1),  # Always keep 1 replica running
        # scaledown_after is ignored when min_replicas > 0
    ),
    # ...
)
# {{/docs-fragment always-on}}

# {{docs-fragment scale-to-zero}}
# Scale-to-zero app
app_env3 = flyte.app.AppEnvironment(
    name="scale-to-zero-app",
    scaling=flyte.app.Scaling(
        replicas=(0, 1),  # Can scale down to 0
        scaledown_after=600,  # Scale down after 10 minutes of inactivity
    ),
    # ...
)
# {{/docs-fragment scale-to-zero}}

# {{docs-fragment high-availability}}
# High-availability app
app_env4 = flyte.app.AppEnvironment(
    name="ha-api",
    scaling=flyte.app.Scaling(
        replicas=(2, 5),  # Keep at least 2, scale up to 5
        scaledown_after=300,  # Scale down after 5 minutes
    ),
    # ...
)
# {{/docs-fragment high-availability}}

# {{docs-fragment burstable}}
# Burstable app
app_env5 = flyte.app.AppEnvironment(
    name="bursty-app",
    scaling=flyte.app.Scaling(
        replicas=(1, 10),  # Start with 1, scale up to 10 under load
        scaledown_after=180,  # Scale down quickly after 3 minutes
    ),
    # ...
)
# {{/docs-fragment burstable}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/configure-apps/autoscaling-examples.py*

This configuration:

- Starts with 0 replicas (no running instances)
- Scales up to 1 replica when there's traffic
- Scales back down to 0 after 5 minutes (300 seconds) of no traffic

### Scaling patterns

#### Always-on app

For apps that need to always be running:

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

import flyte
import flyte.app

# {{docs-fragment basic-scaling}}
# Basic example: scale from 0 to 1 replica
app_env = flyte.app.AppEnvironment(
    name="autoscaling-app",
    scaling=flyte.app.Scaling(
        replicas=(0, 1),  # Scale from 0 to 1 replica
        scaledown_after=300,  # Scale down after 5 minutes of inactivity
    ),
    # ...
)
# {{/docs-fragment basic-scaling}}

# {{docs-fragment always-on}}
# Always-on app
app_env2 = flyte.app.AppEnvironment(
    name="always-on-api",
    scaling=flyte.app.Scaling(
        replicas=(1, 1),  # Always keep 1 replica running
        # scaledown_after is ignored when min_replicas > 0
    ),
    # ...
)
# {{/docs-fragment always-on}}

# {{docs-fragment scale-to-zero}}
# Scale-to-zero app
app_env3 = flyte.app.AppEnvironment(
    name="scale-to-zero-app",
    scaling=flyte.app.Scaling(
        replicas=(0, 1),  # Can scale down to 0
        scaledown_after=600,  # Scale down after 10 minutes of inactivity
    ),
    # ...
)
# {{/docs-fragment scale-to-zero}}

# {{docs-fragment high-availability}}
# High-availability app
app_env4 = flyte.app.AppEnvironment(
    name="ha-api",
    scaling=flyte.app.Scaling(
        replicas=(2, 5),  # Keep at least 2, scale up to 5
        scaledown_after=300,  # Scale down after 5 minutes
    ),
    # ...
)
# {{/docs-fragment high-availability}}

# {{docs-fragment burstable}}
# Burstable app
app_env5 = flyte.app.AppEnvironment(
    name="bursty-app",
    scaling=flyte.app.Scaling(
        replicas=(1, 10),  # Start with 1, scale up to 10 under load
        scaledown_after=180,  # Scale down quickly after 3 minutes
    ),
    # ...
)
# {{/docs-fragment burstable}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/configure-apps/autoscaling-examples.py*

#### Scale-to-zero app

For apps that can scale to zero when idle:

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

import flyte
import flyte.app

# {{docs-fragment basic-scaling}}
# Basic example: scale from 0 to 1 replica
app_env = flyte.app.AppEnvironment(
    name="autoscaling-app",
    scaling=flyte.app.Scaling(
        replicas=(0, 1),  # Scale from 0 to 1 replica
        scaledown_after=300,  # Scale down after 5 minutes of inactivity
    ),
    # ...
)
# {{/docs-fragment basic-scaling}}

# {{docs-fragment always-on}}
# Always-on app
app_env2 = flyte.app.AppEnvironment(
    name="always-on-api",
    scaling=flyte.app.Scaling(
        replicas=(1, 1),  # Always keep 1 replica running
        # scaledown_after is ignored when min_replicas > 0
    ),
    # ...
)
# {{/docs-fragment always-on}}

# {{docs-fragment scale-to-zero}}
# Scale-to-zero app
app_env3 = flyte.app.AppEnvironment(
    name="scale-to-zero-app",
    scaling=flyte.app.Scaling(
        replicas=(0, 1),  # Can scale down to 0
        scaledown_after=600,  # Scale down after 10 minutes of inactivity
    ),
    # ...
)
# {{/docs-fragment scale-to-zero}}

# {{docs-fragment high-availability}}
# High-availability app
app_env4 = flyte.app.AppEnvironment(
    name="ha-api",
    scaling=flyte.app.Scaling(
        replicas=(2, 5),  # Keep at least 2, scale up to 5
        scaledown_after=300,  # Scale down after 5 minutes
    ),
    # ...
)
# {{/docs-fragment high-availability}}

# {{docs-fragment burstable}}
# Burstable app
app_env5 = flyte.app.AppEnvironment(
    name="bursty-app",
    scaling=flyte.app.Scaling(
        replicas=(1, 10),  # Start with 1, scale up to 10 under load
        scaledown_after=180,  # Scale down quickly after 3 minutes
    ),
    # ...
)
# {{/docs-fragment burstable}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/configure-apps/autoscaling-examples.py*

#### High-availability app

For apps that need multiple replicas for availability:

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

import flyte
import flyte.app

# {{docs-fragment basic-scaling}}
# Basic example: scale from 0 to 1 replica
app_env = flyte.app.AppEnvironment(
    name="autoscaling-app",
    scaling=flyte.app.Scaling(
        replicas=(0, 1),  # Scale from 0 to 1 replica
        scaledown_after=300,  # Scale down after 5 minutes of inactivity
    ),
    # ...
)
# {{/docs-fragment basic-scaling}}

# {{docs-fragment always-on}}
# Always-on app
app_env2 = flyte.app.AppEnvironment(
    name="always-on-api",
    scaling=flyte.app.Scaling(
        replicas=(1, 1),  # Always keep 1 replica running
        # scaledown_after is ignored when min_replicas > 0
    ),
    # ...
)
# {{/docs-fragment always-on}}

# {{docs-fragment scale-to-zero}}
# Scale-to-zero app
app_env3 = flyte.app.AppEnvironment(
    name="scale-to-zero-app",
    scaling=flyte.app.Scaling(
        replicas=(0, 1),  # Can scale down to 0
        scaledown_after=600,  # Scale down after 10 minutes of inactivity
    ),
    # ...
)
# {{/docs-fragment scale-to-zero}}

# {{docs-fragment high-availability}}
# High-availability app
app_env4 = flyte.app.AppEnvironment(
    name="ha-api",
    scaling=flyte.app.Scaling(
        replicas=(2, 5),  # Keep at least 2, scale up to 5
        scaledown_after=300,  # Scale down after 5 minutes
    ),
    # ...
)
# {{/docs-fragment high-availability}}

# {{docs-fragment burstable}}
# Burstable app
app_env5 = flyte.app.AppEnvironment(
    name="bursty-app",
    scaling=flyte.app.Scaling(
        replicas=(1, 10),  # Start with 1, scale up to 10 under load
        scaledown_after=180,  # Scale down quickly after 3 minutes
    ),
    # ...
)
# {{/docs-fragment burstable}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/configure-apps/autoscaling-examples.py*

#### Burstable app

For apps with variable load:

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

import flyte
import flyte.app

# {{docs-fragment basic-scaling}}
# Basic example: scale from 0 to 1 replica
app_env = flyte.app.AppEnvironment(
    name="autoscaling-app",
    scaling=flyte.app.Scaling(
        replicas=(0, 1),  # Scale from 0 to 1 replica
        scaledown_after=300,  # Scale down after 5 minutes of inactivity
    ),
    # ...
)
# {{/docs-fragment basic-scaling}}

# {{docs-fragment always-on}}
# Always-on app
app_env2 = flyte.app.AppEnvironment(
    name="always-on-api",
    scaling=flyte.app.Scaling(
        replicas=(1, 1),  # Always keep 1 replica running
        # scaledown_after is ignored when min_replicas > 0
    ),
    # ...
)
# {{/docs-fragment always-on}}

# {{docs-fragment scale-to-zero}}
# Scale-to-zero app
app_env3 = flyte.app.AppEnvironment(
    name="scale-to-zero-app",
    scaling=flyte.app.Scaling(
        replicas=(0, 1),  # Can scale down to 0
        scaledown_after=600,  # Scale down after 10 minutes of inactivity
    ),
    # ...
)
# {{/docs-fragment scale-to-zero}}

# {{docs-fragment high-availability}}
# High-availability app
app_env4 = flyte.app.AppEnvironment(
    name="ha-api",
    scaling=flyte.app.Scaling(
        replicas=(2, 5),  # Keep at least 2, scale up to 5
        scaledown_after=300,  # Scale down after 5 minutes
    ),
    # ...
)
# {{/docs-fragment high-availability}}

# {{docs-fragment burstable}}
# Burstable app
app_env5 = flyte.app.AppEnvironment(
    name="bursty-app",
    scaling=flyte.app.Scaling(
        replicas=(1, 10),  # Start with 1, scale up to 10 under load
        scaledown_after=180,  # Scale down quickly after 3 minutes
    ),
    # ...
)
# {{/docs-fragment burstable}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/configure-apps/autoscaling-examples.py*

### Idle TTL (Time To Live)

The `scaledown_after` parameter (idle TTL) determines how long an app instance can be idle before it's scaled down. 

#### Considerations

- **Too short**: May cause frequent scale up/down cycles, leading to cold starts.
- **Too long**: Keeps resources running unnecessarily, increasing costs.
- **Optimal**: Balance between cost and user experience.

#### Common idle TTL values

- **Development/Testing**: 60-180 seconds (1-3 minutes) - quick scale down for cost savings.
- **Production APIs**: 300-600 seconds (5-10 minutes) - balance cost and responsiveness.
- **Batch processing**: 900-1800 seconds (15-30 minutes) - longer to handle bursts.
- **Always-on**: Set `min_replicas > 0` - never scale down.

### Autoscaling best practices

1. **Start conservative**: Begin with longer idle TTL values and adjust based on usage.
2. **Monitor cold starts**: Track how long it takes for your app to become ready after scaling up.
3. **Consider costs**: Balance idle TTL between cost savings and user experience.
4. **Use appropriate min replicas**: Set `min_replicas > 0` for critical apps that need to be always available.
5. **Test scaling behavior**: Verify your app handles scale up/down correctly (for example, state management and connections).

### Autoscaling limitations

- Scaling is based on traffic/request patterns, not CPU/memory utilization.
- Cold starts may occur when scaling from zero.
- Stateful apps need careful design to handle scaling (use external state stores).
- Maximum replicas are limited by your cluster capacity.

### Autoscaling troubleshooting

**App scales down too quickly:**

- Increase `scaledown_after` value.
- Set `min_replicas > 0` if the app needs to stay warm.

**App doesn't scale up fast enough:**

- Ensure your cluster has capacity.
- Check if there are resource constraints.

**Cold starts are too slow:**

- Pre-warm with `min_replicas = 1`.
- Optimize app startup time.
- Consider using faster storage for model loading.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/configure-apps/apps-depending-on-environments ===

# Apps depending on other environments

The `depends_on` parameter allows you to specify that one app depends on another app (or task environment). When you deploy an app with `depends_on`, Flyte ensures that all dependencies are deployed first.

## Basic usage

Use `depends_on` to specify a list of environments that this app depends on:

```python
app1_env = flyte.app.AppEnvironment(name="backend-api", ...)

app2_env = flyte.app.AppEnvironment(
    name="frontend-app",
    depends_on=[app1_env],  # Ensure backend-api is deployed first
    # ...
)
```

When you deploy `app2_env`, Flyte will:
1. First deploy `app1_env` (if not already deployed)
2. Then deploy `app2_env`
3. Make sure `app1_env` is available before `app2_env` starts

## Example: App calling another app

Here's a complete example where one FastAPI app calls another:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
#    "httpx",
# ]
# ///

"""Example of one app calling another app."""

import httpx
from fastapi import FastAPI
import pathlib
import flyte
from flyte.app.extras import FastAPIAppEnvironment

image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
    "fastapi", "uvicorn", "httpx"
)

# {{docs-fragment backend-app}}
app1 = FastAPI(
    title="App 1",
    description="A FastAPI app that runs some computations",
)

env1 = FastAPIAppEnvironment(
    name="app1-is-called-by-app2",
    app=app1,
    image=image,
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
)
# {{/docs-fragment backend-app}}

# {{docs-fragment frontend-app}}
app2 = FastAPI(
    title="App 2",
    description="A FastAPI app that proxies requests to another FastAPI app",
)

env2 = FastAPIAppEnvironment(
    name="app2-calls-app1",
    app=app2,
    image=image,
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
    depends_on=[env1],  # Depends on backend-api
)
# {{/docs-fragment frontend-app}}

# {{docs-fragment backend-endpoint}}
@app1.get("/greeting/{name}")
async def greeting(name: str) -> str:
    return f"Hello, {name}!"
# {{/docs-fragment backend-endpoint}}

# {{docs-fragment frontend-endpoints}}
@app2.get("/app1-endpoint")
async def get_app1_endpoint() -> str:
    return env1.endpoint  # Access the backend endpoint

@app2.get("/greeting/{name}")
async def greeting_proxy(name: str):
    """Proxy that calls the backend app."""
    async with httpx.AsyncClient() as client:
        response = await client.get(f"{env1.endpoint}/greeting/{name}")
        response.raise_for_status()
        return response.json()
# {{/docs-fragment frontend-endpoints}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    deployments = flyte.deploy(env2)
    print(f"Deployed FastAPI app: {deployments[0].env_repr()}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/app_calling_app.py*

When you deploy `env2`, Flyte will:
1. Deploy `env1` first (backend-api)
2. Wait for `env1` to be ready
3. Deploy `env2` (frontend-api)
4. `env2` can then access `env1.endpoint` to make requests

## Dependency chain

You can create chains of dependencies:

```python
app1_env = flyte.app.AppEnvironment(name="service-1", ...)
app2_env = flyte.app.AppEnvironment(name="service-2", depends_on=[app1_env], ...)
app3_env = flyte.app.AppEnvironment(name="service-3", depends_on=[app2_env], ...)

# Deploying app3_env will deploy in order: app1_env -> app2_env -> app3_env
```

## Multiple dependencies

An app can depend on multiple environments:

```python
backend_env = flyte.app.AppEnvironment(name="backend", ...)
database_env = flyte.app.AppEnvironment(name="database", ...)

api_env = flyte.app.AppEnvironment(
    name="api",
    depends_on=[backend_env, database_env],  # Depends on both
    # ...
)
```

When deploying `api_env`, both `backend_env` and `database_env` will be deployed first (they may be deployed in parallel if they don't depend on each other).

## Using AppEndpoint for dependency URLs

When one app depends on another, you can use `AppEndpoint` to get the URL:

```python
backend_env = flyte.app.AppEnvironment(name="backend-api", ...)

frontend_env = flyte.app.AppEnvironment(
    name="frontend-app",
    depends_on=[backend_env],
    parameters=[
        flyte.app.Parameter(
            name="backend_url",
            value=flyte.app.AppEndpoint(app_name="backend-api"),
        ),
    ],
    # ...
)
```

The `backend_url` parameter will be automatically set to the backend app's endpoint URL.
You can get this value in your app code using `flyte.app.get_input("backend_url")`.

## Deployment behavior

When deploying with `flyte.deploy()`:

```python
# Deploy the app (dependencies are automatically deployed)
deployments = flyte.deploy(env2)

# All dependencies are included in the deployment plan
for deployment in deployments:
    print(f"Deployed: {deployment.env.name}")
```

Flyte will:
1. Build a deployment plan that includes all dependencies
2. Deploy dependencies in the correct order
3. Ensure dependencies are ready before deploying dependent apps

## Task environment dependencies

You can also depend on task environments:

```python
task_env = flyte.TaskEnvironment(name="training-env", ...)

serving_env = flyte.app.AppEnvironment(
    name="serving-app",
    depends_on=[task_env],  # Can depend on task environments too
    # ...
)
```

This ensures the task environment is available when the app is deployed (useful if the app needs to call tasks in that environment).

## Best practices

1. **Explicit dependencies**: Always use `depends_on` to make app dependencies explicit
2. **Circular dependencies**: Avoid circular dependencies (app A depends on B, B depends on A)
3. **Dependency order**: Design your dependency graph to be a DAG (Directed Acyclic Graph)
4. **Endpoint access**: Use `AppEndpoint` to pass dependency URLs as inputs
5. **Document dependencies**: Make sure your app documentation explains its dependencies

## Example: A/B testing with dependencies

Here's an example of an A/B testing setup where a root app depends on two variant apps:

```python
app_a = FastAPI(title="Variant A")
app_b = FastAPI(title="Variant B")
root_app = FastAPI(title="Root App")

env_a = FastAPIAppEnvironment(name="app-a-variant", app=app_a, ...)
env_b = FastAPIAppEnvironment(name="app-b-variant", app=app_b, ...)

env_root = FastAPIAppEnvironment(
    name="root-ab-testing-app",
    app=root_app,
    depends_on=[env_a, env_b],  # Depends on both variants
    # ...
)
```

The root app can route traffic to either variant A or B based on A/B testing logic, and both variants will be deployed before the root app starts.

## Limitations

- Circular dependencies are not supported
- Dependencies must be in the same project/domain
- Dependency deployment order is deterministic but dependencies at the same level may deploy in parallel


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/build-apps ===

# Build apps

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

This section covers how to build different types of apps with Flyte, including Streamlit dashboards, FastAPI REST APIs, vLLM and SGLang model servers, webhooks, and WebSocket applications.

> [!TIP]
> Go to **Core concepts > Apps** for an overview of apps and a quick example.

## App types

Flyte supports various types of apps:

- **UI dashboard apps**: Interactive web dashboards and data visualization tools like Streamlit and Gradio
- **Web API apps**: REST APIs, webhooks, and backend services like FastAPI and Flask
- **Model serving apps**: High-performance LLM serving with vLLM and SGLang

## Next steps

- **Build apps > Single-script apps**: The simplest way to build and deploy apps in a single Python script
- **Build apps > Multi-script apps**: Build FastAPI and Streamlit apps with multiple files
- **Build apps > App usage patterns**: Call apps from tasks, tasks from apps, and apps from apps
- **Build apps > Secret-based authentication**: Authenticate FastAPI apps using Flyte secrets
- **Build apps > Streamlit app**: Build interactive Streamlit dashboards
- **Build apps > FastAPI app**: Create REST APIs and backend services
- **Build apps > vLLM app**: Serve large language models with vLLM
- **Build apps > SGLang app**: Serve LLMs with SGLang for structured generation

## Subpages
- **Build apps > Single-script apps**
- **Build apps > Multi-script apps**
- **Build apps > App usage patterns**
- **Build apps > Secret-based authentication**
- **Build apps > Streamlit app**
- **Build apps > FastAPI app**
- **Build apps > vLLM app**
- **Build apps > SGLang app**


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/build-apps/single-script-apps ===

# Single-script apps

The simplest way to build and deploy an app with Flyte is to write everything in a single Python script. This approach is perfect for:

- **Quick prototypes**: Rapidly test ideas and concepts
- **Simple services**: Basic HTTP servers, APIs, or dashboards
- **Learning**: Understanding how Flyte apps work without complexity
- **Minimal examples**: Demonstrating core functionality

All the code for your app—the application logic, the app environment configuration, and the deployment code—lives in one file. This makes it easy to understand, share, and deploy.

## Plain Python HTTP server

The simplest possible app is a plain Python HTTP server using Python's built-in `http.server` module. This requires no external dependencies beyond the Flyte SDK.

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""A plain Python HTTP server example - the simplest possible app."""

import flyte
import flyte.app
from pathlib import Path

# {{docs-fragment server-code}}
# Create a simple HTTP server handler
from http.server import HTTPServer, BaseHTTPRequestHandler

class SimpleHandler(BaseHTTPRequestHandler):
    """A simple HTTP server handler."""

    def do_GET(self):

        if self.path == "/":
            self.send_response(200)
            self.send_header("Content-type", "text/html")
            self.end_headers()
            self.wfile.write(b"<h1>Hello from Plain Python Server!</h1>")

        elif self.path == "/health":
            self.send_response(200)
            self.send_header("Content-type", "application/json")
            self.end_headers()
            self.wfile.write(b'{"status": "healthy"}')

        else:
            self.send_response(404)
            self.end_headers()
# {{/docs-fragment server-code}}

# {{docs-fragment app-env}}
file_name = Path(__file__).name
app_env = flyte.app.AppEnvironment(
    name="plain-python-server",
    image=flyte.Image.from_debian_base(python_version=(3, 12)),
    args=["python", file_name, "--server"],
    port=8080,
    resources=flyte.Resources(cpu="1", memory="512Mi"),
    requires_auth=False,
)
# {{/docs-fragment app-env}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    import sys

    if "--server" in sys.argv:
        server = HTTPServer(("0.0.0.0", 8080), SimpleHandler)
        print("Server running on port 8080")
        server.serve_forever()
    else:
        flyte.init_from_config(root_dir=Path(__file__).parent)
        app = flyte.serve(app_env)
        print(f"App URL: {app.url}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/plain_python_server.py*

**Key points**

- **No external dependencies**: Uses only Python's standard library
- **Simple handler**: Define request handlers as Python classes
- **Basic command**: Run the server with a simple Python command
- **Minimal resources**: Requires only basic CPU and memory

## Streamlit app

Streamlit makes it easy to build interactive web dashboards. Here's a complete single-script Streamlit app:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "streamlit",
# ]
# ///

"""A single-script Streamlit app example."""

import pathlib
import streamlit as st
import flyte
import flyte.app

# {{docs-fragment streamlit-app}}
def main():
    st.set_page_config(page_title="Simple Streamlit App", page_icon="🚀")

    st.title("Hello from Streamlit!")
    st.write("This is a simple single-script Streamlit app.")

    name = st.text_input("What's your name?", "World")
    st.write(f"Hello, {name}!")

    if st.button("Click me!"):
        st.balloons()
        st.success("Button clicked!")
# {{/docs-fragment streamlit-app}}

# {{docs-fragment app-env}}
file_name = pathlib.Path(__file__).name
app_env = flyte.app.AppEnvironment(
    name="streamlit-single-script",
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "streamlit==1.41.1"
    ),
    args=["streamlit", "run", file_name, "--server.port", "8080", "--", "--server"],
    port=8080,
    resources=flyte.Resources(cpu="1", memory="1Gi"),
    requires_auth=False,
)
# {{/docs-fragment app-env}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    import sys

    if "--server" in sys.argv:
        main()
    else:
        flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
        app = flyte.serve(app_env)
        print(f"App URL: {app.url}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/streamlit_single_script.py*

**Key points**

- **Interactive UI**: Streamlit provides widgets and visualizations out of the box
- **Single file**: All UI logic and deployment code in one script
- **Simple deployment**: Just specify the Streamlit command and port
- **Rich ecosystem**: Access to Streamlit's extensive component library

## FastAPI app

FastAPI is a modern, fast web framework for building APIs. Here's a minimal single-script FastAPI app:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
# ]
# ///

"""A single-script FastAPI app example - the simplest FastAPI app."""

from fastapi import FastAPI
import pathlib
import flyte
from flyte.app.extras import FastAPIAppEnvironment

# {{docs-fragment fastapi-app}}
app = FastAPI(
    title="Simple FastAPI App",
    description="A minimal single-script FastAPI application",
    version="1.0.0",
)

@app.get("/")
async def root():
    return {"message": "Hello, World!"}

@app.get("/health")
async def health():
    return {"status": "healthy"}
# {{/docs-fragment fastapi-app}}

# {{docs-fragment app-env}}
app_env = FastAPIAppEnvironment(
    name="fastapi-single-script",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
    ),
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
)
# {{/docs-fragment app-env}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    app_deployment = flyte.serve(app_env)
    print(f"Deployed: {app_deployment.url}")
    print(f"API docs: {app_deployment.url}/docs")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi_single_script.py*

**Key points**

- **FastAPIAppEnvironment**: Automatically configures uvicorn and FastAPI
- **Type hints**: FastAPI uses Python type hints for automatic validation
- **Auto docs**: Interactive API documentation at `/docs` endpoint
- **Async support**: Built-in support for async/await patterns

## Running single-script apps

To run any of these examples:

1. **Save the script** to a file (e.g., `my_app.py`)
2. **Ensure you have a config file** (`./.flyte/config.yaml` or `./config.yaml`)
3. **Run the script**:

```bash
python my_app.py
```

Or using `uv`:

```bash
uv run my_app.py
```

The script will:
- Initialize Flyte from your config
- Deploy the app to your Union/Flyte instance
- Print the app URL

## When to use single-script apps

**Use single-script apps when:**
- Building prototypes or proof-of-concepts
- Creating simple services with minimal logic
- Learning how Flyte apps work
- Sharing complete, runnable examples
- Building demos or tutorials

**Consider multi-script apps when:**
- Your app grows beyond a few hundred lines
- You need to organize code into modules
- You want to reuse components across apps
- You're building production applications

See [**Multi-script apps**](./multi-script-apps) for examples of organizing apps across multiple files.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/build-apps/multi-script-apps ===

# Multi-script apps

Real-world applications often span multiple files. This page shows how to build FastAPI and Streamlit apps with multiple Python files.

## FastAPI multi-script app

### Project structure

```
project/
├── app.py          # Main FastAPI app file
└── module.py       # Helper module
```

### Example: Multi-file FastAPI app

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
# ]
# ///

"""Multi-file FastAPI app example."""

from fastapi import FastAPI
from module import function  # Import from another file
import pathlib

import flyte
from flyte.app.extras import FastAPIAppEnvironment

# {{docs-fragment app-definition}}
app = FastAPI(title="Multi-file FastAPI Demo")

app_env = FastAPIAppEnvironment(
    name="fastapi-multi-file",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
    ),
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
    # FastAPIAppEnvironment automatically includes necessary files
    # But you can also specify explicitly:
    # include=["app.py", "module.py"],
)
# {{/docs-fragment app-definition}}

# {{docs-fragment endpoint}}
@app.get("/")
async def root():
    return function()  # Uses function from module.py
# {{/docs-fragment endpoint}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    app_deployment = flyte.deploy(app_env)
    print(f"Deployed: {app_deployment[0].summary_repr()}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/multi_file/app.py*

```
# {{docs-fragment helper-function}}
def function():
    """Helper function used by the FastAPI app."""
    return {"message": "Hello from module.py!"}
# {{/docs-fragment helper-function}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/multi_file/module.py*

### Automatic file discovery

`FastAPIAppEnvironment` automatically discovers and includes the necessary files by analyzing your imports. However, if you have files that aren't automatically detected (like configuration files or data files), you can explicitly include them:

```python
app_env = FastAPIAppEnvironment(
    name="fastapi-with-config",
    app=app,
    include=["app.py", "module.py", "config.yaml"],  # Explicit includes
    # ...
)
```

## Streamlit multi-script app

### Project structure

```
project/
├── main.py         # Main Streamlit app
├── utils.py        # Utility functions
└── components.py   # Reusable components
```

### Example: Multi-file Streamlit app

```
import os

import streamlit as st
from utils import generate_data

# {{docs-fragment streamlit-app}}
all_columns = ["Apples", "Orange", "Pineapple"]
with st.container(border=True):
    columns = st.multiselect("Columns", all_columns, default=all_columns)

all_data = st.cache_data(generate_data)(columns=all_columns, seed=101)

data = all_data[columns]

tab1, tab2 = st.tabs(["Chart", "Dataframe"])
tab1.line_chart(data, height=250)
tab2.dataframe(data, height=250, use_container_width=True)
st.write(f"Environment: {os.environ}")
# {{/docs-fragment streamlit-app}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/streamlit/main.py*

```
import numpy as np
import pandas as pd

# {{docs-fragment utils-function}}
def generate_data(columns: list[str], seed: int = 42):
    rng = np.random.default_rng(seed)
    data = pd.DataFrame(rng.random(size=(20, len(columns))), columns=columns)
    return data
# {{/docs-fragment utils-function}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/streamlit/utils.py*

### Deploying multi-file Streamlit app

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""A custom Streamlit app with multiple files."""

import pathlib
import flyte
import flyte.app

# {{docs-fragment app-env}}
image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
    "streamlit==1.41.1",
    "pandas==2.2.3",
    "numpy==2.2.3",
)

app_env = flyte.app.AppEnvironment(
    name="streamlit-multi-file-app",
    image=image,
    args="streamlit run main.py --server.port 8080",
    port=8080,
    include=["main.py", "utils.py"],  # Include your app files
    resources=flyte.Resources(cpu="1", memory="1Gi"),
    requires_auth=False,
)
# {{/docs-fragment app-env}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    app = flyte.deploy(app_env)
    print(f"Deployed app: {app[0].summary_repr()}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/streamlit/multi_file_streamlit.py*

## Complex multi-file example

Here's a more complex example with multiple modules:

### Project structure

```
project/
├── app.py
├── models/
│   ├── __init__.py
│   └── user.py
├── services/
│   ├── __init__.py
│   └── auth.py
└── utils/
    ├── __init__.py
    └── helpers.py
```

### Example code

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
# ]
# ///

"""Complex multi-file FastAPI app example."""

from pathlib import Path
from fastapi import FastAPI
from models.user import User
from services.auth import authenticate
from utils.helpers import format_response

import flyte
from flyte.app.extras import FastAPIAppEnvironment

# {{docs-fragment complex-app}}
app = FastAPI(title="Complex Multi-file App")

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    user = User(id=user_id, name="John Doe")
    return format_response(user)
# {{/docs-fragment complex-app}}

# {{docs-fragment complex-env}}
app_env = FastAPIAppEnvironment(
    name="complex-app",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
        "pydantic",
    ),
    # Include all necessary files
    include=[
        "app.py",
        "models/",
        "services/",
        "utils/",
    ],
    resources=flyte.Resources(cpu=1, memory="512Mi"),
)
# {{/docs-fragment complex-env}}

if __name__ == "__main__":
    flyte.init_from_config(root_dir=Path(__file__).parent)
    app_deployment = flyte.deploy(app_env)
    print(f"Deployed: {app_deployment[0].summary_repr()}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/complex_multi_file/app.py*

```
# {{docs-fragment user-model}}
from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str
# {{/docs-fragment user-model}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/complex_multi_file/models/user.py*

```
# {{docs-fragment auth-service}}
def authenticate(token: str) -> bool:
    """Authenticate a user by token."""
    # ... authentication logic ...
    return True
# {{/docs-fragment auth-service}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/complex_multi_file/services/auth.py*

```
# {{docs-fragment helpers}}
def format_response(data):
    """Format a response with standard structure."""
    return {"data": data, "status": "success"}
# {{/docs-fragment helpers}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/complex_multi_file/utils/helpers.py*

### Deploying complex app

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
# ]
# ///

"""Complex multi-file FastAPI app example."""

from pathlib import Path
from fastapi import FastAPI
from models.user import User
from services.auth import authenticate
from utils.helpers import format_response

import flyte
from flyte.app.extras import FastAPIAppEnvironment

# {{docs-fragment complex-app}}
app = FastAPI(title="Complex Multi-file App")

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    user = User(id=user_id, name="John Doe")
    return format_response(user)
# {{/docs-fragment complex-app}}

# {{docs-fragment complex-env}}
app_env = FastAPIAppEnvironment(
    name="complex-app",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
        "pydantic",
    ),
    # Include all necessary files
    include=[
        "app.py",
        "models/",
        "services/",
        "utils/",
    ],
    resources=flyte.Resources(cpu=1, memory="512Mi"),
)
# {{/docs-fragment complex-env}}

if __name__ == "__main__":
    flyte.init_from_config(root_dir=Path(__file__).parent)
    app_deployment = flyte.deploy(app_env)
    print(f"Deployed: {app_deployment[0].summary_repr()}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/complex_multi_file/app.py*

## Best practices

1. **Use explicit includes**: For Streamlit apps, explicitly list all files in `include`
2. **Automatic discovery**: For FastAPI apps, `FastAPIAppEnvironment` handles most cases automatically
3. **Organize modules**: Use proper Python package structure with `__init__.py` files
4. **Test locally**: Test your multi-file app locally before deploying
5. **Include all dependencies**: Include all files that your app imports

## Troubleshooting

**Import errors:**
- Verify all files are included in the `include` parameter
- Check that file paths are correct (relative to app definition file)
- Ensure `__init__.py` files are included for packages

**Module not found:**
- Add missing files to the `include` list
- Check that import paths match the file structure
- Verify that the image includes all necessary packages

**File not found at runtime:**
- Ensure all referenced files are included
- Check mount paths for file/directory inputs
- Verify file paths are relative to the app root directory


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/build-apps/app-usage-patterns ===

# App usage patterns

Apps and tasks can interact in various ways: calling each other via HTTP, webhooks, WebSockets, or direct browser usage. This page describes the different patterns and when to use them.

## Patterns overview

1. **Build apps > App usage patterns > Call app from task**: A task makes HTTP requests to an app
2. **Build apps > App usage patterns > Call task from app (webhooks / APIs)**: An app triggers task execution via the Flyte SDK
3. **Build apps > App usage patterns > Call app from app**: One app makes HTTP requests to another app
4. **Build apps > App usage patterns > WebSocket-based patterns**: Real-time, bidirectional communication
5. **Browser-based access**: Users access apps directly through the browser

## Call app from task

Tasks can call apps by making HTTP requests to the app's endpoint. This is useful when:
- You need to use a long-running service during task execution
- You want to call a model serving endpoint from a batch processing task
- You need to interact with an API from a workflow

### Example: Task calling an app

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
#    "httpx",
# ]
# ///

"""Example of a task calling an app."""

import pathlib
import httpx
from fastapi import FastAPI
import flyte
from flyte.app.extras import FastAPIAppEnvironment

app = FastAPI(title="Add One", description="Adds one to the input", version="1.0.0")

image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages("fastapi", "uvicorn", "httpx")

# {{docs-fragment app-definition}}
app_env = FastAPIAppEnvironment(
    name="add-one-app",
    app=app,
    description="Adds one to the input",
    image=image,
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
)
# {{/docs-fragment app-definition}}

# {{docs-fragment task-env}}
task_env = flyte.TaskEnvironment(
    name="add_one_task_env",
    image=image,
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    depends_on=[app_env],  # Ensure app is deployed before task runs
)
# {{/docs-fragment task-env}}

# {{docs-fragment app-endpoint}}
@app.get("/")
async def add_one(x: int) -> dict[str, int]:
    """Main endpoint for the add-one app."""
    return {"result": x + 1}
# {{/docs-fragment app-endpoint}}

# {{docs-fragment task}}
@task_env.task
async def add_one_task(x: int) -> int:
    print(f"Calling app at {app_env.endpoint}")
    async with httpx.AsyncClient() as client:
        response = await client.get(app_env.endpoint, params={"x": x})
        response.raise_for_status()
        return response.json()["result"]
# {{/docs-fragment task}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    deployments = flyte.deploy(task_env)
    print(f"Deployed task environment: {deployments}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/task_calling_app.py*

Key points:
- The task environment uses `depends_on=[app_env]` to ensure the app is deployed first
- Access the app endpoint via `app_env.endpoint`
- Use standard HTTP client libraries (like `httpx`) to make requests

## Call task from app (webhooks / APIs)

Apps can trigger task execution using the Flyte SDK. This is useful for:

- Webhooks that trigger workflows
- APIs that need to run batch jobs
- Services that need to execute tasks asynchronously

Webhooks are HTTP endpoints that trigger actions in response to external events. Flyte apps can serve as webhook endpoints that trigger task runs, workflows, or other operations.

### Example: Basic webhook app

Here's a simple webhook that triggers Flyte tasks:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
# ]
# ///

"""A webhook that triggers Flyte tasks."""

import pathlib
from fastapi import FastAPI, HTTPException, Security
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from starlette import status
import os
from contextlib import asynccontextmanager
import flyte
import flyte.remote as remote
from flyte.app.extras import FastAPIAppEnvironment

# {{docs-fragment auth}}
WEBHOOK_API_KEY = os.getenv("WEBHOOK_API_KEY", "test-api-key")
security = HTTPBearer()

async def verify_token(
    credentials: HTTPAuthorizationCredentials = Security(security),
) -> HTTPAuthorizationCredentials:
    """Verify the API key from the bearer token."""
    if credentials.credentials != WEBHOOK_API_KEY:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Could not validate credentials",
        )
    return credentials
# {{/docs-fragment auth}}

# {{docs-fragment lifespan}}
@asynccontextmanager
async def lifespan(app: FastAPI):
    """Initialize Flyte before accepting requests."""
    await flyte.init_in_cluster.aio()
    yield
    # Cleanup if needed
# {{/docs-fragment lifespan}}

# {{docs-fragment app}}
app = FastAPI(
    title="Flyte Webhook Runner",
    description="A webhook service that triggers Flyte task runs",
    version="1.0.0",
    lifespan=lifespan,
)

@app.get("/health")
async def health_check():
    """Health check endpoint."""
    return {"status": "healthy"}
# {{/docs-fragment app}}

# {{docs-fragment webhook-endpoint}}
@app.post("/run-task/{project}/{domain}/{name}/{version}")
async def run_task(
    project: str,
    domain: str,
    name: str,
    version: str,
    inputs: dict,
    credentials: HTTPAuthorizationCredentials = Security(verify_token),
):
    """
    Trigger a Flyte task run via webhook.

    Returns information about the launched run.
    """
    # Fetch the task
    task = remote.Task.get(
        project=project,
        domain=domain,
        name=name,
        version=version,
    )

    # Run the task
    run = await flyte.run.aio(task, **inputs)

    return {
        "url": run.url,
        "id": run.id,
        "status": "started",
    }
# {{/docs-fragment webhook-endpoint}}

# {{docs-fragment env}}
env = FastAPIAppEnvironment(
    name="webhook-runner",
    app=app,
    description="A webhook service that triggers Flyte task runs",
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
    ),
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,  # We handle auth in the app
    env_vars={"WEBHOOK_API_KEY": os.getenv("WEBHOOK_API_KEY", "test-api-key")},
)
# {{/docs-fragment env}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    app_deployment = flyte.deploy(env)
    print(f"Deployed webhook: {app_deployment[0].summary_repr()}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/webhook/basic_webhook.py*

Once deployed, you can trigger tasks via HTTP POST:

```bash
curl -X POST "https://your-webhook-url/run-task/flytesnacks/development/my_task/v1" \
  -H "Authorization: Bearer test-api-key" \
  -H "Content-Type: application/json" \
  -d '{"input_key": "input_value"}'
```

Response:

```json
{
  "url": "https://console.union.ai/...",
  "id": "abc123",
  "status": "started"
}
```

### Advanced webhook patterns

**Webhook with validation**

Use Pydantic for input validation:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
# ]
# ///

"""A webhook with Pydantic validation."""

import pathlib
from fastapi import FastAPI, HTTPException, Security
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from starlette import status
import os
from contextlib import asynccontextmanager
from pydantic import BaseModel
import flyte
import flyte.remote as remote
from flyte.app.extras import FastAPIAppEnvironment

WEBHOOK_API_KEY = os.getenv("WEBHOOK_API_KEY", "test-api-key")
security = HTTPBearer()

async def verify_token(
    credentials: HTTPAuthorizationCredentials = Security(security),
) -> HTTPAuthorizationCredentials:
    """Verify the API key from the bearer token."""
    if credentials.credentials != WEBHOOK_API_KEY:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Could not validate credentials",
        )
    return credentials

@asynccontextmanager
async def lifespan(app: FastAPI):
    """Initialize Flyte before accepting requests."""
    await flyte.init_in_cluster.aio()
    yield

app = FastAPI(
    title="Flyte Webhook Runner with Validation",
    description="A webhook service that triggers Flyte task runs with Pydantic validation",
    version="1.0.0",
    lifespan=lifespan,
)

# {{docs-fragment validation-model}}
class TaskInput(BaseModel):
    data: dict
    priority: int = 0
# {{/docs-fragment validation-model}}

# {{docs-fragment validated-webhook}}
@app.post("/run-task/{project}/{domain}/{name}/{version}")
async def run_task(
    project: str,
    domain: str,
    name: str,
    version: str,
    inputs: TaskInput,  # Validated input
    credentials: HTTPAuthorizationCredentials = Security(verify_token),
):
    task = remote.Task.get(
        project=project,
        domain=domain,
        name=name,
        version=version,
    )

    run = await flyte.run.aio(task, **inputs.model_dump())

    return {
        "run_id": run.id,
        "url": run.url,
    }
# {{/docs-fragment validated-webhook}}

env = FastAPIAppEnvironment(
    name="webhook-with-validation",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
    ),
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
    env_vars={"WEBHOOK_API_KEY": os.getenv("WEBHOOK_API_KEY", "test-api-key")},
)

if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    app_deployment = flyte.deploy(env)
    print(f"Deployed webhook: {app_deployment[0].summary_repr()}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/webhook_validation.py*

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
# ]
# ///

"""A webhook with Pydantic validation."""

import pathlib
from fastapi import FastAPI, HTTPException, Security
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from starlette import status
import os
from contextlib import asynccontextmanager
from pydantic import BaseModel
import flyte
import flyte.remote as remote
from flyte.app.extras import FastAPIAppEnvironment

WEBHOOK_API_KEY = os.getenv("WEBHOOK_API_KEY", "test-api-key")
security = HTTPBearer()

async def verify_token(
    credentials: HTTPAuthorizationCredentials = Security(security),
) -> HTTPAuthorizationCredentials:
    """Verify the API key from the bearer token."""
    if credentials.credentials != WEBHOOK_API_KEY:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Could not validate credentials",
        )
    return credentials

@asynccontextmanager
async def lifespan(app: FastAPI):
    """Initialize Flyte before accepting requests."""
    await flyte.init_in_cluster.aio()
    yield

app = FastAPI(
    title="Flyte Webhook Runner with Validation",
    description="A webhook service that triggers Flyte task runs with Pydantic validation",
    version="1.0.0",
    lifespan=lifespan,
)

# {{docs-fragment validation-model}}
class TaskInput(BaseModel):
    data: dict
    priority: int = 0
# {{/docs-fragment validation-model}}

# {{docs-fragment validated-webhook}}
@app.post("/run-task/{project}/{domain}/{name}/{version}")
async def run_task(
    project: str,
    domain: str,
    name: str,
    version: str,
    inputs: TaskInput,  # Validated input
    credentials: HTTPAuthorizationCredentials = Security(verify_token),
):
    task = remote.Task.get(
        project=project,
        domain=domain,
        name=name,
        version=version,
    )

    run = await flyte.run.aio(task, **inputs.model_dump())

    return {
        "run_id": run.id,
        "url": run.url,
    }
# {{/docs-fragment validated-webhook}}

env = FastAPIAppEnvironment(
    name="webhook-with-validation",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
    ),
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
    env_vars={"WEBHOOK_API_KEY": os.getenv("WEBHOOK_API_KEY", "test-api-key")},
)

if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    app_deployment = flyte.deploy(env)
    print(f"Deployed webhook: {app_deployment[0].summary_repr()}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/webhook_validation.py*

**Webhook with response waiting**

Wait for task completion:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
# ]
# ///

"""A webhook that waits for task completion."""

import pathlib
from fastapi import FastAPI, HTTPException, Security
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from starlette import status
import os
from contextlib import asynccontextmanager
import flyte
import flyte.remote as remote
from flyte.app.extras import FastAPIAppEnvironment

WEBHOOK_API_KEY = os.getenv("WEBHOOK_API_KEY", "test-api-key")
security = HTTPBearer()

async def verify_token(
    credentials: HTTPAuthorizationCredentials = Security(security),
) -> HTTPAuthorizationCredentials:
    """Verify the API key from the bearer token."""
    if credentials.credentials != WEBHOOK_API_KEY:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Could not validate credentials",
        )
    return credentials

@asynccontextmanager
async def lifespan(app: FastAPI):
    """Initialize Flyte before accepting requests."""
    await flyte.init_in_cluster.aio()
    yield

app = FastAPI(
    title="Flyte Webhook Runner (Wait for Completion)",
    description="A webhook service that triggers Flyte task runs and waits for completion",
    version="1.0.0",
    lifespan=lifespan,
)

# {{docs-fragment wait-webhook}}
@app.post("/run-task-and-wait/{project}/{domain}/{name}/{version}")
async def run_task_and_wait(
    project: str,
    domain: str,
    name: str,
    version: str,
    inputs: dict,
    credentials: HTTPAuthorizationCredentials = Security(verify_token),
):
    task = remote.Task.get(
        project=project,
        domain=domain,
        name=name,
        version=version,
    )

    run = await flyte.run.aio(task, **inputs)
    run.wait()  # Wait for completion

    return {
        "run_id": run.id,
        "url": run.url,
        "status": run.status,
        "outputs": run.outputs(),
    }
# {{/docs-fragment wait-webhook}}

env = FastAPIAppEnvironment(
    name="webhook-wait-completion",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
    ),
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
    env_vars={"WEBHOOK_API_KEY": os.getenv("WEBHOOK_API_KEY", "test-api-key")},
)

if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    app_deployment = flyte.deploy(env)
    print(f"Deployed webhook: {app_deployment[0].summary_repr()}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/webhook_wait.py*

**Webhook with secret management**

Use Flyte secrets for API keys:

```python
env = FastAPIAppEnvironment(
    name="webhook-runner",
    app=app,
    secrets=flyte.Secret(key="webhook-api-key", as_env_var="WEBHOOK_API_KEY"),
    # ...
)
```

Then access in your app:

```python
WEBHOOK_API_KEY = os.getenv("WEBHOOK_API_KEY")
```

### Webhook security and best practices

- **Authentication**: Always secure webhooks with authentication (API keys, tokens, etc.).
- **Input validation**: Validate webhook inputs using Pydantic models.
- **Error handling**: Handle errors gracefully and return meaningful error messages.
- **Async operations**: Use async/await for I/O operations.
- **Health checks**: Include health check endpoints.
- **Logging**: Log webhook requests for debugging and auditing.
- **Rate limiting**: Consider implementing rate limiting for production.

Security considerations:

- Store API keys in Flyte secrets, not in code.
- Always use HTTPS in production.
- Validate all inputs to prevent injection attacks.
- Implement proper access control mechanisms.
- Log all webhook invocations for security auditing.

### Example: GitHub webhook

Here's an example webhook that triggers tasks based on GitHub events:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
# ]
# ///

"""A GitHub webhook that triggers Flyte tasks based on GitHub events."""

import pathlib
import hmac
import hashlib
import os
from contextlib import asynccontextmanager
from fastapi import FastAPI, Request, Header, HTTPException
import flyte
import flyte.remote as remote
from flyte.app.extras import FastAPIAppEnvironment

@asynccontextmanager
async def lifespan(app: FastAPI):
    """Initialize Flyte before accepting requests."""
    await flyte.init_in_cluster.aio()
    yield

app = FastAPI(
    title="GitHub Webhook Handler",
    description="Triggers Flyte tasks based on GitHub events",
    version="1.0.0",
    lifespan=lifespan,
)

# {{docs-fragment github-webhook}}
@app.post("/github-webhook")
async def github_webhook(
    request: Request,
    x_hub_signature_256: str = Header(None),
):
    """Handle GitHub webhook events."""
    body = await request.body()

    # Verify signature
    secret = os.getenv("GITHUB_WEBHOOK_SECRET")
    signature = hmac.new(
        secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()

    expected_signature = f"sha256={signature}"
    if not hmac.compare_digest(x_hub_signature_256, expected_signature):
        raise HTTPException(status_code=403, detail="Invalid signature")

    # Process webhook
    event = await request.json()
    event_type = request.headers.get("X-GitHub-Event")

    if event_type == "push":
        # Trigger deployment task
        task = remote.Task.get(
            project="my-project",
            domain="development",
            name="deploy-task",
            version="v1",
        )
        run = await flyte.run.aio(task, commit=event["after"])
        return {"run_id": run.id, "url": run.url}

    return {"status": "ignored"}
# {{/docs-fragment github-webhook}}

# {{docs-fragment env}}
env = FastAPIAppEnvironment(
    name="github-webhook",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
    ),
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
    secrets=flyte.Secret(key="GITHUB_WEBHOOK_SECRET", as_env_var="GITHUB_WEBHOOK_SECRET"),
)
# {{/docs-fragment env}}

if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    app_deployment = flyte.deploy(env)
    print(f"Deployed GitHub webhook: {app_deployment[0].summary_repr()}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/github_webhook.py*

### Gradio agent UI

For AI agents, a Gradio app lets you build an interactive UI that kicks off agent runs. The app uses `flyte.with_runcontext()` to run the agent task either locally or on a remote cluster, controlled by an environment variable.

```python
import os
import flyte
import flyte.app
from research_agent import agent

RUN_MODE = os.getenv("RUN_MODE", "remote")

serving_env = flyte.app.AppEnvironment(
    name="research-agent-ui",
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "gradio", "langchain-core", "langchain-openai", "langgraph",
    ),
    secrets=flyte.Secret(key="OPENAI_API_KEY", as_env_var="OPENAI_API_KEY"),
    port=7860,
)

def run_query(request: str):
    """Kick off the agent as a Flyte task."""
    result = flyte.with_runcontext(mode=RUN_MODE).run(agent, request=request)
    result.wait()
    return result.outputs()[0]

@serving_env.server
def app_server():
    create_demo().launch(server_name="0.0.0.0", server_port=7860)

if __name__ == "__main__":
    create_demo().launch()
```

The `RUN_MODE` variable gives you a smooth development progression:

1. **Fully local**: `RUN_MODE=local python agent_app.py`. Everything runs in your local Python environment, great for rapid iteration.
2. **Local app, remote task**: `python agent_app.py`. The UI runs locally but the agent executes on the cluster with full compute resources.
3. **Full remote**: `flyte deploy agent_app.py serving_env`. Both the UI and agent run on the cluster.

## Call app from app

Apps can call other apps by making HTTP requests. This is useful for:
- Microservice architectures
- Proxy/gateway patterns
- A/B testing setups
- Service composition

### Example: App calling another app

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
#    "httpx",
# ]
# ///

"""Example of one app calling another app."""

import httpx
from fastapi import FastAPI
import pathlib
import flyte
from flyte.app.extras import FastAPIAppEnvironment

image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
    "fastapi", "uvicorn", "httpx"
)

# {{docs-fragment backend-app}}
app1 = FastAPI(
    title="App 1",
    description="A FastAPI app that runs some computations",
)

env1 = FastAPIAppEnvironment(
    name="app1-is-called-by-app2",
    app=app1,
    image=image,
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
)
# {{/docs-fragment backend-app}}

# {{docs-fragment frontend-app}}
app2 = FastAPI(
    title="App 2",
    description="A FastAPI app that proxies requests to another FastAPI app",
)

env2 = FastAPIAppEnvironment(
    name="app2-calls-app1",
    app=app2,
    image=image,
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
    depends_on=[env1],  # Depends on backend-api
)
# {{/docs-fragment frontend-app}}

# {{docs-fragment backend-endpoint}}
@app1.get("/greeting/{name}")
async def greeting(name: str) -> str:
    return f"Hello, {name}!"
# {{/docs-fragment backend-endpoint}}

# {{docs-fragment frontend-endpoints}}
@app2.get("/app1-endpoint")
async def get_app1_endpoint() -> str:
    return env1.endpoint  # Access the backend endpoint

@app2.get("/greeting/{name}")
async def greeting_proxy(name: str):
    """Proxy that calls the backend app."""
    async with httpx.AsyncClient() as client:
        response = await client.get(f"{env1.endpoint}/greeting/{name}")
        response.raise_for_status()
        return response.json()
# {{/docs-fragment frontend-endpoints}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    deployments = flyte.deploy(env2)
    print(f"Deployed FastAPI app: {deployments[0].env_repr()}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/app_calling_app.py*

Key points:
- Use `depends_on=[env1]` to ensure dependencies are deployed first
- Access the app endpoint via `env1.endpoint`
- Use HTTP clients (like `httpx`) to make requests between apps

### Using AppEndpoint parameter

You can pass app endpoints as parameters for more flexibility:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
#    "httpx",
# ]
# ///

"""Example of one app calling another app."""

import os
import httpx
from fastapi import FastAPI
import pathlib
import flyte
from flyte.app.extras import FastAPIAppEnvironment

image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
    "fastapi", "uvicorn", "httpx"
)

# {{docs-fragment backend-app}}
app1 = FastAPI(
    title="App 1",
    description="A FastAPI app that runs some computations",
)

env1 = FastAPIAppEnvironment(
    name="app1-is-called-by-app2",
    app=app1,
    image=image,
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
)

@app1.get("/greeting/{name}")
async def greeting(name: str) -> str:
    return f"Hello, {name}!"
# {{/docs-fragment backend-app}}

# {{docs-fragment using-app-endpoint}}
app2 = FastAPI(
    title="App 2",
    description="A FastAPI app that proxies requests to another FastAPI app",
)

env2 = FastAPIAppEnvironment(
    name="app2-calls-app1",
    app=app2,
    image=image,
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
    depends_on=[env1],  # Depends on backend-api
    parameters=[
        flyte.app.Parameter(
            name="app1_endpoint",
            value=flyte.app.AppEndpoint(app_name="app1-is-called-by-app2"),
            env_var="APP1_ENDPOINT",
        ),
    ],
)

@app2.get("/greeting/{name}")
async def greeting_proxy(name: str):
    app1_endpoint = os.getenv("APP1_ENDPOINT")
    async with httpx.AsyncClient() as client:
        response = await client.get(f"{app1_endpoint}/greeting/{name}")
        response.raise_for_status()
        return response.json()
# {{/docs-fragment using-app-endpoint}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    deployments = flyte.deploy(env2)
    print(f"Deployed FastAPI app: {deployments[0].env_repr()}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/app_calling_app_endpoint.py*

## WebSocket-based patterns

WebSockets enable bidirectional, real-time communication between clients and servers. Flyte apps can serve WebSocket endpoints for real-time applications like chat, live updates, or streaming data.

### Example: Basic WebSocket app

Here's a simple FastAPI app with WebSocket support:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
#    "websockets",
# ]
# ///

"""A FastAPI app with WebSocket support."""

import pathlib
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
from fastapi.responses import HTMLResponse
import asyncio
import json
from datetime import UTC, datetime
import flyte
from flyte.app.extras import FastAPIAppEnvironment

app = FastAPI(
    title="Flyte WebSocket Demo",
    description="A FastAPI app with WebSocket support",
    version="1.0.0",
)

# {{docs-fragment connection-manager}}
class ConnectionManager:
    """Manages WebSocket connections."""

    def __init__(self):
        self.active_connections: list[WebSocket] = []

    async def connect(self, websocket: WebSocket):
        """Accept and register a new WebSocket connection."""
        await websocket.accept()
        self.active_connections.append(websocket)
        print(f"Client connected. Total: {len(self.active_connections)}")

    def disconnect(self, websocket: WebSocket):
        """Remove a WebSocket connection."""
        self.active_connections.remove(websocket)
        print(f"Client disconnected. Total: {len(self.active_connections)}")

    async def send_personal_message(self, message: str, websocket: WebSocket):
        """Send a message to a specific WebSocket connection."""
        await websocket.send_text(message)

    async def broadcast(self, message: str):
        """Broadcast a message to all active connections."""
        for connection in self.active_connections:
            try:
                await connection.send_text(message)
            except Exception as e:
                print(f"Error broadcasting: {e}")

manager = ConnectionManager()
# {{/docs-fragment connection-manager}}

# {{docs-fragment websocket-endpoint}}
@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    """WebSocket endpoint for real-time communication."""
    await manager.connect(websocket)

    try:
        # Send welcome message
        await manager.send_personal_message(
            json.dumps({
                "type": "system",
                "message": "Welcome! You are connected.",
                "timestamp": datetime.now(UTC).isoformat(),
            }),
            websocket,
        )

        # Listen for messages
        while True:
            data = await websocket.receive_text()

            # Echo back to sender
            await manager.send_personal_message(
                json.dumps({
                    "type": "echo",
                    "message": f"Echo: {data}",
                    "timestamp": datetime.now(UTC).isoformat(),
                }),
                websocket,
            )

            # Broadcast to all clients
            await manager.broadcast(
                json.dumps({
                    "type": "broadcast",
                    "message": f"Broadcast: {data}",
                    "timestamp": datetime.now(UTC).isoformat(),
                    "connections": len(manager.active_connections),
                })
            )

    except WebSocketDisconnect:
        manager.disconnect(websocket)
        await manager.broadcast(
            json.dumps({
                "type": "system",
                "message": "A client disconnected",
                "connections": len(manager.active_connections),
            })
        )
# {{/docs-fragment websocket-endpoint}}

# {{docs-fragment env}}
env = FastAPIAppEnvironment(
    name="websocket-app",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
        "websockets",
    ),
    resources=flyte.Resources(cpu=1, memory="1Gi"),
    requires_auth=False,
)
# {{/docs-fragment env}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    app_deployment = flyte.deploy(env)
    print(f"Deployed websocket app: {app_deployment[0].summary_repr()}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/websocket/basic_websocket.py*

### WebSocket patterns

**Echo server**

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
#    "websockets",
# ]
# ///

"""WebSocket patterns: echo, broadcast, streaming, and chat."""

import asyncio
import json
import random
from datetime import datetime, UTC
from pathlib import Path
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
import flyte
from flyte.app.extras import FastAPIAppEnvironment

app = FastAPI(
    title="WebSocket Patterns Demo",
    description="Demonstrates various WebSocket patterns",
    version="1.0.0",
)

# {{docs-fragment echo-server}}
@app.websocket("/echo")
async def echo(websocket: WebSocket):
    await websocket.accept()
    try:
        while True:
            data = await websocket.receive_text()
            await websocket.send_text(f"Echo: {data}")
    except WebSocketDisconnect:
        pass
# {{/docs-fragment echo-server}}

# Connection manager for broadcast
class ConnectionManager:
    def __init__(self):
        self.active_connections: list[WebSocket] = []

    async def connect(self, websocket: WebSocket):
        await websocket.accept()
        self.active_connections.append(websocket)

    def disconnect(self, websocket: WebSocket):
        self.active_connections.remove(websocket)

    async def broadcast(self, message: str):
        for connection in self.active_connections:
            try:
                await connection.send_text(message)
            except Exception:
                pass

manager = ConnectionManager()

# {{docs-fragment broadcast-server}}
@app.websocket("/broadcast")
async def broadcast(websocket: WebSocket):
    await manager.connect(websocket)
    try:
        while True:
            data = await websocket.receive_text()
            await manager.broadcast(data)
    except WebSocketDisconnect:
        manager.disconnect(websocket)
# {{/docs-fragment broadcast-server}}

# {{docs-fragment streaming-server}}
@app.websocket("/stream")
async def stream_data(websocket: WebSocket):
    await websocket.accept()
    try:
        while True:
            # Generate or fetch data
            data = {"timestamp": datetime.now(UTC).isoformat(), "value": random.random()}
            await websocket.send_json(data)
            await asyncio.sleep(1)  # Send update every second
    except WebSocketDisconnect:
        pass
# {{/docs-fragment streaming-server}}

# {{docs-fragment chat-room}}
class ChatRoom:
    def __init__(self, name: str):
        self.name = name
        self.connections: list[WebSocket] = []

    async def join(self, websocket: WebSocket):
        self.connections.append(websocket)

    async def leave(self, websocket: WebSocket):
        self.connections.remove(websocket)

    async def broadcast(self, message: str, sender: WebSocket):
        for connection in self.connections:
            if connection != sender:
                await connection.send_text(message)

rooms: dict[str, ChatRoom] = {}

@app.websocket("/chat/{room_name}")
async def chat(websocket: WebSocket, room_name: str):
    await websocket.accept()

    if room_name not in rooms:
        rooms[room_name] = ChatRoom(room_name)

    room = rooms[room_name]
    await room.join(websocket)

    try:
        while True:
            data = await websocket.receive_text()
            await room.broadcast(data, websocket)
    except WebSocketDisconnect:
        await room.leave(websocket)
# {{/docs-fragment chat-room}}

env = FastAPIAppEnvironment(
    name="websocket-patterns",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
        "websockets",
    ),
    resources=flyte.Resources(cpu=1, memory="1Gi"),
    requires_auth=False,
)

if __name__ == "__main__":
    flyte.init_from_config(root_dir=Path(__file__).parent)
    app_deployment = flyte.deploy(env)
    print(f"Deployed WebSocket patterns app: {app_deployment[0].summary_repr()}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/websocket/websocket_patterns.py*

**Broadcast server**

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
#    "websockets",
# ]
# ///

"""WebSocket patterns: echo, broadcast, streaming, and chat."""

import asyncio
import json
import random
from datetime import datetime, UTC
from pathlib import Path
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
import flyte
from flyte.app.extras import FastAPIAppEnvironment

app = FastAPI(
    title="WebSocket Patterns Demo",
    description="Demonstrates various WebSocket patterns",
    version="1.0.0",
)

# {{docs-fragment echo-server}}
@app.websocket("/echo")
async def echo(websocket: WebSocket):
    await websocket.accept()
    try:
        while True:
            data = await websocket.receive_text()
            await websocket.send_text(f"Echo: {data}")
    except WebSocketDisconnect:
        pass
# {{/docs-fragment echo-server}}

# Connection manager for broadcast
class ConnectionManager:
    def __init__(self):
        self.active_connections: list[WebSocket] = []

    async def connect(self, websocket: WebSocket):
        await websocket.accept()
        self.active_connections.append(websocket)

    def disconnect(self, websocket: WebSocket):
        self.active_connections.remove(websocket)

    async def broadcast(self, message: str):
        for connection in self.active_connections:
            try:
                await connection.send_text(message)
            except Exception:
                pass

manager = ConnectionManager()

# {{docs-fragment broadcast-server}}
@app.websocket("/broadcast")
async def broadcast(websocket: WebSocket):
    await manager.connect(websocket)
    try:
        while True:
            data = await websocket.receive_text()
            await manager.broadcast(data)
    except WebSocketDisconnect:
        manager.disconnect(websocket)
# {{/docs-fragment broadcast-server}}

# {{docs-fragment streaming-server}}
@app.websocket("/stream")
async def stream_data(websocket: WebSocket):
    await websocket.accept()
    try:
        while True:
            # Generate or fetch data
            data = {"timestamp": datetime.now(UTC).isoformat(), "value": random.random()}
            await websocket.send_json(data)
            await asyncio.sleep(1)  # Send update every second
    except WebSocketDisconnect:
        pass
# {{/docs-fragment streaming-server}}

# {{docs-fragment chat-room}}
class ChatRoom:
    def __init__(self, name: str):
        self.name = name
        self.connections: list[WebSocket] = []

    async def join(self, websocket: WebSocket):
        self.connections.append(websocket)

    async def leave(self, websocket: WebSocket):
        self.connections.remove(websocket)

    async def broadcast(self, message: str, sender: WebSocket):
        for connection in self.connections:
            if connection != sender:
                await connection.send_text(message)

rooms: dict[str, ChatRoom] = {}

@app.websocket("/chat/{room_name}")
async def chat(websocket: WebSocket, room_name: str):
    await websocket.accept()

    if room_name not in rooms:
        rooms[room_name] = ChatRoom(room_name)

    room = rooms[room_name]
    await room.join(websocket)

    try:
        while True:
            data = await websocket.receive_text()
            await room.broadcast(data, websocket)
    except WebSocketDisconnect:
        await room.leave(websocket)
# {{/docs-fragment chat-room}}

env = FastAPIAppEnvironment(
    name="websocket-patterns",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
        "websockets",
    ),
    resources=flyte.Resources(cpu=1, memory="1Gi"),
    requires_auth=False,
)

if __name__ == "__main__":
    flyte.init_from_config(root_dir=Path(__file__).parent)
    app_deployment = flyte.deploy(env)
    print(f"Deployed WebSocket patterns app: {app_deployment[0].summary_repr()}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/websocket/websocket_patterns.py*

**Real-time data streaming**

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
#    "websockets",
# ]
# ///

"""WebSocket patterns: echo, broadcast, streaming, and chat."""

import asyncio
import json
import random
from datetime import datetime, UTC
from pathlib import Path
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
import flyte
from flyte.app.extras import FastAPIAppEnvironment

app = FastAPI(
    title="WebSocket Patterns Demo",
    description="Demonstrates various WebSocket patterns",
    version="1.0.0",
)

# {{docs-fragment echo-server}}
@app.websocket("/echo")
async def echo(websocket: WebSocket):
    await websocket.accept()
    try:
        while True:
            data = await websocket.receive_text()
            await websocket.send_text(f"Echo: {data}")
    except WebSocketDisconnect:
        pass
# {{/docs-fragment echo-server}}

# Connection manager for broadcast
class ConnectionManager:
    def __init__(self):
        self.active_connections: list[WebSocket] = []

    async def connect(self, websocket: WebSocket):
        await websocket.accept()
        self.active_connections.append(websocket)

    def disconnect(self, websocket: WebSocket):
        self.active_connections.remove(websocket)

    async def broadcast(self, message: str):
        for connection in self.active_connections:
            try:
                await connection.send_text(message)
            except Exception:
                pass

manager = ConnectionManager()

# {{docs-fragment broadcast-server}}
@app.websocket("/broadcast")
async def broadcast(websocket: WebSocket):
    await manager.connect(websocket)
    try:
        while True:
            data = await websocket.receive_text()
            await manager.broadcast(data)
    except WebSocketDisconnect:
        manager.disconnect(websocket)
# {{/docs-fragment broadcast-server}}

# {{docs-fragment streaming-server}}
@app.websocket("/stream")
async def stream_data(websocket: WebSocket):
    await websocket.accept()
    try:
        while True:
            # Generate or fetch data
            data = {"timestamp": datetime.now(UTC).isoformat(), "value": random.random()}
            await websocket.send_json(data)
            await asyncio.sleep(1)  # Send update every second
    except WebSocketDisconnect:
        pass
# {{/docs-fragment streaming-server}}

# {{docs-fragment chat-room}}
class ChatRoom:
    def __init__(self, name: str):
        self.name = name
        self.connections: list[WebSocket] = []

    async def join(self, websocket: WebSocket):
        self.connections.append(websocket)

    async def leave(self, websocket: WebSocket):
        self.connections.remove(websocket)

    async def broadcast(self, message: str, sender: WebSocket):
        for connection in self.connections:
            if connection != sender:
                await connection.send_text(message)

rooms: dict[str, ChatRoom] = {}

@app.websocket("/chat/{room_name}")
async def chat(websocket: WebSocket, room_name: str):
    await websocket.accept()

    if room_name not in rooms:
        rooms[room_name] = ChatRoom(room_name)

    room = rooms[room_name]
    await room.join(websocket)

    try:
        while True:
            data = await websocket.receive_text()
            await room.broadcast(data, websocket)
    except WebSocketDisconnect:
        await room.leave(websocket)
# {{/docs-fragment chat-room}}

env = FastAPIAppEnvironment(
    name="websocket-patterns",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
        "websockets",
    ),
    resources=flyte.Resources(cpu=1, memory="1Gi"),
    requires_auth=False,
)

if __name__ == "__main__":
    flyte.init_from_config(root_dir=Path(__file__).parent)
    app_deployment = flyte.deploy(env)
    print(f"Deployed WebSocket patterns app: {app_deployment[0].summary_repr()}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/websocket/websocket_patterns.py*

**Chat application**

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
#    "websockets",
# ]
# ///

"""WebSocket patterns: echo, broadcast, streaming, and chat."""

import asyncio
import json
import random
from datetime import datetime, UTC
from pathlib import Path
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
import flyte
from flyte.app.extras import FastAPIAppEnvironment

app = FastAPI(
    title="WebSocket Patterns Demo",
    description="Demonstrates various WebSocket patterns",
    version="1.0.0",
)

# {{docs-fragment echo-server}}
@app.websocket("/echo")
async def echo(websocket: WebSocket):
    await websocket.accept()
    try:
        while True:
            data = await websocket.receive_text()
            await websocket.send_text(f"Echo: {data}")
    except WebSocketDisconnect:
        pass
# {{/docs-fragment echo-server}}

# Connection manager for broadcast
class ConnectionManager:
    def __init__(self):
        self.active_connections: list[WebSocket] = []

    async def connect(self, websocket: WebSocket):
        await websocket.accept()
        self.active_connections.append(websocket)

    def disconnect(self, websocket: WebSocket):
        self.active_connections.remove(websocket)

    async def broadcast(self, message: str):
        for connection in self.active_connections:
            try:
                await connection.send_text(message)
            except Exception:
                pass

manager = ConnectionManager()

# {{docs-fragment broadcast-server}}
@app.websocket("/broadcast")
async def broadcast(websocket: WebSocket):
    await manager.connect(websocket)
    try:
        while True:
            data = await websocket.receive_text()
            await manager.broadcast(data)
    except WebSocketDisconnect:
        manager.disconnect(websocket)
# {{/docs-fragment broadcast-server}}

# {{docs-fragment streaming-server}}
@app.websocket("/stream")
async def stream_data(websocket: WebSocket):
    await websocket.accept()
    try:
        while True:
            # Generate or fetch data
            data = {"timestamp": datetime.now(UTC).isoformat(), "value": random.random()}
            await websocket.send_json(data)
            await asyncio.sleep(1)  # Send update every second
    except WebSocketDisconnect:
        pass
# {{/docs-fragment streaming-server}}

# {{docs-fragment chat-room}}
class ChatRoom:
    def __init__(self, name: str):
        self.name = name
        self.connections: list[WebSocket] = []

    async def join(self, websocket: WebSocket):
        self.connections.append(websocket)

    async def leave(self, websocket: WebSocket):
        self.connections.remove(websocket)

    async def broadcast(self, message: str, sender: WebSocket):
        for connection in self.connections:
            if connection != sender:
                await connection.send_text(message)

rooms: dict[str, ChatRoom] = {}

@app.websocket("/chat/{room_name}")
async def chat(websocket: WebSocket, room_name: str):
    await websocket.accept()

    if room_name not in rooms:
        rooms[room_name] = ChatRoom(room_name)

    room = rooms[room_name]
    await room.join(websocket)

    try:
        while True:
            data = await websocket.receive_text()
            await room.broadcast(data, websocket)
    except WebSocketDisconnect:
        await room.leave(websocket)
# {{/docs-fragment chat-room}}

env = FastAPIAppEnvironment(
    name="websocket-patterns",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
        "websockets",
    ),
    resources=flyte.Resources(cpu=1, memory="1Gi"),
    requires_auth=False,
)

if __name__ == "__main__":
    flyte.init_from_config(root_dir=Path(__file__).parent)
    app_deployment = flyte.deploy(env)
    print(f"Deployed WebSocket patterns app: {app_deployment[0].summary_repr()}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/websocket/websocket_patterns.py*

### Using WebSockets with Flyte tasks

You can trigger Flyte tasks from WebSocket messages:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
#    "websockets",
# ]
# ///

"""A WebSocket app that triggers Flyte tasks and streams updates."""

import json
from pathlib import Path
from contextlib import asynccontextmanager
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
import flyte
import flyte.remote as remote
from flyte.app.extras import FastAPIAppEnvironment

@asynccontextmanager
async def lifespan(app: FastAPI):
    """Initialize Flyte before accepting requests."""
    await flyte.init_in_cluster.aio()
    yield

app = FastAPI(
    title="WebSocket Task Runner",
    description="Triggers Flyte tasks via WebSocket and streams updates",
    version="1.0.0",
    lifespan=lifespan,
)

# {{docs-fragment task-runner-websocket}}
@app.websocket("/task-runner")
async def task_runner(websocket: WebSocket):
    await websocket.accept()

    try:
        while True:
            # Receive task request
            message = await websocket.receive_text()
            request = json.loads(message)

            # Trigger Flyte task
            task = remote.Task.get(
                project=request["project"],
                domain=request["domain"],
                name=request["task"],
                version=request["version"],
            )

            run = await flyte.run.aio(task, **request["inputs"])

            # Send run info back
            await websocket.send_json({
                "run_id": run.id,
                "url": run.url,
                "status": "started",
            })

            # Optionally stream updates
            async for update in run.stream():
                await websocket.send_json({
                    "status": update.status,
                    "message": update.message,
                })

    except WebSocketDisconnect:
        pass
# {{/docs-fragment task-runner-websocket}}

env = FastAPIAppEnvironment(
    name="task-runner-websocket",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
        "websockets",
    ),
    resources=flyte.Resources(cpu=1, memory="1Gi"),
    requires_auth=False,
)

if __name__ == "__main__":
    flyte.init_from_config(root_dir=Path(__file__).parent)
    app_deployment = flyte.deploy(env)
    print(f"Deployed WebSocket task runner: {app_deployment[0].summary_repr()}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/websocket/task_runner_websocket.py*

### WebSocket client example

Connect from Python:

```python
import asyncio
import websockets
import json

async def client():
    uri = "ws://your-app-url/ws"
    async with websockets.connect(uri) as websocket:
        # Send message
        await websocket.send("Hello, Server!")
        
        # Receive message
        response = await websocket.recv()
        print(f"Received: {response}")

asyncio.run(client())
```

## Browser-based apps

For browser-based apps (like Streamlit), users interact directly through the web interface. The app URL is accessible in a browser, and users interact with the UI directly - no API calls needed from other services.

To access a browser-based app:
1. Deploy the app
2. Navigate to the app URL in a browser
3. Interact with the UI directly

## Best practices

1. **Use `depends_on`**: Always specify dependencies to ensure proper deployment order.
2. **Handle errors**: Implement proper error handling for HTTP requests.
3. **Use async clients**: Use async HTTP clients (`httpx.AsyncClient`) in async contexts.
4. **Initialize Flyte**: For apps calling tasks, initialize Flyte in the app's startup.
5. **Endpoint access**: Use `app_env.endpoint` or `AppEndpoint` parameter for accessing app URLs.
6. **Authentication**: Consider authentication when apps call each other (set `requires_auth=True` if needed).
7. **Webhook security**: Secure webhooks with auth, validation, and HTTPS.
8. **WebSocket robustness**: Implement connection management, heartbeats, and rate limiting.

## Summary

| Pattern | Use Case | Implementation |
|---------|----------|----------------|
| Task → App | Batch processing using inference services | HTTP requests from task |
| App → Task | Webhooks, APIs triggering workflows | Flyte SDK in app |
| App → App | Microservices, proxies, agent routers, LLM routers | HTTP requests between apps |
| Browser → App | User-facing dashboards | Direct browser access |

Choose the pattern that best fits your architecture and requirements.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/build-apps/secret-based-authentication ===

# Secret-based authentication

In this guide, we'll deploy a FastAPI app that uses API key authentication with Flyte secrets. This allows you to invoke the endpoint from the public internet securely without exposing API keys in your code.

## Create the secret

Before defining and deploying the app, you need to create the `API_KEY` secret in Flyte. This secret will store your API key securely.

Create the secret using the Flyte CLI:

```bash
flyte create secret API_KEY <your-api-key-value>
```

For example:

```bash
flyte create secret API_KEY my-secret-api-key-12345
```

> [!NOTE]
> The secret name `API_KEY` must match the key specified in the `flyte.Secret()` call in your code. The secret will be available to your app as the environment variable specified in `as_env_var`.

## Define the FastAPI app

Here's a simple FastAPI app that uses `HTTPAuthorizationCredentials` to authenticate requests using a secret stored in Flyte:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
# ]
# ///

"""Basic FastAPI authentication using dependency injection."""

from fastapi import FastAPI, HTTPException, Security
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from starlette import status
import os
import pathlib
import flyte
from flyte.app.extras import FastAPIAppEnvironment

# Get API key from environment variable (loaded from Flyte secret)
# The secret must be created using: flyte create secret API_KEY <your-api-key-value>
API_KEY = os.getenv("API_KEY")
security = HTTPBearer()

async def verify_token(
    credentials: HTTPAuthorizationCredentials = Security(security),
) -> HTTPAuthorizationCredentials:
    """Verify the API key from the bearer token."""
    if not API_KEY:
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail="API_KEY not configured",
        )
    if credentials.credentials != API_KEY:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Could not validate credentials",
        )
    return credentials

app = FastAPI(title="Authenticated API")

@app.get("/public")
async def public_endpoint():
    """Public endpoint that doesn't require authentication."""
    return {"message": "This is public"}

@app.get("/protected")
async def protected_endpoint(
    credentials: HTTPAuthorizationCredentials = Security(verify_token),
):
    """Protected endpoint that requires authentication."""
    return {
        "message": "This is protected",
        "user": credentials.credentials,
    }

env = FastAPIAppEnvironment(
    name="authenticated-api",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
    ),
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,  # We handle auth in the app
    secrets=flyte.Secret(key="API_KEY", as_env_var="API_KEY"),
)

if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    app_deployment = flyte.deploy(env)
    print(f"Deployed: {app_deployment[0].summary_repr()}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/basic_auth.py*

As you can see, we:

1. Define a `FastAPI` app
2. Create a `verify_token` function that verifies the API key from the Bearer token
3. Define endpoints that use the `verify_token` function to authenticate requests
4. Configure the `FastAPIAppEnvironment` with:
   - `requires_auth=False` - This allows the endpoint to be reached without going through Flyte's authentication, since we're handling authentication ourselves using the `API_KEY` secret
   - `secrets=flyte.Secret(key="API_KEY", as_env_var="API_KEY")` - This injects the secret value into the `API_KEY` environment variable at runtime

The key difference from using `env_vars` is that secrets are stored securely in Flyte's secret store and injected at runtime, rather than being passed as plain environment variables.

## Deploy the FastAPI app

Once the secret is created, you can deploy the FastAPI app. Make sure your `config.yaml` file is in the same directory as your script, then run:

```bash
python basic_auth.py
```

Or use the Flyte CLI:

```bash
flyte serve basic_auth.py
```

Deploying the application will stream the status to the console and display the app URL:

```
✨ Deploying Application: authenticated-api
🔎 Console URL: https://<union-tenant>/console/projects/my-project/domains/development/apps/fastapi-with-auth
[Status] Pending: App is pending deployment
[Status] Started: Service is ready
🚀 Deployed Endpoint: https://rough-meadow-97cf5.apps.<union-tenant>
```

## Invoke the endpoint

Once deployed, you can invoke the authenticated endpoint using curl:

```bash
curl -X GET "https://rough-meadow-97cf5.apps.<union-tenant>/protected" \
  -H "Authorization: Bearer <your-api-key-value>"
```

Replace `<your-api-key-value>` with the actual API key value you used when creating the secret.

For example, if you created the secret with value `my-secret-api-key-12345`:

```bash
curl -X GET "https://rough-meadow-97cf5.apps.<union-tenant>/protected" \
  -H "Authorization: Bearer my-secret-api-key-12345"
```

You should receive a response:

```json
{
  "message": "This is protected",
  "user": "my-secret-api-key-12345"
}
```

## Authentication for vLLM and SGLang apps

Both vLLM and SGLang apps support API key authentication through their native `--api-key` argument. This allows you to secure your LLM endpoints while keeping them accessible from the public internet.

### Create the authentication secret

Create a secret to store your API key:

```bash
flyte create secret AUTH_SECRET <your-api-key-value>
```

For example:

```bash
flyte create secret AUTH_SECRET my-llm-api-key-12345
```

### Deploy vLLM app with authentication

Here's how to deploy a vLLM app with API key authentication:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-vllm>=2.0.0b45",
# ]
# ///

"""vLLM app with API key authentication."""

import pathlib
from flyteplugins.vllm import VLLMAppEnvironment
import flyte

# The secret must be created using: flyte create secret AUTH_SECRET <your-api-key-value>
vllm_app = VLLMAppEnvironment(
    name="vllm-app-with-auth",
    model_hf_path="Qwen/Qwen3-0.6B",  # HuggingFace model path
    model_id="qwen3-0.6b",  # Model ID exposed by vLLM
    resources=flyte.Resources(
        cpu="4",
        memory="16Gi",
        gpu="L40s:1",  # GPU required for LLM serving
        disk="10Gi",
    ),
    scaling=flyte.app.Scaling(
        replicas=(0, 1),
        scaledown_after=300,  # Scale down after 5 minutes of inactivity
    ),
    # Disable Union's platform-level authentication so you can access the
    # endpoint from the public internet
    requires_auth=False,
    # Inject the secret as an environment variable
    secrets=flyte.Secret(key="AUTH_SECRET", as_env_var="AUTH_SECRET"),
    # Pass the API key to vLLM's --api-key argument
    # The $AUTH_SECRET will be replaced with the actual secret value at runtime
    extra_args=[
        "--api-key", "$AUTH_SECRET",
    ],
)

if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    app = flyte.serve(vllm_app)
    print(f"Deployed vLLM app: {app.url}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/vllm/vllm_with_auth.py*

Key points:

1. **`requires_auth=False`** - Disables Union's platform-level authentication so the endpoint can be accessed from the public internet
2. **`secrets=flyte.Secret(key="AUTH_SECRET", as_env_var="AUTH_SECRET")`** - Injects the secret as an environment variable
3. **`extra_args=["--api-key", "$AUTH_SECRET"]`** - Passes the API key to vLLM's `--api-key` argument. The `$AUTH_SECRET` will be replaced with the actual secret value at runtime

Deploy the app:

```bash
python vllm_with_auth.py
```

Or use the Flyte CLI:

```bash
flyte serve vllm_with_auth.py
```

### Deploy SGLang app with authentication

Here's how to deploy a SGLang app with API key authentication:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-sglang>=2.0.0b45",
# ]
# ///

"""SGLang app with API key authentication."""

import pathlib
from flyteplugins.sglang import SGLangAppEnvironment
import flyte

# The secret must be created using: flyte create secret AUTH_SECRET <your-api-key-value>
sglang_app = SGLangAppEnvironment(
    name="sglang-with-auth",
    model_hf_path="Qwen/Qwen3-0.6B",  # HuggingFace model path
    model_id="qwen3-0.6b",  # Model ID exposed by SGLang
    resources=flyte.Resources(
        cpu="4",
        memory="16Gi",
        gpu="L40s:1",  # GPU required for LLM serving
        disk="10Gi",
    ),
    scaling=flyte.app.Scaling(
        replicas=(0, 1),
        scaledown_after=300,  # Scale down after 5 minutes of inactivity
    ),
    # Disable Union's platform-level authentication so you can access the
    # endpoint from the public internet
    requires_auth=False,
    # Inject the secret as an environment variable
    secrets=flyte.Secret(key="AUTH_SECRET", as_env_var="AUTH_SECRET"),
    # Pass the API key to SGLang's --api-key argument
    # The $AUTH_SECRET will be replaced with the actual secret value at runtime
    extra_args=[
        "--api-key", "$AUTH_SECRET",
    ],
)

if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    app = flyte.serve(sglang_app)
    print(f"Deployed SGLang app: {app.url}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/sglang/sglang_with_auth.py*

The configuration is similar to vLLM:

1. **`requires_auth=False`** - Disables Union's platform-level authentication
2. **`secrets=flyte.Secret(key="AUTH_SECRET", as_env_var="AUTH_SECRET")`** - Injects the secret as an environment variable
3. **`extra_args=["--api-key", "$AUTH_SECRET"]`** - Passes the API key to SGLang's `--api-key` argument

Deploy the app:

```bash
python sglang_with_auth.py
```

Or use the Flyte CLI:

```bash
flyte serve sglang_with_auth.py
```

### Invoke authenticated LLM endpoints

Once deployed, you can invoke the authenticated endpoints using the OpenAI-compatible API format. Both vLLM and SGLang expose OpenAI-compatible endpoints.

For example, to make a chat completion request:

```bash
curl -X POST "https://your-app-url/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key-value>" \
  -d '{
    "model": "qwen3-0.6b",
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ]
  }'
```

Replace `<your-api-key-value>` with the actual API key value you used when creating the secret.

For example, if you created the secret with value `my-llm-api-key-12345`:

```bash
curl -X POST "https://your-app-url/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer my-llm-api-key-12345" \
  -d '{
    "model": "qwen3-0.6b",
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ]
  }'
```

You should receive a response with the model's completion.

> [!NOTE]
> The `$AUTH_SECRET` syntax in `extra_args` is automatically replaced with the actual secret value at runtime. This ensures the API key is never exposed in your code or configuration files.

## Accessing Swagger documentation

The app also includes a public health check endpoint and Swagger UI documentation:

- **Health check**: `https://your-app-url/health`
- **Swagger UI**: `https://your-app-url/docs`
- **ReDoc**: `https://your-app-url/redoc`

The Swagger UI will show an "Authorize" button where you can enter your Bearer token to test authenticated endpoints directly from the browser.

## Security best practices

1. **Use strong API keys**: Generate cryptographically secure random strings for your API keys
2. **Rotate keys regularly**: Periodically rotate your API keys for better security
3. **Scope secrets appropriately**: Use project/domain scoping when creating secrets if you want to limit access:
   ```bash
   flyte create secret --project my-project --domain development API_KEY my-secret-value
   ```
4. **Never commit secrets**: Always use Flyte secrets for API keys, never hardcode them in your code
5. **Use HTTPS**: Always use HTTPS in production (Flyte apps are served over HTTPS by default)

## Troubleshooting

**Authentication failing:**
- Verify the secret exists: `flyte get secret API_KEY`
- Check that the secret key name matches exactly (case-sensitive)
- Ensure you're using the correct Bearer token value
- Verify the `as_env_var` parameter matches the environment variable name in your code

**Secret not found:**
- Make sure you've created the secret before deploying the app
- Check the secret scope (organization vs project/domain) matches your app's project/domain
- Verify the secret name matches exactly (should be `API_KEY`)

**App not starting:**
- Check container logs for errors
- Verify all dependencies are installed in the image
- Ensure the secret is accessible in the app's project/domain

**LLM app authentication not working:**
- Verify the secret exists: `flyte get secret AUTH_SECRET`
- Check that `$AUTH_SECRET` is correctly specified in `extra_args` (note the `$` prefix)
- Ensure the secret name matches exactly (case-sensitive) in both the `flyte.Secret()` call and `extra_args`
- For vLLM, verify the `--api-key` argument is correctly passed
- For SGLang, verify the `--api-key` argument is correctly passed
- Check that `requires_auth=False` is set to allow public access

## Next steps

- Learn more about [managing secrets](../task-configuration/secrets) in Flyte
- See [app usage patterns](./app-usage-patterns#call-task-from-app-webhooks--apis) for webhook examples and authentication patterns
- Learn about [vLLM apps](./vllm-app) and [SGLang apps](./sglang-app) for serving LLMs


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/build-apps/streamlit-app ===

# Streamlit app

Streamlit is a popular framework for building interactive web applications and dashboards. Flyte makes it easy to deploy Streamlit apps as long-running services.

## Basic Streamlit app

The simplest way to deploy a Streamlit app is to use the built-in Streamlit "hello" demo:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""A basic Streamlit app using the built-in hello demo."""

# {{docs-fragment app-definition}}
import flyte
import flyte.app

image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages("streamlit==1.41.1")

app_env = flyte.app.AppEnvironment(
    name="streamlit-hello",
    image=image,
    args="streamlit hello --server.port 8080",
    port=8080,
    resources=flyte.Resources(cpu="1", memory="1Gi"),
    requires_auth=False,
)

if __name__ == "__main__":
    flyte.init_from_config()
    app = flyte.deploy(app_env)
    print(f"Deployed app: {app[0].summary_repr()}")
# {{/docs-fragment app-definition}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/streamlit/basic_streamlit.py*

This just serves the built-in Streamlit "hello" demo.

## Single-file Streamlit app

For a single-file Streamlit app, you can wrap the app code in a function and use the `args` parameter to specify the command to run the app.
Note that the command is running the file itself, and uses the `--server` flag to start the server.

This is useful when you have a relatively small and simple app that you want to deploy as a single file.

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "streamlit",
# ]
# ///

"""A single-script Streamlit app example."""

import sys
from pathlib import Path

import streamlit as st

import flyte
import flyte.app

# {{docs-fragment streamlit-app}}
def main():
    st.set_page_config(page_title="Simple Streamlit App", page_icon="🚀")

    st.title("Hello from Streamlit!")
    st.write("This is a simple single-script Streamlit app.")

    name = st.text_input("What's your name?", "World")
    st.write(f"Hello, {name}!")

    if st.button("Click me!"):
        st.balloons()
        st.success("Button clicked!")
# {{/docs-fragment streamlit-app}}

file_name = Path(__file__).name
# {{docs-fragment app-env}}
app_env = flyte.app.AppEnvironment(
    name="streamlit-single-script",
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages("streamlit==1.41.1"),
    args=[
        "streamlit",
        "run",
        file_name,
        "--server.port",
        "8080",
        "--",
        "--server",
    ],
    port=8080,
    resources=flyte.Resources(cpu="1", memory="1Gi"),
    requires_auth=False,
)
# {{/docs-fragment app-env}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    import logging
    import sys

    if "--server" in sys.argv:
        main()
    else:
        flyte.init_from_config(
            root_dir=Path(__file__).parent,
            log_level=logging.DEBUG,
        )
        app = flyte.serve(app_env)
        print(f"App URL: {app.url}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/streamlit/single_file_streamlit.py*

Note that the `if __name__ == "__main__"` block is used to both serve the `AppEnvironment` *and* run the app code via
the `streamlit run` command using the `--server` flag.

## Multi-file Streamlit app

When your streamlit application grows more complex, you may want to split your app into multiple files.
For a multi-file Streamlit app, use the `include` parameter to bundle your app files:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""A custom Streamlit app with multiple files."""

import pathlib
import flyte
import flyte.app

# {{docs-fragment app-env}}
image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
    "streamlit==1.41.1",
    "pandas==2.2.3",
    "numpy==2.2.3",
)

app_env = flyte.app.AppEnvironment(
    name="streamlit-multi-file-app",
    image=image,
    args="streamlit run main.py --server.port 8080",
    port=8080,
    include=["main.py", "utils.py"],  # Include your app files
    resources=flyte.Resources(cpu="1", memory="1Gi"),
    requires_auth=False,
)
# {{/docs-fragment app-env}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    app = flyte.deploy(app_env)
    print(f"Deployed app: {app[0].summary_repr()}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/streamlit/multi_file_streamlit.py*

Where your project structure looks like this:

```
project/
├── main.py           # Main Streamlit app
├── utils.py          # Utility functions
└── components.py     # Reusable components
```

Your `main.py` file would contain your Streamlit app code:

```
import os

import streamlit as st
from utils import generate_data

# {{docs-fragment streamlit-app}}
all_columns = ["Apples", "Orange", "Pineapple"]
with st.container(border=True):
    columns = st.multiselect("Columns", all_columns, default=all_columns)

all_data = st.cache_data(generate_data)(columns=all_columns, seed=101)

data = all_data[columns]

tab1, tab2 = st.tabs(["Chart", "Dataframe"])
tab1.line_chart(data, height=250)
tab2.dataframe(data, height=250, use_container_width=True)
st.write(f"Environment: {os.environ}")
# {{/docs-fragment streamlit-app}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/streamlit/main.py*

## Example: Data visualization dashboard

Here's a complete example of a Streamlit dashboard, all in a single file.

Define the streamlit app in the `main` function:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "streamlit",
#    "pandas",
#    "numpy",
# ]
# ///

"""A data visualization dashboard example using Streamlit."""

import sys
from pathlib import Path

import numpy as np
import pandas as pd
import streamlit as st

import flyte
import flyte.app

# {{docs-fragment streamlit-app}}
def main():
    st.set_page_config(page_title="Sales Dashboard", page_icon="📊")

    st.title("Sales Dashboard")

    # Load data
    @st.cache_data
    def load_data():
        return pd.DataFrame({
            "date": pd.date_range("2024-01-01", periods=100, freq="D"),
            "sales": np.random.randint(1000, 5000, 100),
        })

    data = load_data()

    # Sidebar filters
    st.sidebar.header("Filters")
    start_date = st.sidebar.date_input("Start date", value=data["date"].min())
    end_date = st.sidebar.date_input("End date", value=data["date"].max())

    # Filter data
    filtered_data = data[
        (data["date"] >= pd.Timestamp(start_date)) &
        (data["date"] <= pd.Timestamp(end_date))
    ]

    # Display metrics
    col1, col2, col3 = st.columns(3)
    with col1:
        st.metric("Total Sales", f"${filtered_data['sales'].sum():,.0f}")
    with col2:
        st.metric("Average Sales", f"${filtered_data['sales'].mean():,.0f}")
    with col3:
        st.metric("Days", len(filtered_data))

    # Chart
    st.line_chart(filtered_data.set_index("date")["sales"])

# {{/docs-fragment streamlit-app}}

# {{docs-fragment app-env}}
file_name = Path(__file__).name
app_env = flyte.app.AppEnvironment(
    name="sales-dashboard",
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "streamlit==1.41.1",
        "pandas==2.2.3",
        "numpy==2.2.3",
    ),
    args=["streamlit run", file_name, "--server.port", "8080", "--", "--server"],
    port=8080,
    resources=flyte.Resources(cpu="2", memory="2Gi"),
    requires_auth=False,
)
# {{/docs-fragment app-env}}

# {{docs-fragment serve}}
if __name__ == "__main__":
    import logging
    import sys

    if "--server" in sys.argv:
        main()
    else:
        flyte.init_from_config(
            root_dir=Path(__file__).parent,
            log_level=logging.DEBUG,
        )
        app = flyte.serve(app_env)
        print(f"Dashboard URL: {app.url}")
# {{/docs-fragment serve}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/streamlit/data_visualization_dashboard.py*

Define the `AppEnvironment` to serve the app:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "streamlit",
#    "pandas",
#    "numpy",
# ]
# ///

"""A data visualization dashboard example using Streamlit."""

import sys
from pathlib import Path

import numpy as np
import pandas as pd
import streamlit as st

import flyte
import flyte.app

# {{docs-fragment streamlit-app}}
def main():
    st.set_page_config(page_title="Sales Dashboard", page_icon="📊")

    st.title("Sales Dashboard")

    # Load data
    @st.cache_data
    def load_data():
        return pd.DataFrame({
            "date": pd.date_range("2024-01-01", periods=100, freq="D"),
            "sales": np.random.randint(1000, 5000, 100),
        })

    data = load_data()

    # Sidebar filters
    st.sidebar.header("Filters")
    start_date = st.sidebar.date_input("Start date", value=data["date"].min())
    end_date = st.sidebar.date_input("End date", value=data["date"].max())

    # Filter data
    filtered_data = data[
        (data["date"] >= pd.Timestamp(start_date)) &
        (data["date"] <= pd.Timestamp(end_date))
    ]

    # Display metrics
    col1, col2, col3 = st.columns(3)
    with col1:
        st.metric("Total Sales", f"${filtered_data['sales'].sum():,.0f}")
    with col2:
        st.metric("Average Sales", f"${filtered_data['sales'].mean():,.0f}")
    with col3:
        st.metric("Days", len(filtered_data))

    # Chart
    st.line_chart(filtered_data.set_index("date")["sales"])

# {{/docs-fragment streamlit-app}}

# {{docs-fragment app-env}}
file_name = Path(__file__).name
app_env = flyte.app.AppEnvironment(
    name="sales-dashboard",
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "streamlit==1.41.1",
        "pandas==2.2.3",
        "numpy==2.2.3",
    ),
    args=["streamlit run", file_name, "--server.port", "8080", "--", "--server"],
    port=8080,
    resources=flyte.Resources(cpu="2", memory="2Gi"),
    requires_auth=False,
)
# {{/docs-fragment app-env}}

# {{docs-fragment serve}}
if __name__ == "__main__":
    import logging
    import sys

    if "--server" in sys.argv:
        main()
    else:
        flyte.init_from_config(
            root_dir=Path(__file__).parent,
            log_level=logging.DEBUG,
        )
        app = flyte.serve(app_env)
        print(f"Dashboard URL: {app.url}")
# {{/docs-fragment serve}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/streamlit/data_visualization_dashboard.py*

And finally the app serving logic:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "streamlit",
#    "pandas",
#    "numpy",
# ]
# ///

"""A data visualization dashboard example using Streamlit."""

import sys
from pathlib import Path

import numpy as np
import pandas as pd
import streamlit as st

import flyte
import flyte.app

# {{docs-fragment streamlit-app}}
def main():
    st.set_page_config(page_title="Sales Dashboard", page_icon="📊")

    st.title("Sales Dashboard")

    # Load data
    @st.cache_data
    def load_data():
        return pd.DataFrame({
            "date": pd.date_range("2024-01-01", periods=100, freq="D"),
            "sales": np.random.randint(1000, 5000, 100),
        })

    data = load_data()

    # Sidebar filters
    st.sidebar.header("Filters")
    start_date = st.sidebar.date_input("Start date", value=data["date"].min())
    end_date = st.sidebar.date_input("End date", value=data["date"].max())

    # Filter data
    filtered_data = data[
        (data["date"] >= pd.Timestamp(start_date)) &
        (data["date"] <= pd.Timestamp(end_date))
    ]

    # Display metrics
    col1, col2, col3 = st.columns(3)
    with col1:
        st.metric("Total Sales", f"${filtered_data['sales'].sum():,.0f}")
    with col2:
        st.metric("Average Sales", f"${filtered_data['sales'].mean():,.0f}")
    with col3:
        st.metric("Days", len(filtered_data))

    # Chart
    st.line_chart(filtered_data.set_index("date")["sales"])

# {{/docs-fragment streamlit-app}}

# {{docs-fragment app-env}}
file_name = Path(__file__).name
app_env = flyte.app.AppEnvironment(
    name="sales-dashboard",
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "streamlit==1.41.1",
        "pandas==2.2.3",
        "numpy==2.2.3",
    ),
    args=["streamlit run", file_name, "--server.port", "8080", "--", "--server"],
    port=8080,
    resources=flyte.Resources(cpu="2", memory="2Gi"),
    requires_auth=False,
)
# {{/docs-fragment app-env}}

# {{docs-fragment serve}}
if __name__ == "__main__":
    import logging
    import sys

    if "--server" in sys.argv:
        main()
    else:
        flyte.init_from_config(
            root_dir=Path(__file__).parent,
            log_level=logging.DEBUG,
        )
        app = flyte.serve(app_env)
        print(f"Dashboard URL: {app.url}")
# {{/docs-fragment serve}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/streamlit/data_visualization_dashboard.py*

## Best practices

1. **Use `include` for custom apps**: Always include your app files when deploying custom Streamlit code
2. **Set the port correctly**: Ensure your Streamlit app uses `--server.port 8080` (or match your `port` setting)
3. **Cache data**: Use `@st.cache_data` for expensive computations to improve performance
4. **Resource sizing**: Adjust resources based on your app's needs (data size, computations)
5. **Public vs private**: Set `requires_auth=False` for public dashboards, `True` for internal tools

## Troubleshooting

**App not loading:**
- Verify the port matches (use `--server.port 8080`)
- Check that all required files are included
- Review container logs for errors

**Missing dependencies:**
- Ensure all required packages are in your image's pip packages
- Check that file paths in `include` are correct

**Performance issues:**
- Increase CPU/memory resources
- Use Streamlit's caching features (`@st.cache_data`, `@st.cache_resource`)
- Optimize data processing


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/build-apps/fastapi-app ===

# FastAPI app

FastAPI is a modern, fast web framework for building APIs. Flyte provides `FastAPIAppEnvironment` which makes it easy to deploy FastAPI applications.

## Basic FastAPI app

Here's a simple FastAPI app:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
# ]
# ///

"""A basic FastAPI app example."""

from fastapi import FastAPI
import pathlib
import flyte
from flyte.app.extras import FastAPIAppEnvironment

# {{docs-fragment fastapi-app}}
app = FastAPI(
    title="My API",
    description="A simple FastAPI application",
    version="1.0.0",
)
# {{/docs-fragment fastapi-app}}

# {{docs-fragment fastapi-env}}
env = FastAPIAppEnvironment(
    name="my-fastapi-app",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
    ),
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
)
# {{/docs-fragment fastapi-env}}

# {{docs-fragment endpoints}}
@app.get("/")
async def root():
    return {"message": "Hello, World!"}

@app.get("/health")
async def health_check():
    return {"status": "healthy"}
# {{/docs-fragment endpoints}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    app_deployment = flyte.deploy(env)
    print(f"Deployed: {app_deployment[0].summary_repr()}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/basic_fastapi.py*

Once deployed, you can:
- Access the API at the generated URL
- View interactive API docs at `/docs` (Swagger UI)
- View alternative docs at `/redoc`

## Serving a machine learning model

Here's an example of serving a scikit-learn model:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
#    "scikit-learn",
#    "joblib",
# ]
# ///

"""Example of serving a machine learning model with FastAPI."""

import os
from contextlib import asynccontextmanager
from pathlib import Path

import joblib
import flyte
from fastapi import FastAPI
from flyte.app.extras import FastAPIAppEnvironment
from pydantic import BaseModel

# {{docs-fragment ml-model}}
app = FastAPI(title="ML Model API")

# Define request/response models
class PredictionRequest(BaseModel):
    feature1: float
    feature2: float
    feature3: float

class PredictionResponse(BaseModel):
    prediction: float
    probability: float

# Load model (you would typically load this from storage)
model = None

@asynccontextmanager
async def lifespan(app: FastAPI):
    global model
    model_path = os.getenv("MODEL_PATH", "/app/models/model.joblib")
    # In production, load from your storage
    if os.path.exists(model_path):
        with open(model_path, "rb") as f:
            model = joblib.load(f)
    yield

@app.post("/predict", response_model=PredictionResponse)
async def predict(request: PredictionRequest):
    # Make prediction
    # prediction = model.predict([[request.feature1, request.feature2, request.feature3]])

    # Dummy prediction for demo
    prediction = 0.85
    probability = 0.92

    return PredictionResponse(
        prediction=prediction,
        probability=probability,
    )

env = FastAPIAppEnvironment(
    name="ml-model-api",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
        "scikit-learn",
        "pydantic",
        "joblib",
    ),
    parameters=[
        flyte.app.Parameter(
            name="model_file",
            value=flyte.io.File("s3://bucket/models/model.joblib"),
            mount="/app/models",
            env_var="MODEL_PATH",
        ),
    ],
    resources=flyte.Resources(cpu=2, memory="2Gi"),
    requires_auth=False,
)
# {{/docs-fragment ml-model}}

if __name__ == "__main__":
    flyte.init_from_config(root_dir=Path(__file__).parent)
    app_deployment = flyte.deploy(env)
    print(f"API URL: {app_deployment[0].url}")
    print(f"Swagger docs: {app_deployment[0].url}/docs")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/ml_model_serving.py*

## Accessing Swagger documentation

FastAPI automatically generates interactive API documentation. Once deployed:

- **Swagger UI**: Access at `{app_url}/docs`
- **ReDoc**: Access at `{app_url}/redoc`
- **OpenAPI JSON**: Access at `{app_url}/openapi.json`

The Swagger UI provides an interactive interface where you can:
- See all available endpoints
- Test API calls directly from the browser
- View request/response schemas
- See example payloads

## Example: REST API with multiple endpoints

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
# ]
# ///

"""Example REST API with multiple endpoints."""

from pathlib import Path
from typing import List
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import flyte
from flyte.app.extras import FastAPIAppEnvironment

# {{docs-fragment rest-api}}
app = FastAPI(title="Product API")

# Data models
class Product(BaseModel):
    id: int
    name: str
    price: float

class ProductCreate(BaseModel):
    name: str
    price: float

# In-memory database (use real database in production)
products_db = []

@app.get("/products", response_model=List[Product])
async def get_products():
    return products_db

@app.get("/products/{product_id}", response_model=Product)
async def get_product(product_id: int):
    product = next((p for p in products_db if p["id"] == product_id), None)
    if not product:
        raise HTTPException(status_code=404, detail="Product not found")
    return product

@app.post("/products", response_model=Product)
async def create_product(product: ProductCreate):
    new_product = {
        "id": len(products_db) + 1,
        "name": product.name,
        "price": product.price,
    }
    products_db.append(new_product)
    return new_product

env = FastAPIAppEnvironment(
    name="product-api",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
    ),
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
)
# {{/docs-fragment rest-api}}

if __name__ == "__main__":
    flyte.init_from_config(root_dir=Path(__file__).parent)
    app_deployment = flyte.deploy(env)
    print(f"API URL: {app_deployment[0].url}")
    print(f"Swagger docs: {app_deployment[0].url}/docs")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/rest_api.py*

## Multi-file FastAPI app

Here's an example of a multi-file FastAPI app:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "fastapi",
# ]
# ///

"""Multi-file FastAPI app example."""

from fastapi import FastAPI
from module import function  # Import from another file
import pathlib

import flyte
from flyte.app.extras import FastAPIAppEnvironment

# {{docs-fragment app-definition}}
app = FastAPI(title="Multi-file FastAPI Demo")

app_env = FastAPIAppEnvironment(
    name="fastapi-multi-file",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi",
        "uvicorn",
    ),
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
    # FastAPIAppEnvironment automatically includes necessary files
    # But you can also specify explicitly:
    # include=["app.py", "module.py"],
)
# {{/docs-fragment app-definition}}

# {{docs-fragment endpoint}}
@app.get("/")
async def root():
    return function()  # Uses function from module.py
# {{/docs-fragment endpoint}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    flyte.init_from_config(root_dir=pathlib.Path(__file__).parent)
    app_deployment = flyte.deploy(app_env)
    print(f"Deployed: {app_deployment[0].summary_repr()}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/multi_file/app.py*

The helper module:

```
# {{docs-fragment helper-function}}
def function():
    """Helper function used by the FastAPI app."""
    return {"message": "Hello from module.py!"}
# {{/docs-fragment helper-function}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/fastapi/multi_file/module.py*

See [Multi-script apps](./multi-script-apps) for more details on building FastAPI apps with multiple files.

## Local-to-remote model serving

A common ML pattern: train a model with a Flyte pipeline, then serve predictions from it. During local development, the app loads the model from a local file (e.g. `model.pt` saved by your training pipeline). When deployed remotely, Flyte's `Parameter` system automatically resolves the model from the latest training run output.

```python
from contextlib import asynccontextmanager
from pathlib import Path
import os

from fastapi import FastAPI
import flyte
from flyte.app import Parameter, RunOutput
from flyte.app.extras import FastAPIAppEnvironment

MODEL_PATH_ENV = "MODEL_PATH"

@asynccontextmanager
async def lifespan(app: FastAPI):
    """Load model on startup, either local file or remote run output."""
    model_path = Path(os.environ.get(MODEL_PATH_ENV, "model.pt"))
    model = load_model(model_path)
    app.state.model = model
    yield

app = FastAPI(title="MNIST Predictor", lifespan=lifespan)

serving_env = FastAPIAppEnvironment(
    name="mnist-predictor",
    app=app,
    parameters=[
        # Remote: resolves model from the latest train run and sets MODEL_PATH
        Parameter(
            name="model",
            value=RunOutput(task_name="ml_pipeline.pipeline", type="file", getter=(1,)),
            download=True,
            env_var=MODEL_PATH_ENV,
        ),
    ],
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "fastapi", "uvicorn", "torch", "torchvision",
    ),
    resources=flyte.Resources(cpu=1, memory="4Gi"),
)

@app.get("/predict")
async def predict(index: int = 0) -> dict:
    return {"prediction": app.state.model(index)}

if __name__ == "__main__":
    # Local: skip RunOutput resolution, lifespan falls back to local model.pt
    serving_env.parameters = []
    local_app = flyte.with_servecontext(mode="local").serve(serving_env)
    local_app.activate(wait=True)
```

Locally, the app loads `model.pt` from disk:

```bash
python serve_model.py
```

Remotely, Flyte resolves the model from the latest training run:

```bash
flyte deploy serve_model.py serving_env
```

The key idea: `Parameter` with `RunOutput` bridges the gap between local and remote. Locally, the app falls back to a local file. Remotely, Flyte resolves the model artifact from the latest pipeline run automatically.

## Best practices

1. **Use Pydantic models**: Define request/response models for type safety and automatic validation
2. **Handle errors**: Use HTTPException for proper error responses
3. **Async operations**: Use async/await for I/O operations
4. **Environment variables**: Use environment variables for configuration
5. **Logging**: Add proper logging for debugging and monitoring
6. **Health checks**: Always include a `/health` endpoint
7. **API documentation**: FastAPI auto-generates docs, but add descriptions to your endpoints

## Advanced features

FastAPI supports many features that work with Flyte:

- **Dependencies**: Use FastAPI's dependency injection system
- **Background tasks**: Run background tasks with BackgroundTasks
- **WebSockets**: See [WebSocket-based patterns](./app-usage-patterns#websocket-based-patterns) for details
- **Authentication**: Add authentication middleware (see [secret-based authentication](./secret-based-authentication))
- **CORS**: Configure CORS for cross-origin requests
- **Rate limiting**: Add rate limiting middleware

## Troubleshooting

**App not starting:**
- Check that uvicorn can find your app module
- Verify all dependencies are installed in the image
- Check container logs for startup errors

**Import errors:**
- Ensure all imported modules are available
- Use `include` parameter if you have custom modules
- Check that file paths are correct

**API not accessible:**
- Verify `requires_auth` setting
- Check that the app is listening on the correct port (8080)
- Review network/firewall settings


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/build-apps/vllm-app ===

# vLLM app

vLLM is a high-performance library for serving large language models (LLMs). Flyte provides `VLLMAppEnvironment` for deploying vLLM model servers.

## Installation

First, install the vLLM plugin:

```bash
pip install flyteplugins-vllm
```

## Basic vLLM app

Here's a simple example serving a HuggingFace model:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-vllm>=2.0.0b45",
# ]
# ///

"""A simple vLLM app example."""

from flyteplugins.vllm import VLLMAppEnvironment
import flyte

# {{docs-fragment basic-vllm-app}}
vllm_app = VLLMAppEnvironment(
    name="my-llm-app",
    model_hf_path="Qwen/Qwen3-0.6B",  # HuggingFace model path
    model_id="qwen3-0.6b",  # Model ID exposed by vLLM
    resources=flyte.Resources(
        cpu="4",
        memory="16Gi",
        gpu="L40s:1",  # GPU required for LLM serving
        disk="10Gi",
    ),
    scaling=flyte.app.Scaling(
        replicas=(0, 1),
        scaledown_after=300,  # Scale down after 5 minutes of inactivity
    ),
    requires_auth=False,
)
# {{/docs-fragment basic-vllm-app}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    flyte.init_from_config()
    app = flyte.serve(vllm_app)
    print(f"Deployed vLLM app: {app.url}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/vllm/basic_vllm.py*

## Using prefetched models

You can use models prefetched with `flyte.prefetch`:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-vllm>=2.0.0b45",
# ]
# override-dependencies = [
#    "cel-python; sys_platform == 'never'",
# ]
# ///

"""vLLM app using prefetched models."""

from flyteplugins.vllm import VLLMAppEnvironment
import flyte

# {{docs-fragment prefetch}}

# Use the prefetched model
vllm_app = VLLMAppEnvironment(
    name="my-llm-app",
    model_hf_path="Qwen/Qwen3-0.6B",  # this is a placeholder
    model_id="qwen3-0.6b",
    resources=flyte.Resources(cpu="4", memory="16Gi", gpu="L40s:1", disk="10Gi"),
    stream_model=True,  # Stream model directly from blob store to GPU
    requires_auth=False,
)

if __name__ == "__main__":
    flyte.init_from_config()

    # Prefetch the model first
    run = flyte.prefetch.hf_model(repo="Qwen/Qwen3-0.6B")
    run.wait()

    # Use the prefetched model
    app = flyte.serve(
        vllm_app.clone_with(
            vllm_app.name,
            model_hf_path=None,
            model_path=flyte.app.RunOutput(type="directory", run_name=run.name),
        )
    )
    print(f"Deployed vLLM app: {app.url}")
# {{/docs-fragment prefetch}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/vllm/vllm_with_prefetch.py*

## Model streaming

`VLLMAppEnvironment` supports streaming models directly from blob storage to GPU memory, reducing startup time.
When `stream_model=True` and the `model_path` argument is provided with either a `flyte.io.Dir` or `RunOutput` pointing
to a path in object store:

- Model weights stream directly from storage to GPU
- Faster startup time (no full download required)
- Lower disk space requirements

> [!NOTE]
> The contents of the model directory must be compatible with the vLLM-supported formats, e.g. the HuggingFace model
> serialization format.

## Custom vLLM arguments

Use `extra_args` to pass additional arguments to vLLM:

```python
vllm_app = VLLMAppEnvironment(
    name="custom-vllm-app",
    model_hf_path="Qwen/Qwen3-0.6B",
    model_id="qwen3-0.6b",
    extra_args=[
        "--max-model-len", "8192",  # Maximum context length
        "--gpu-memory-utilization", "0.8",  # GPU memory utilization
        "--trust-remote-code",  # Trust remote code in models
    ],
    resources=flyte.Resources(cpu="4", memory="16Gi", gpu="L40s:1"),
    # ...
)
```

See the [vLLM documentation](https://docs.vllm.ai/en/stable/configuration/engine_args.html) for all available arguments.

## Using the OpenAI-compatible API

Once deployed, your vLLM app exposes an OpenAI-compatible API:

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://your-app-url/v1",  # vLLM endpoint
    api_key="your-api-key",  # If you passed an --api-key argument
)

response = client.chat.completions.create(
    model="qwen3-0.6b",  # Your model_id
    messages=[
        {"role": "user", "content": "Hello, how are you?"}
    ],
)

print(response.choices[0].message.content)
```

> [!TIP]
> If you passed an `--api-key` argument, you can use the `api_key` parameter to authenticate your requests.
> See [here](./secret-based-authentication#deploy-vllm-app-with-authentication) for more details on how to pass auth secrets to your app.

## Multi-GPU inference (Tensor Parallelism)

For larger models, use multiple GPUs with tensor parallelism:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-vllm>=2.0.0b45",
# ]
# ///

"""vLLM app with multi-GPU tensor parallelism."""

from flyteplugins.vllm import VLLMAppEnvironment
import flyte

# {{docs-fragment multi-gpu}}
vllm_app = VLLMAppEnvironment(
    name="multi-gpu-llm-app",
    model_hf_path="meta-llama/Llama-2-70b-hf",
    model_id="llama-2-70b",
    resources=flyte.Resources(
        cpu="8",
        memory="32Gi",
        gpu="L40s:4",  # 4 GPUs for tensor parallelism
        disk="100Gi",
    ),
    extra_args=[
        "--tensor-parallel-size", "4",  # Use 4 GPUs
        "--max-model-len", "4096",
        "--gpu-memory-utilization", "0.9",
    ],
    requires_auth=False,
)
# {{/docs-fragment multi-gpu}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    flyte.init_from_config()
    app = flyte.serve(vllm_app)
    print(f"Deployed vLLM app: {app.url}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/vllm/vllm_multi_gpu.py*

The `tensor-parallel-size` should match the number of GPUs specified in resources.

## Model sharding with prefetch

You can prefetch and shard models for multi-GPU inference:

```python
# Prefetch with sharding configuration
run = flyte.prefetch.hf_model(
    repo="meta-llama/Llama-2-70b-hf",
    accelerator="L40s:4",
    shard_config=flyte.prefetch.ShardConfig(
        engine="vllm",
        args=flyte.prefetch.VLLMShardArgs(
            tensor_parallel_size=4,
            dtype="auto",
            trust_remote_code=True,
        ),
    ),
)
run.wait()

# Use the sharded model
vllm_app = VLLMAppEnvironment(
    name="sharded-llm-app",
    model_path=flyte.app.RunOutput(type="directory", run_name=run.name),
    model_id="llama-2-70b",
    resources=flyte.Resources(cpu="8", memory="32Gi", gpu="L40s:4", disk="100Gi"),
    extra_args=["--tensor-parallel-size", "4"],
    stream_model=True,
)
```

See [Prefetching models](../serve-and-deploy-apps/prefetching-models) for more details on sharding.

## Autoscaling

vLLM apps work well with autoscaling:

```python
vllm_app = VLLMAppEnvironment(
    name="autoscaling-llm-app",
    model_hf_path="Qwen/Qwen3-0.6B",
    model_id="qwen3-0.6b",
    resources=flyte.Resources(cpu="4", memory="16Gi", gpu="L40s:1"),
    scaling=flyte.app.Scaling(
        replicas=(0, 1),  # Scale to zero when idle
        scaledown_after=600,  # 10 minutes idle before scaling down
    ),
    # ...
)
```

## Best practices

1. **Use prefetching**: Prefetch models for faster deployment and better reproducibility
2. **Enable streaming**: Use `stream_model=True` to reduce startup time and disk usage
3. **Right-size GPUs**: Match GPU memory to model size
4. **Configure memory utilization**: Use `--gpu-memory-utilization` to control memory usage
5. **Use tensor parallelism**: For large models, use multiple GPUs with `tensor-parallel-size`
6. **Set autoscaling**: Use appropriate idle TTL to balance cost and performance
7. **Limit context length**: Use `--max-model-len` for smaller models to reduce memory usage

## Troubleshooting

**Model loading fails:**
- Verify GPU memory is sufficient for the model
- Check that the model path or HuggingFace path is correct
- Review container logs for detailed error messages

**Out of memory errors:**
- Reduce `--max-model-len`
- Lower `--gpu-memory-utilization`
- Use a smaller model or more GPUs

**Slow startup:**
- Enable `stream_model=True` for faster loading
- Prefetch models before deployment
- Use faster storage backends


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/build-apps/sglang-app ===

# SGLang app

SGLang is a fast structured generation library for large language models (LLMs). Flyte provides `SGLangAppEnvironment` for deploying SGLang model servers.

## Installation

First, install the SGLang plugin:

```bash
pip install flyteplugins-sglang
```

## Basic SGLang app

Here's a simple example serving a HuggingFace model:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-sglang>=2.0.0b45",
# ]
# ///

"""A simple SGLang app example."""

from flyteplugins.sglang import SGLangAppEnvironment
import flyte

# {{docs-fragment basic-sglang-app}}
sglang_app = SGLangAppEnvironment(
    name="my-sglang-app",
    model_hf_path="Qwen/Qwen3-0.6B",  # HuggingFace model path
    model_id="qwen3-0.6b",  # Model ID exposed by SGLang
    resources=flyte.Resources(
        cpu="4",
        memory="16Gi",
        gpu="L40s:1",  # GPU required for LLM serving
        disk="10Gi",
    ),
    scaling=flyte.app.Scaling(
        replicas=(0, 1),
        scaledown_after=300,  # Scale down after 5 minutes of inactivity
    ),
    requires_auth=False,
)
# {{/docs-fragment basic-sglang-app}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    flyte.init_from_config()
    app = flyte.serve(sglang_app)
    print(f"Deployed SGLang app: {app.url}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/sglang/basic_sglang.py*

## Using prefetched models

You can use models prefetched with `flyte.prefetch`:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-sglang>=2.0.0b45",
# ]
# ///

"""SGLang app using prefetched models."""

from flyteplugins.sglang import SGLangAppEnvironment
import flyte

# {{docs-fragment prefetch}}

# Use the prefetched model
sglang_app = SGLangAppEnvironment(
    name="my-sglang-app",
    model_hf_path="Qwen/Qwen3-0.6B",  # this is a placeholder
    model_id="qwen3-0.6b",
    resources=flyte.Resources(cpu="4", memory="16Gi", gpu="L40s:1", disk="10Gi"),
    stream_model=True,  # Stream model directly from blob store to GPU
    requires_auth=False,
)

if __name__ == "__main__":
    flyte.init_from_config()

    # Prefetch the model first
    run = flyte.prefetch.hf_model(repo="Qwen/Qwen3-0.6B")
    run.wait()

    app = flyte.serve(
        sglang_app.clone_with(
            sglang_app.name,
            model_hf_path=None,
            model_path=flyte.app.RunOutput(type="directory", run_name=run.name),
        )
    )
    print(f"Deployed SGLang app: {app.url}")
# {{/docs-fragment prefetch}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/sglang/sglang_with_prefetch.py*

## Model streaming

`SGLangAppEnvironment` supports streaming models directly from blob storage to GPU memory, reducing startup time.
When `stream_model=True` and the `model_path` argument is provided with either a `flyte.io.Dir` or `RunOutput` pointing
to a path in object store:

- Model weights stream directly from storage to GPU
- Faster startup time (no full download required)
- Lower disk space requirements

> [!NOTE]
> The contents of the model directory must be compatible with the SGLang-supported formats, e.g. the HuggingFace model
> serialization format.

## Custom SGLang arguments

Use `extra_args` to pass additional arguments to SGLang:

```python
sglang_app = SGLangAppEnvironment(
    name="custom-sglang-app",
    model_hf_path="Qwen/Qwen3-0.6B",
    model_id="qwen3-0.6b",
    extra_args=[
        "--max-model-len", "8192",  # Maximum context length
        "--mem-fraction-static", "0.8",  # Memory fraction for static allocation
        "--trust-remote-code",  # Trust remote code in models
    ],
    resources=flyte.Resources(cpu="4", memory="16Gi", gpu="L40s:1"),
    # ...
)
```

See the [SGLang server arguments documentation](https://docs.sglang.io/advanced_features/server_arguments.html) for all available options.

## Using the OpenAI-compatible API

Once deployed, your SGLang app exposes an OpenAI-compatible API:

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://your-app-url/v1",  # SGLang endpoint
    api_key="your-api-key",  # If you passed an --api-key argument
)

response = client.chat.completions.create(
    model="qwen3-0.6b",  # Your model_id
    messages=[
        {"role": "user", "content": "Hello, how are you?"}
    ],
)

print(response.choices[0].message.content)
```

> [!TIP]
> If you passed an `--api-key` argument, you can use the `api_key` parameter to authenticate your requests.
> See [here](./secret-based-authentication#deploy-sglang-app-with-authentication) for more details on how to pass auth secrets to your app.

## Multi-GPU inference (Tensor Parallelism)

For larger models, use multiple GPUs with tensor parallelism:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-sglang>=2.0.0b45",
# ]
# ///

"""SGLang app with multi-GPU tensor parallelism."""

from flyteplugins.sglang import SGLangAppEnvironment
import flyte

# {{docs-fragment multi-gpu}}
sglang_app = SGLangAppEnvironment(
    name="multi-gpu-sglang-app",
    model_hf_path="meta-llama/Llama-2-70b-hf",
    model_id="llama-2-70b",
    resources=flyte.Resources(
        cpu="8",
        memory="32Gi",
        gpu="L40s:4",  # 4 GPUs for tensor parallelism
        disk="100Gi",
    ),
    extra_args=[
        "--tp", "4",  # Tensor parallelism size (4 GPUs)
        "--max-model-len", "4096",
        "--mem-fraction-static", "0.9",
    ],
    requires_auth=False,
)
# {{/docs-fragment multi-gpu}}

# {{docs-fragment deploy}}
if __name__ == "__main__":
    flyte.init_from_config()
    app = flyte.serve(sglang_app)
    print(f"Deployed SGLang app: {app.url}")
# {{/docs-fragment deploy}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/build-apps/sglang/sglang_multi_gpu.py*

The tensor parallelism size (`--tp`) should match the number of GPUs specified in resources.

## Model sharding with prefetch

You can prefetch and shard models for multi-GPU inference using SGLang's sharding:

```python
# Prefetch with sharding configuration
run = flyte.prefetch.hf_model(
    repo="meta-llama/Llama-2-70b-hf",
    accelerator="L40s:4",
    shard_config=flyte.prefetch.ShardConfig(
        engine="vllm",
        args=flyte.prefetch.VLLMShardArgs(
            tensor_parallel_size=4,
            dtype="auto",
            trust_remote_code=True,
        ),
    ),
)
run.wait()

# Use the sharded model
sglang_app = SGLangAppEnvironment(
    name="sharded-sglang-app",
    model_path=flyte.app.RunOutput(type="directory", run_name=run.name),
    model_id="llama-2-70b",
    resources=flyte.Resources(cpu="8", memory="32Gi", gpu="L40s:4", disk="100Gi"),
    extra_args=["--tp", "4"],
    stream_model=True,
)
```

See [Prefetching models](../serve-and-deploy-apps/prefetching-models) for more details on sharding.

## Autoscaling

SGLang apps work well with autoscaling:

```python
sglang_app = SGLangAppEnvironment(
    name="autoscaling-sglang-app",
    model_hf_path="Qwen/Qwen3-0.6B",
    model_id="qwen3-0.6b",
    resources=flyte.Resources(cpu="4", memory="16Gi", gpu="L40s:1"),
    scaling=flyte.app.Scaling(
        replicas=(0, 1),  # Scale to zero when idle
        scaledown_after=600,  # 10 minutes idle before scaling down
    ),
    # ...
)
```

## Structured generation

SGLang is particularly well-suited for structured generation tasks. The deployed app supports standard OpenAI API calls, and you can use SGLang's advanced features through the API.

## Best practices

1. **Use prefetching**: Prefetch models for faster deployment and better reproducibility
2. **Enable streaming**: Use `stream_model=True` to reduce startup time and disk usage
3. **Right-size GPUs**: Match GPU memory to model size
4. **Use tensor parallelism**: For large models, use multiple GPUs with `--tp`
5. **Set autoscaling**: Use appropriate idle TTL to balance cost and performance
6. **Configure memory**: Use `--mem-fraction-static` to control memory allocation
7. **Limit context length**: Use `--max-model-len` for smaller models to reduce memory usage

## Troubleshooting

**Model loading fails:**
- Verify GPU memory is sufficient for the model
- Check that the model path or HuggingFace path is correct
- Review container logs for detailed error messages

**Out of memory errors:**
- Reduce `--max-model-len`
- Lower `--mem-fraction-static`
- Use a smaller model or more GPUs

**Slow startup:**
- Enable `stream_model=True` for faster loading
- Prefetch models before deployment
- Use faster storage backends


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/serve-and-deploy-apps ===

# Serve and deploy apps

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

Flyte provides two main ways to deploy apps: **serve** (for development) and **deploy** (for production). This section covers both methods and their differences.

## Serve vs Deploy

### `flyte serve`

Serving is designed for development and iteration:

- **Dynamic parameter modification**: You can override app parameters when serving
- **Quick iteration**: Faster feedback loop for development
- **Interactive**: Better suited for testing and experimentation

### `flyte deploy`

Deployment is designed for production use:

- **Immutable**: Apps are deployed with fixed configurations
- **Production-ready**: Optimized for stability and reproducibility

## Using Python SDK

### Serve

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""Serve and deploy examples for the _index.md documentation."""

import flyte
import flyte.app

# {{docs-fragment serve-example}}
app_env = flyte.app.AppEnvironment(
    name="my-app",
    image=flyte.app.Image.from_debian_base().with_pip_packages("streamlit==1.41.1"),
    args=["streamlit", "hello", "--server.port", "8080"],
    port=8080,
    resources=flyte.Resources(cpu="1", memory="1Gi"),
)

if __name__ == "__main__":
    flyte.init_from_config()
    app = flyte.serve(app_env)
    print(f"Served at: {app.url}")
# {{/docs-fragment serve-example}}

# {{docs-fragment deploy-example}}
app_env = flyte.app.AppEnvironment(
    name="my-app",
    image=flyte.app.Image.from_debian_base().with_pip_packages("streamlit==1.41.1"),
    args=["streamlit", "hello", "--server.port", "8080"],
    port=8080,
    resources=flyte.Resources(cpu="1", memory="1Gi"),
)

if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(app_env)
    # Access deployed app URL from the deployment
    for deployed_env in deployments[0].envs.values():
        print(f"Deployed: {deployed_env.deployed_app.url}")
# {{/docs-fragment deploy-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/serve_and_deploy_examples.py*

### Deploy

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""Serve and deploy examples for the _index.md documentation."""

import flyte
import flyte.app

# {{docs-fragment serve-example}}
app_env = flyte.app.AppEnvironment(
    name="my-app",
    image=flyte.app.Image.from_debian_base().with_pip_packages("streamlit==1.41.1"),
    args=["streamlit", "hello", "--server.port", "8080"],
    port=8080,
    resources=flyte.Resources(cpu="1", memory="1Gi"),
)

if __name__ == "__main__":
    flyte.init_from_config()
    app = flyte.serve(app_env)
    print(f"Served at: {app.url}")
# {{/docs-fragment serve-example}}

# {{docs-fragment deploy-example}}
app_env = flyte.app.AppEnvironment(
    name="my-app",
    image=flyte.app.Image.from_debian_base().with_pip_packages("streamlit==1.41.1"),
    args=["streamlit", "hello", "--server.port", "8080"],
    port=8080,
    resources=flyte.Resources(cpu="1", memory="1Gi"),
)

if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(app_env)
    # Access deployed app URL from the deployment
    for deployed_env in deployments[0].envs.values():
        print(f"Deployed: {deployed_env.deployed_app.url}")
# {{/docs-fragment deploy-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/serve_and_deploy_examples.py*

## Using the CLI

### Serve

```bash
flyte serve path/to/app.py app_env
```

### Deploy

```bash
flyte deploy path/to/app.py app_env
```

## Next steps

- **Serve and deploy apps > How app serving works**: Understanding the serve process and configuration options
- **Serve and deploy apps > How app deployment works**: Understanding the deploy process and configuration options
- **Serve and deploy apps > Activating and deactivating apps**: Managing app lifecycle
- **Basic project: RAG**: Train a model with tasks and serve it via FastAPI
- **Serve and deploy apps > Prefetching models**: Download and shard HuggingFace models for vLLM and SGLang

## Subpages
- **Serve and deploy apps > How app serving works**
- **Serve and deploy apps > How app deployment works**
- **Serve and deploy apps > Activating and deactivating apps**
- **Serve and deploy apps > Prefetching models**


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/serve-and-deploy-apps/how-app-serving-works ===

# How app serving works

Serving is the recommended way to deploy apps during development. It provides a faster feedback loop and allows you to dynamically modify parameters.

## Overview

When you serve an app, the following happens:

1. **Code bundling**: Your app code is bundled and prepared
2. **Image building**: Container images are built (if needed)
3. **Deployment**: The app is deployed to your Flyte cluster
4. **Activation**: The app is automatically activated and ready to use
5. **URL generation**: A URL is generated for accessing the app

## Using the Python SDK

The simplest way to serve an app:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""Serve examples for the how-app-serving-works.md documentation."""

import logging
import flyte
import flyte.app

# {{docs-fragment basic-serve}}
app_env = flyte.app.AppEnvironment(
    name="my-dev-app",
    parameters=[flyte.app.Parameter(name="model_path", value="s3://bucket/models/model.pkl")],
    # ...
)

if __name__ == "__main__":
    flyte.init_from_config()
    app = flyte.serve(app_env)
    print(f"App served at: {app.url}")
# {{/docs-fragment basic-serve}}

# {{docs-fragment override-parameters}}
app = flyte.with_servecontext(
    input_values={
        "my-dev-app": {
            "model_path": "s3://bucket/models/test-model.pkl",
        }
    }
).serve(app_env)
# {{/docs-fragment override-parameters}}

# {{docs-fragment advanced-serving}}
app = flyte.with_servecontext(
    version="v1.0.0",
    project="my-project",
    domain="development",
    env_vars={"LOG_LEVEL": "DEBUG"},
    input_values={"app-name": {"input": "value"}},
    cluster_pool="dev-pool",
    log_level=logging.INFO,
    log_format="json",
    dry_run=False,
).serve(app_env)
# {{/docs-fragment advanced-serving}}

# {{docs-fragment return-value}}
app = flyte.serve(app_env)
print(f"URL: {app.url}")
print(f"Endpoint: {app.endpoint}")
print(f"Status: {app.deployment_status}")
# {{/docs-fragment return-value}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/serve_examples.py*

## Overriding parameters

One key advantage of serving is the ability to override parameters dynamically:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""Serve examples for the how-app-serving-works.md documentation."""

import logging
import flyte
import flyte.app

# {{docs-fragment basic-serve}}
app_env = flyte.app.AppEnvironment(
    name="my-dev-app",
    parameters=[flyte.app.Parameter(name="model_path", value="s3://bucket/models/model.pkl")],
    # ...
)

if __name__ == "__main__":
    flyte.init_from_config()
    app = flyte.serve(app_env)
    print(f"App served at: {app.url}")
# {{/docs-fragment basic-serve}}

# {{docs-fragment override-parameters}}
app = flyte.with_servecontext(
    input_values={
        "my-dev-app": {
            "model_path": "s3://bucket/models/test-model.pkl",
        }
    }
).serve(app_env)
# {{/docs-fragment override-parameters}}

# {{docs-fragment advanced-serving}}
app = flyte.with_servecontext(
    version="v1.0.0",
    project="my-project",
    domain="development",
    env_vars={"LOG_LEVEL": "DEBUG"},
    input_values={"app-name": {"input": "value"}},
    cluster_pool="dev-pool",
    log_level=logging.INFO,
    log_format="json",
    dry_run=False,
).serve(app_env)
# {{/docs-fragment advanced-serving}}

# {{docs-fragment return-value}}
app = flyte.serve(app_env)
print(f"URL: {app.url}")
print(f"Endpoint: {app.endpoint}")
print(f"Status: {app.deployment_status}")
# {{/docs-fragment return-value}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/serve_examples.py*

This is useful for:
- Testing different configurations
- Using different models or data sources
- A/B testing during development

## Advanced serving options

Use `with_servecontext()` for more control over the serving process:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""Serve examples for the how-app-serving-works.md documentation."""

import logging
import flyte
import flyte.app

# {{docs-fragment basic-serve}}
app_env = flyte.app.AppEnvironment(
    name="my-dev-app",
    parameters=[flyte.app.Parameter(name="model_path", value="s3://bucket/models/model.pkl")],
    # ...
)

if __name__ == "__main__":
    flyte.init_from_config()
    app = flyte.serve(app_env)
    print(f"App served at: {app.url}")
# {{/docs-fragment basic-serve}}

# {{docs-fragment override-parameters}}
app = flyte.with_servecontext(
    input_values={
        "my-dev-app": {
            "model_path": "s3://bucket/models/test-model.pkl",
        }
    }
).serve(app_env)
# {{/docs-fragment override-parameters}}

# {{docs-fragment advanced-serving}}
app = flyte.with_servecontext(
    version="v1.0.0",
    project="my-project",
    domain="development",
    env_vars={"LOG_LEVEL": "DEBUG"},
    input_values={"app-name": {"input": "value"}},
    cluster_pool="dev-pool",
    log_level=logging.INFO,
    log_format="json",
    dry_run=False,
).serve(app_env)
# {{/docs-fragment advanced-serving}}

# {{docs-fragment return-value}}
app = flyte.serve(app_env)
print(f"URL: {app.url}")
print(f"Endpoint: {app.endpoint}")
print(f"Status: {app.deployment_status}")
# {{/docs-fragment return-value}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/serve_examples.py*

## Using CLI

You can also serve apps from the command line:

```bash
flyte serve path/to/app.py app
```

Where `app` is the variable name of the `AppEnvironment` object.

## Return value

`flyte.serve()` returns an `App` object with:

- `url`: The app's URL
- `endpoint`: The app's endpoint URL
- `deployment_status`: Current status of the app
- `name`: App name

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""Serve examples for the how-app-serving-works.md documentation."""

import logging
import flyte
import flyte.app

# {{docs-fragment basic-serve}}
app_env = flyte.app.AppEnvironment(
    name="my-dev-app",
    parameters=[flyte.app.Parameter(name="model_path", value="s3://bucket/models/model.pkl")],
    # ...
)

if __name__ == "__main__":
    flyte.init_from_config()
    app = flyte.serve(app_env)
    print(f"App served at: {app.url}")
# {{/docs-fragment basic-serve}}

# {{docs-fragment override-parameters}}
app = flyte.with_servecontext(
    input_values={
        "my-dev-app": {
            "model_path": "s3://bucket/models/test-model.pkl",
        }
    }
).serve(app_env)
# {{/docs-fragment override-parameters}}

# {{docs-fragment advanced-serving}}
app = flyte.with_servecontext(
    version="v1.0.0",
    project="my-project",
    domain="development",
    env_vars={"LOG_LEVEL": "DEBUG"},
    input_values={"app-name": {"input": "value"}},
    cluster_pool="dev-pool",
    log_level=logging.INFO,
    log_format="json",
    dry_run=False,
).serve(app_env)
# {{/docs-fragment advanced-serving}}

# {{docs-fragment return-value}}
app = flyte.serve(app_env)
print(f"URL: {app.url}")
print(f"Endpoint: {app.endpoint}")
print(f"Status: {app.deployment_status}")
# {{/docs-fragment return-value}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/serve_examples.py*

## Best practices

1. **Use for development**: App serving is ideal for development and testing.
2. **Override parameters**: Take advantage of parameter overrides for testing different configurations.
3. **Quick iteration**: Use `serve` for rapid development cycles.
4. **Switch to deploy**: Use [deploy](./how-app-deployment-works) for production deployments.

## Troubleshooting

**App not activating:**
- Check cluster connectivity
- Verify app configuration is correct
- Review container logs for errors

**Parameter overrides not working:**
- Verify parameter names match exactly
- Check that parameters are defined in the app environment
- Ensure you're using the `input_values` parameter correctly

**Slow serving:**
- Images may need to be built (first time is slower).
- Large code bundles can slow down deployment.
- Check network connectivity to the cluster.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/serve-and-deploy-apps/how-app-deployment-works ===

# How app deployment works

Deployment is the recommended way to deploy apps to production. It creates versioned, immutable app deployments.

## Overview

When you deploy an app, the following happens:

1. **Code bundling**: Your app code is bundled and prepared
2. **Image building**: Container images are built (if needed)
3. **Deployment**: The app is deployed to your Flyte cluster
4. **Activation**: The app is automatically activated and ready to use

## Using the Python SDK

Deploy an app:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""Deploy examples for the how-app-deployment-works.md documentation."""

import flyte
import flyte.app
from flyte.remote import App

# {{docs-fragment basic-deploy}}
app_env = flyte.app.AppEnvironment(
    name="my-prod-app",
    # ...
)

if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(app_env)

    # Access deployed apps from deployments
    for deployment in deployments:
        for deployed_env in deployment.envs.values():
            print(f"Deployed: {deployed_env.env.name}")
            print(f"URL: {deployed_env.deployed_app.url}")
# {{/docs-fragment basic-deploy}}

# {{docs-fragment deployment-plan}}
app1_env = flyte.app.AppEnvironment(name="backend", ...)
app2_env = flyte.app.AppEnvironment(name="frontend", depends_on=[app1_env], ...)

# Deploying app2_env will also deploy app1_env
deployments = flyte.deploy(app2_env)

# deployments contains both app1_env and app2_env
assert len(deployments) == 2
# {{/docs-fragment deployment-plan}}

# {{docs-fragment clone-with}}
app_env = flyte.app.AppEnvironment(name="my-app", ...)

if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(
        app_env.clone_with(app_env.name, resources=flyte.Resources(cpu="2", memory="2Gi"))
    )
    for deployment in deployments:
        for deployed_env in deployment.envs.values():
            print(f"Deployed: {deployed_env.env.name}")
            print(f"URL: {deployed_env.deployed_app.url}")
# {{/docs-fragment clone-with}}

# {{docs-fragment activation-deactivation}}
if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(app_env)

    app = App.get(name=app_env.name)

    # deactivate the app
    app.deactivate()

    # activate the app
    app.activate()
# {{/docs-fragment activation-deactivation}}

# {{docs-fragment full-deployment}}
if __name__ == "__main__":
    flyte.init_from_config()

    deployments = flyte.deploy(
        app_env,
        dryrun=False,
        version="v1.0.0",
        interactive_mode=False,
        copy_style="loaded_modules",
    )

    # Access deployed apps from deployments
    for deployment in deployments:
        for deployed_env in deployment.envs.values():
            app = deployed_env.deployed_app
            print(f"Deployed: {deployed_env.env.name}")
            print(f"URL: {app.url}")

            # Activate the app
            app.activate()
            print(f"Activated: {app.name}")
# {{/docs-fragment full-deployment}}

# {{docs-fragment deployment-status}}
deployments = flyte.deploy(app_env)

for deployment in deployments:
    for deployed_env in deployment.envs.values():
        if hasattr(deployed_env, 'deployed_app'):
            # Access deployed environment
            env = deployed_env.env
            app = deployed_env.deployed_app

            # Access deployment info
            print(f"Name: {env.name}")
            print(f"URL: {app.url}")
            print(f"Status: {app.deployment_status}")
# {{/docs-fragment deployment-status}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/deploy_examples.py*

`flyte.deploy()` returns a list of `Deployment` objects. Each `Deployment` contains a dictionary of `DeployedEnvironment` objects (one for each environment deployed, including environment dependencies). For apps, the `DeployedEnvironment` is a `DeployedAppEnvironment` which has a `deployed_app` property of type `App`.

## Deployment plan

Flyte automatically creates a deployment plan that includes:

- The app you're deploying
- All [app environment dependencies](../configure-apps/apps-depending-on-environments) (via `depends_on`)
- Proper deployment order

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""Deploy examples for the how-app-deployment-works.md documentation."""

import flyte
import flyte.app
from flyte.remote import App

# {{docs-fragment basic-deploy}}
app_env = flyte.app.AppEnvironment(
    name="my-prod-app",
    # ...
)

if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(app_env)

    # Access deployed apps from deployments
    for deployment in deployments:
        for deployed_env in deployment.envs.values():
            print(f"Deployed: {deployed_env.env.name}")
            print(f"URL: {deployed_env.deployed_app.url}")
# {{/docs-fragment basic-deploy}}

# {{docs-fragment deployment-plan}}
app1_env = flyte.app.AppEnvironment(name="backend", ...)
app2_env = flyte.app.AppEnvironment(name="frontend", depends_on=[app1_env], ...)

# Deploying app2_env will also deploy app1_env
deployments = flyte.deploy(app2_env)

# deployments contains both app1_env and app2_env
assert len(deployments) == 2
# {{/docs-fragment deployment-plan}}

# {{docs-fragment clone-with}}
app_env = flyte.app.AppEnvironment(name="my-app", ...)

if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(
        app_env.clone_with(app_env.name, resources=flyte.Resources(cpu="2", memory="2Gi"))
    )
    for deployment in deployments:
        for deployed_env in deployment.envs.values():
            print(f"Deployed: {deployed_env.env.name}")
            print(f"URL: {deployed_env.deployed_app.url}")
# {{/docs-fragment clone-with}}

# {{docs-fragment activation-deactivation}}
if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(app_env)

    app = App.get(name=app_env.name)

    # deactivate the app
    app.deactivate()

    # activate the app
    app.activate()
# {{/docs-fragment activation-deactivation}}

# {{docs-fragment full-deployment}}
if __name__ == "__main__":
    flyte.init_from_config()

    deployments = flyte.deploy(
        app_env,
        dryrun=False,
        version="v1.0.0",
        interactive_mode=False,
        copy_style="loaded_modules",
    )

    # Access deployed apps from deployments
    for deployment in deployments:
        for deployed_env in deployment.envs.values():
            app = deployed_env.deployed_app
            print(f"Deployed: {deployed_env.env.name}")
            print(f"URL: {app.url}")

            # Activate the app
            app.activate()
            print(f"Activated: {app.name}")
# {{/docs-fragment full-deployment}}

# {{docs-fragment deployment-status}}
deployments = flyte.deploy(app_env)

for deployment in deployments:
    for deployed_env in deployment.envs.values():
        if hasattr(deployed_env, 'deployed_app'):
            # Access deployed environment
            env = deployed_env.env
            app = deployed_env.deployed_app

            # Access deployment info
            print(f"Name: {env.name}")
            print(f"URL: {app.url}")
            print(f"Status: {app.deployment_status}")
# {{/docs-fragment deployment-status}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/deploy_examples.py*

## Overriding App configuration at deployment time

If you need to override the app configuration at deployment time, you can use the `clone_with` method to create a new
app environment with the desired overrides.

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""Deploy examples for the how-app-deployment-works.md documentation."""

import flyte
import flyte.app
from flyte.remote import App

# {{docs-fragment basic-deploy}}
app_env = flyte.app.AppEnvironment(
    name="my-prod-app",
    # ...
)

if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(app_env)

    # Access deployed apps from deployments
    for deployment in deployments:
        for deployed_env in deployment.envs.values():
            print(f"Deployed: {deployed_env.env.name}")
            print(f"URL: {deployed_env.deployed_app.url}")
# {{/docs-fragment basic-deploy}}

# {{docs-fragment deployment-plan}}
app1_env = flyte.app.AppEnvironment(name="backend", ...)
app2_env = flyte.app.AppEnvironment(name="frontend", depends_on=[app1_env], ...)

# Deploying app2_env will also deploy app1_env
deployments = flyte.deploy(app2_env)

# deployments contains both app1_env and app2_env
assert len(deployments) == 2
# {{/docs-fragment deployment-plan}}

# {{docs-fragment clone-with}}
app_env = flyte.app.AppEnvironment(name="my-app", ...)

if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(
        app_env.clone_with(app_env.name, resources=flyte.Resources(cpu="2", memory="2Gi"))
    )
    for deployment in deployments:
        for deployed_env in deployment.envs.values():
            print(f"Deployed: {deployed_env.env.name}")
            print(f"URL: {deployed_env.deployed_app.url}")
# {{/docs-fragment clone-with}}

# {{docs-fragment activation-deactivation}}
if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(app_env)

    app = App.get(name=app_env.name)

    # deactivate the app
    app.deactivate()

    # activate the app
    app.activate()
# {{/docs-fragment activation-deactivation}}

# {{docs-fragment full-deployment}}
if __name__ == "__main__":
    flyte.init_from_config()

    deployments = flyte.deploy(
        app_env,
        dryrun=False,
        version="v1.0.0",
        interactive_mode=False,
        copy_style="loaded_modules",
    )

    # Access deployed apps from deployments
    for deployment in deployments:
        for deployed_env in deployment.envs.values():
            app = deployed_env.deployed_app
            print(f"Deployed: {deployed_env.env.name}")
            print(f"URL: {app.url}")

            # Activate the app
            app.activate()
            print(f"Activated: {app.name}")
# {{/docs-fragment full-deployment}}

# {{docs-fragment deployment-status}}
deployments = flyte.deploy(app_env)

for deployment in deployments:
    for deployed_env in deployment.envs.values():
        if hasattr(deployed_env, 'deployed_app'):
            # Access deployed environment
            env = deployed_env.env
            app = deployed_env.deployed_app

            # Access deployment info
            print(f"Name: {env.name}")
            print(f"URL: {app.url}")
            print(f"Status: {app.deployment_status}")
# {{/docs-fragment deployment-status}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/deploy_examples.py*

## Activation/deactivation

Unlike serving, deployment does not automatically activate apps. You need to activate them explicitly:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""Deploy examples for the how-app-deployment-works.md documentation."""

import flyte
import flyte.app
from flyte.remote import App

# {{docs-fragment basic-deploy}}
app_env = flyte.app.AppEnvironment(
    name="my-prod-app",
    # ...
)

if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(app_env)

    # Access deployed apps from deployments
    for deployment in deployments:
        for deployed_env in deployment.envs.values():
            print(f"Deployed: {deployed_env.env.name}")
            print(f"URL: {deployed_env.deployed_app.url}")
# {{/docs-fragment basic-deploy}}

# {{docs-fragment deployment-plan}}
app1_env = flyte.app.AppEnvironment(name="backend", ...)
app2_env = flyte.app.AppEnvironment(name="frontend", depends_on=[app1_env], ...)

# Deploying app2_env will also deploy app1_env
deployments = flyte.deploy(app2_env)

# deployments contains both app1_env and app2_env
assert len(deployments) == 2
# {{/docs-fragment deployment-plan}}

# {{docs-fragment clone-with}}
app_env = flyte.app.AppEnvironment(name="my-app", ...)

if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(
        app_env.clone_with(app_env.name, resources=flyte.Resources(cpu="2", memory="2Gi"))
    )
    for deployment in deployments:
        for deployed_env in deployment.envs.values():
            print(f"Deployed: {deployed_env.env.name}")
            print(f"URL: {deployed_env.deployed_app.url}")
# {{/docs-fragment clone-with}}

# {{docs-fragment activation-deactivation}}
if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(app_env)

    app = App.get(name=app_env.name)

    # deactivate the app
    app.deactivate()

    # activate the app
    app.activate()
# {{/docs-fragment activation-deactivation}}

# {{docs-fragment full-deployment}}
if __name__ == "__main__":
    flyte.init_from_config()

    deployments = flyte.deploy(
        app_env,
        dryrun=False,
        version="v1.0.0",
        interactive_mode=False,
        copy_style="loaded_modules",
    )

    # Access deployed apps from deployments
    for deployment in deployments:
        for deployed_env in deployment.envs.values():
            app = deployed_env.deployed_app
            print(f"Deployed: {deployed_env.env.name}")
            print(f"URL: {app.url}")

            # Activate the app
            app.activate()
            print(f"Activated: {app.name}")
# {{/docs-fragment full-deployment}}

# {{docs-fragment deployment-status}}
deployments = flyte.deploy(app_env)

for deployment in deployments:
    for deployed_env in deployment.envs.values():
        if hasattr(deployed_env, 'deployed_app'):
            # Access deployed environment
            env = deployed_env.env
            app = deployed_env.deployed_app

            # Access deployment info
            print(f"Name: {env.name}")
            print(f"URL: {app.url}")
            print(f"Status: {app.deployment_status}")
# {{/docs-fragment deployment-status}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/deploy_examples.py*

See [Activating and deactivating apps](./activating-and-deactivating-apps) for more details.

## Using the CLI

Deploy from the command line:

```bash
flyte deploy path/to/app.py app
```

Where `app` is the variable name of the `AppEnvironment` object.

You can also specify the following options:

```bash
flyte deploy path/to/app.py app \
    --version v1.0.0 \
    --project my-project \
    --domain production \
    --dry-run
```

## Example: Full deployment configuration

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""Deploy examples for the how-app-deployment-works.md documentation."""

import flyte
import flyte.app
from flyte.remote import App

# {{docs-fragment basic-deploy}}
app_env = flyte.app.AppEnvironment(
    name="my-prod-app",
    # ...
)

if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(app_env)

    # Access deployed apps from deployments
    for deployment in deployments:
        for deployed_env in deployment.envs.values():
            print(f"Deployed: {deployed_env.env.name}")
            print(f"URL: {deployed_env.deployed_app.url}")
# {{/docs-fragment basic-deploy}}

# {{docs-fragment deployment-plan}}
app1_env = flyte.app.AppEnvironment(name="backend", ...)
app2_env = flyte.app.AppEnvironment(name="frontend", depends_on=[app1_env], ...)

# Deploying app2_env will also deploy app1_env
deployments = flyte.deploy(app2_env)

# deployments contains both app1_env and app2_env
assert len(deployments) == 2
# {{/docs-fragment deployment-plan}}

# {{docs-fragment clone-with}}
app_env = flyte.app.AppEnvironment(name="my-app", ...)

if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(
        app_env.clone_with(app_env.name, resources=flyte.Resources(cpu="2", memory="2Gi"))
    )
    for deployment in deployments:
        for deployed_env in deployment.envs.values():
            print(f"Deployed: {deployed_env.env.name}")
            print(f"URL: {deployed_env.deployed_app.url}")
# {{/docs-fragment clone-with}}

# {{docs-fragment activation-deactivation}}
if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(app_env)

    app = App.get(name=app_env.name)

    # deactivate the app
    app.deactivate()

    # activate the app
    app.activate()
# {{/docs-fragment activation-deactivation}}

# {{docs-fragment full-deployment}}
if __name__ == "__main__":
    flyte.init_from_config()

    deployments = flyte.deploy(
        app_env,
        dryrun=False,
        version="v1.0.0",
        interactive_mode=False,
        copy_style="loaded_modules",
    )

    # Access deployed apps from deployments
    for deployment in deployments:
        for deployed_env in deployment.envs.values():
            app = deployed_env.deployed_app
            print(f"Deployed: {deployed_env.env.name}")
            print(f"URL: {app.url}")

            # Activate the app
            app.activate()
            print(f"Activated: {app.name}")
# {{/docs-fragment full-deployment}}

# {{docs-fragment deployment-status}}
deployments = flyte.deploy(app_env)

for deployment in deployments:
    for deployed_env in deployment.envs.values():
        if hasattr(deployed_env, 'deployed_app'):
            # Access deployed environment
            env = deployed_env.env
            app = deployed_env.deployed_app

            # Access deployment info
            print(f"Name: {env.name}")
            print(f"URL: {app.url}")
            print(f"Status: {app.deployment_status}")
# {{/docs-fragment deployment-status}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/deploy_examples.py*

## Best practices

1. **Use for production**: Deploy is designed for production use.
2. **Version everything**: Always specify versions for reproducibility.
3. **Test first**: Test with serve before deploying to production.
4. **Manage dependencies**: Use `depends_on` to manage app dependencies.
5. **Activation strategy**: Have a strategy for activating/deactivating apps.
7. **Use dry-run**: Test deployments with `dry_run=True` first.
8. **Separate environments**: Use different projects/domains for different environments.
9. **Parameter management**: Consider using environment-specific parameter values.

## Deployment status and return value

`flyte.deploy()` returns a list of `Deployment` objects. Each `Deployment` contains a dictionary of `DeployedEnvironment` objects:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""Deploy examples for the how-app-deployment-works.md documentation."""

import flyte
import flyte.app
from flyte.remote import App

# {{docs-fragment basic-deploy}}
app_env = flyte.app.AppEnvironment(
    name="my-prod-app",
    # ...
)

if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(app_env)

    # Access deployed apps from deployments
    for deployment in deployments:
        for deployed_env in deployment.envs.values():
            print(f"Deployed: {deployed_env.env.name}")
            print(f"URL: {deployed_env.deployed_app.url}")
# {{/docs-fragment basic-deploy}}

# {{docs-fragment deployment-plan}}
app1_env = flyte.app.AppEnvironment(name="backend", ...)
app2_env = flyte.app.AppEnvironment(name="frontend", depends_on=[app1_env], ...)

# Deploying app2_env will also deploy app1_env
deployments = flyte.deploy(app2_env)

# deployments contains both app1_env and app2_env
assert len(deployments) == 2
# {{/docs-fragment deployment-plan}}

# {{docs-fragment clone-with}}
app_env = flyte.app.AppEnvironment(name="my-app", ...)

if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(
        app_env.clone_with(app_env.name, resources=flyte.Resources(cpu="2", memory="2Gi"))
    )
    for deployment in deployments:
        for deployed_env in deployment.envs.values():
            print(f"Deployed: {deployed_env.env.name}")
            print(f"URL: {deployed_env.deployed_app.url}")
# {{/docs-fragment clone-with}}

# {{docs-fragment activation-deactivation}}
if __name__ == "__main__":
    flyte.init_from_config()
    deployments = flyte.deploy(app_env)

    app = App.get(name=app_env.name)

    # deactivate the app
    app.deactivate()

    # activate the app
    app.activate()
# {{/docs-fragment activation-deactivation}}

# {{docs-fragment full-deployment}}
if __name__ == "__main__":
    flyte.init_from_config()

    deployments = flyte.deploy(
        app_env,
        dryrun=False,
        version="v1.0.0",
        interactive_mode=False,
        copy_style="loaded_modules",
    )

    # Access deployed apps from deployments
    for deployment in deployments:
        for deployed_env in deployment.envs.values():
            app = deployed_env.deployed_app
            print(f"Deployed: {deployed_env.env.name}")
            print(f"URL: {app.url}")

            # Activate the app
            app.activate()
            print(f"Activated: {app.name}")
# {{/docs-fragment full-deployment}}

# {{docs-fragment deployment-status}}
deployments = flyte.deploy(app_env)

for deployment in deployments:
    for deployed_env in deployment.envs.values():
        if hasattr(deployed_env, 'deployed_app'):
            # Access deployed environment
            env = deployed_env.env
            app = deployed_env.deployed_app

            # Access deployment info
            print(f"Name: {env.name}")
            print(f"URL: {app.url}")
            print(f"Status: {app.deployment_status}")
# {{/docs-fragment deployment-status}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/deploy_examples.py*

For apps, each `DeployedAppEnvironment` includes:

- `env`: The `AppEnvironment` that was deployed
- `deployed_app`: The `App` object with properties like `url`, `endpoint`, `name`, and `deployment_status`

## Troubleshooting

**Deployment fails:**
- Check that all dependencies are available
- Verify image builds succeed
- Review deployment logs

**App not accessible:**
- Ensure the app is activated
- Check cluster connectivity
- Verify app configuration

**Version conflicts:**
- Use unique versions for each deployment
- Check existing app versions
- Clean up old versions if needed


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/serve-and-deploy-apps/activating-and-deactivating-apps ===

# Activating and deactivating apps

Apps deployed with `flyte.deploy()` need to be explicitly activated before they can serve traffic. Apps served with `flyte.serve()` are automatically activated.

## Activation

### Activate after deployment

After deploying an app, activate it:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""Activation examples for the activating-and-deactivating-apps.md documentation."""

import flyte
import flyte.app
from flyte.remote import App

app_env = flyte.app.AppEnvironment(
    name="my-app",
    # ...
)

# {{docs-fragment activate-after-deployment}}
# Deploy the app
deployments = flyte.deploy(app_env)

# Activate the app
app = App.get(name=app_env.name)
app.activate()

print(f"Activated app: {app.name}")
print(f"URL: {app.url}")
# {{/docs-fragment activate-after-deployment}}

# {{docs-fragment activate-app}}
app = App.get(name="my-app")
app.activate()
# {{/docs-fragment activate-app}}

# {{docs-fragment check-activation-status}}
app = App.get(name="my-app")
print(f"Active: {app.is_active()}")
print(f"Revision: {app.revision}")
# {{/docs-fragment check-activation-status}}

# {{docs-fragment deactivation}}
app = App.get(name="my-app")
app.deactivate()

print(f"Deactivated app: {app.name}")
# {{/docs-fragment deactivation}}

# {{docs-fragment typical-deployment-workflow}}
# 1. Deploy new version
deployments = flyte.deploy(
    app_env,
    version="v2.0.0",
)

# 2. Get the deployed app
new_app = App.get(name="my-app")
# Test endpoints, etc.

# 3. Activate the new version
new_app.activate()

print(f"Deployed and activated version {new_app.revision}")
# {{/docs-fragment typical-deployment-workflow}}

# {{docs-fragment blue-green-deployment}}
# Deploy new version without deactivating old
new_deployments = flyte.deploy(
    app_env,
    version="v2.0.0",
)

new_app = App.get(name="my-app")

# Test new version
# ... testing ...

# Switch traffic to new version
new_app.activate()

print(f"Activated revision {new_app.revision}")
# {{/docs-fragment blue-green-deployment}}

# {{docs-fragment automatic-activation}}
# Automatically activated
app = flyte.serve(app_env)
print(f"Active: {app.is_active()}")  # True
# {{/docs-fragment automatic-activation}}

# {{docs-fragment complete-example}}
app_env = flyte.app.AppEnvironment(
    name="my-prod-app",
    # ... configuration ...
)

if __name__ == "__main__":
    flyte.init_from_config()

    # Deploy
    deployments = flyte.deploy(
        app_env,
        version="v1.0.0",
        project="my-project",
        domain="production",
    )

    # Get the deployed app
    app = App.get(name="my-prod-app")

    # Activate
    app.activate()

    print(f"Deployed and activated: {app.name}")
    print(f"Revision: {app.revision}")
    print(f"URL: {app.url}")
    print(f"Active: {app.is_active()}")
# {{/docs-fragment complete-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/activation_examples.py*

### Activate an app

When you get an app by name, you get the current app instance:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""Activation examples for the activating-and-deactivating-apps.md documentation."""

import flyte
import flyte.app
from flyte.remote import App

app_env = flyte.app.AppEnvironment(
    name="my-app",
    # ...
)

# {{docs-fragment activate-after-deployment}}
# Deploy the app
deployments = flyte.deploy(app_env)

# Activate the app
app = App.get(name=app_env.name)
app.activate()

print(f"Activated app: {app.name}")
print(f"URL: {app.url}")
# {{/docs-fragment activate-after-deployment}}

# {{docs-fragment activate-app}}
app = App.get(name="my-app")
app.activate()
# {{/docs-fragment activate-app}}

# {{docs-fragment check-activation-status}}
app = App.get(name="my-app")
print(f"Active: {app.is_active()}")
print(f"Revision: {app.revision}")
# {{/docs-fragment check-activation-status}}

# {{docs-fragment deactivation}}
app = App.get(name="my-app")
app.deactivate()

print(f"Deactivated app: {app.name}")
# {{/docs-fragment deactivation}}

# {{docs-fragment typical-deployment-workflow}}
# 1. Deploy new version
deployments = flyte.deploy(
    app_env,
    version="v2.0.0",
)

# 2. Get the deployed app
new_app = App.get(name="my-app")
# Test endpoints, etc.

# 3. Activate the new version
new_app.activate()

print(f"Deployed and activated version {new_app.revision}")
# {{/docs-fragment typical-deployment-workflow}}

# {{docs-fragment blue-green-deployment}}
# Deploy new version without deactivating old
new_deployments = flyte.deploy(
    app_env,
    version="v2.0.0",
)

new_app = App.get(name="my-app")

# Test new version
# ... testing ...

# Switch traffic to new version
new_app.activate()

print(f"Activated revision {new_app.revision}")
# {{/docs-fragment blue-green-deployment}}

# {{docs-fragment automatic-activation}}
# Automatically activated
app = flyte.serve(app_env)
print(f"Active: {app.is_active()}")  # True
# {{/docs-fragment automatic-activation}}

# {{docs-fragment complete-example}}
app_env = flyte.app.AppEnvironment(
    name="my-prod-app",
    # ... configuration ...
)

if __name__ == "__main__":
    flyte.init_from_config()

    # Deploy
    deployments = flyte.deploy(
        app_env,
        version="v1.0.0",
        project="my-project",
        domain="production",
    )

    # Get the deployed app
    app = App.get(name="my-prod-app")

    # Activate
    app.activate()

    print(f"Deployed and activated: {app.name}")
    print(f"Revision: {app.revision}")
    print(f"URL: {app.url}")
    print(f"Active: {app.is_active()}")
# {{/docs-fragment complete-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/activation_examples.py*

### Check activation status

Check if an app is active:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""Activation examples for the activating-and-deactivating-apps.md documentation."""

import flyte
import flyte.app
from flyte.remote import App

app_env = flyte.app.AppEnvironment(
    name="my-app",
    # ...
)

# {{docs-fragment activate-after-deployment}}
# Deploy the app
deployments = flyte.deploy(app_env)

# Activate the app
app = App.get(name=app_env.name)
app.activate()

print(f"Activated app: {app.name}")
print(f"URL: {app.url}")
# {{/docs-fragment activate-after-deployment}}

# {{docs-fragment activate-app}}
app = App.get(name="my-app")
app.activate()
# {{/docs-fragment activate-app}}

# {{docs-fragment check-activation-status}}
app = App.get(name="my-app")
print(f"Active: {app.is_active()}")
print(f"Revision: {app.revision}")
# {{/docs-fragment check-activation-status}}

# {{docs-fragment deactivation}}
app = App.get(name="my-app")
app.deactivate()

print(f"Deactivated app: {app.name}")
# {{/docs-fragment deactivation}}

# {{docs-fragment typical-deployment-workflow}}
# 1. Deploy new version
deployments = flyte.deploy(
    app_env,
    version="v2.0.0",
)

# 2. Get the deployed app
new_app = App.get(name="my-app")
# Test endpoints, etc.

# 3. Activate the new version
new_app.activate()

print(f"Deployed and activated version {new_app.revision}")
# {{/docs-fragment typical-deployment-workflow}}

# {{docs-fragment blue-green-deployment}}
# Deploy new version without deactivating old
new_deployments = flyte.deploy(
    app_env,
    version="v2.0.0",
)

new_app = App.get(name="my-app")

# Test new version
# ... testing ...

# Switch traffic to new version
new_app.activate()

print(f"Activated revision {new_app.revision}")
# {{/docs-fragment blue-green-deployment}}

# {{docs-fragment automatic-activation}}
# Automatically activated
app = flyte.serve(app_env)
print(f"Active: {app.is_active()}")  # True
# {{/docs-fragment automatic-activation}}

# {{docs-fragment complete-example}}
app_env = flyte.app.AppEnvironment(
    name="my-prod-app",
    # ... configuration ...
)

if __name__ == "__main__":
    flyte.init_from_config()

    # Deploy
    deployments = flyte.deploy(
        app_env,
        version="v1.0.0",
        project="my-project",
        domain="production",
    )

    # Get the deployed app
    app = App.get(name="my-prod-app")

    # Activate
    app.activate()

    print(f"Deployed and activated: {app.name}")
    print(f"Revision: {app.revision}")
    print(f"URL: {app.url}")
    print(f"Active: {app.is_active()}")
# {{/docs-fragment complete-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/activation_examples.py*

## Deactivation

Deactivate an app when you no longer need it:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""Activation examples for the activating-and-deactivating-apps.md documentation."""

import flyte
import flyte.app
from flyte.remote import App

app_env = flyte.app.AppEnvironment(
    name="my-app",
    # ...
)

# {{docs-fragment activate-after-deployment}}
# Deploy the app
deployments = flyte.deploy(app_env)

# Activate the app
app = App.get(name=app_env.name)
app.activate()

print(f"Activated app: {app.name}")
print(f"URL: {app.url}")
# {{/docs-fragment activate-after-deployment}}

# {{docs-fragment activate-app}}
app = App.get(name="my-app")
app.activate()
# {{/docs-fragment activate-app}}

# {{docs-fragment check-activation-status}}
app = App.get(name="my-app")
print(f"Active: {app.is_active()}")
print(f"Revision: {app.revision}")
# {{/docs-fragment check-activation-status}}

# {{docs-fragment deactivation}}
app = App.get(name="my-app")
app.deactivate()

print(f"Deactivated app: {app.name}")
# {{/docs-fragment deactivation}}

# {{docs-fragment typical-deployment-workflow}}
# 1. Deploy new version
deployments = flyte.deploy(
    app_env,
    version="v2.0.0",
)

# 2. Get the deployed app
new_app = App.get(name="my-app")
# Test endpoints, etc.

# 3. Activate the new version
new_app.activate()

print(f"Deployed and activated version {new_app.revision}")
# {{/docs-fragment typical-deployment-workflow}}

# {{docs-fragment blue-green-deployment}}
# Deploy new version without deactivating old
new_deployments = flyte.deploy(
    app_env,
    version="v2.0.0",
)

new_app = App.get(name="my-app")

# Test new version
# ... testing ...

# Switch traffic to new version
new_app.activate()

print(f"Activated revision {new_app.revision}")
# {{/docs-fragment blue-green-deployment}}

# {{docs-fragment automatic-activation}}
# Automatically activated
app = flyte.serve(app_env)
print(f"Active: {app.is_active()}")  # True
# {{/docs-fragment automatic-activation}}

# {{docs-fragment complete-example}}
app_env = flyte.app.AppEnvironment(
    name="my-prod-app",
    # ... configuration ...
)

if __name__ == "__main__":
    flyte.init_from_config()

    # Deploy
    deployments = flyte.deploy(
        app_env,
        version="v1.0.0",
        project="my-project",
        domain="production",
    )

    # Get the deployed app
    app = App.get(name="my-prod-app")

    # Activate
    app.activate()

    print(f"Deployed and activated: {app.name}")
    print(f"Revision: {app.revision}")
    print(f"URL: {app.url}")
    print(f"Active: {app.is_active()}")
# {{/docs-fragment complete-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/activation_examples.py*

## Lifecycle management

### Typical deployment workflow

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""Activation examples for the activating-and-deactivating-apps.md documentation."""

import flyte
import flyte.app
from flyte.remote import App

app_env = flyte.app.AppEnvironment(
    name="my-app",
    # ...
)

# {{docs-fragment activate-after-deployment}}
# Deploy the app
deployments = flyte.deploy(app_env)

# Activate the app
app = App.get(name=app_env.name)
app.activate()

print(f"Activated app: {app.name}")
print(f"URL: {app.url}")
# {{/docs-fragment activate-after-deployment}}

# {{docs-fragment activate-app}}
app = App.get(name="my-app")
app.activate()
# {{/docs-fragment activate-app}}

# {{docs-fragment check-activation-status}}
app = App.get(name="my-app")
print(f"Active: {app.is_active()}")
print(f"Revision: {app.revision}")
# {{/docs-fragment check-activation-status}}

# {{docs-fragment deactivation}}
app = App.get(name="my-app")
app.deactivate()

print(f"Deactivated app: {app.name}")
# {{/docs-fragment deactivation}}

# {{docs-fragment typical-deployment-workflow}}
# 1. Deploy new version
deployments = flyte.deploy(
    app_env,
    version="v2.0.0",
)

# 2. Get the deployed app
new_app = App.get(name="my-app")
# Test endpoints, etc.

# 3. Activate the new version
new_app.activate()

print(f"Deployed and activated version {new_app.revision}")
# {{/docs-fragment typical-deployment-workflow}}

# {{docs-fragment blue-green-deployment}}
# Deploy new version without deactivating old
new_deployments = flyte.deploy(
    app_env,
    version="v2.0.0",
)

new_app = App.get(name="my-app")

# Test new version
# ... testing ...

# Switch traffic to new version
new_app.activate()

print(f"Activated revision {new_app.revision}")
# {{/docs-fragment blue-green-deployment}}

# {{docs-fragment automatic-activation}}
# Automatically activated
app = flyte.serve(app_env)
print(f"Active: {app.is_active()}")  # True
# {{/docs-fragment automatic-activation}}

# {{docs-fragment complete-example}}
app_env = flyte.app.AppEnvironment(
    name="my-prod-app",
    # ... configuration ...
)

if __name__ == "__main__":
    flyte.init_from_config()

    # Deploy
    deployments = flyte.deploy(
        app_env,
        version="v1.0.0",
        project="my-project",
        domain="production",
    )

    # Get the deployed app
    app = App.get(name="my-prod-app")

    # Activate
    app.activate()

    print(f"Deployed and activated: {app.name}")
    print(f"Revision: {app.revision}")
    print(f"URL: {app.url}")
    print(f"Active: {app.is_active()}")
# {{/docs-fragment complete-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/activation_examples.py*

### Blue-green deployment

For zero-downtime deployments:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""Activation examples for the activating-and-deactivating-apps.md documentation."""

import flyte
import flyte.app
from flyte.remote import App

app_env = flyte.app.AppEnvironment(
    name="my-app",
    # ...
)

# {{docs-fragment activate-after-deployment}}
# Deploy the app
deployments = flyte.deploy(app_env)

# Activate the app
app = App.get(name=app_env.name)
app.activate()

print(f"Activated app: {app.name}")
print(f"URL: {app.url}")
# {{/docs-fragment activate-after-deployment}}

# {{docs-fragment activate-app}}
app = App.get(name="my-app")
app.activate()
# {{/docs-fragment activate-app}}

# {{docs-fragment check-activation-status}}
app = App.get(name="my-app")
print(f"Active: {app.is_active()}")
print(f"Revision: {app.revision}")
# {{/docs-fragment check-activation-status}}

# {{docs-fragment deactivation}}
app = App.get(name="my-app")
app.deactivate()

print(f"Deactivated app: {app.name}")
# {{/docs-fragment deactivation}}

# {{docs-fragment typical-deployment-workflow}}
# 1. Deploy new version
deployments = flyte.deploy(
    app_env,
    version="v2.0.0",
)

# 2. Get the deployed app
new_app = App.get(name="my-app")
# Test endpoints, etc.

# 3. Activate the new version
new_app.activate()

print(f"Deployed and activated version {new_app.revision}")
# {{/docs-fragment typical-deployment-workflow}}

# {{docs-fragment blue-green-deployment}}
# Deploy new version without deactivating old
new_deployments = flyte.deploy(
    app_env,
    version="v2.0.0",
)

new_app = App.get(name="my-app")

# Test new version
# ... testing ...

# Switch traffic to new version
new_app.activate()

print(f"Activated revision {new_app.revision}")
# {{/docs-fragment blue-green-deployment}}

# {{docs-fragment automatic-activation}}
# Automatically activated
app = flyte.serve(app_env)
print(f"Active: {app.is_active()}")  # True
# {{/docs-fragment automatic-activation}}

# {{docs-fragment complete-example}}
app_env = flyte.app.AppEnvironment(
    name="my-prod-app",
    # ... configuration ...
)

if __name__ == "__main__":
    flyte.init_from_config()

    # Deploy
    deployments = flyte.deploy(
        app_env,
        version="v1.0.0",
        project="my-project",
        domain="production",
    )

    # Get the deployed app
    app = App.get(name="my-prod-app")

    # Activate
    app.activate()

    print(f"Deployed and activated: {app.name}")
    print(f"Revision: {app.revision}")
    print(f"URL: {app.url}")
    print(f"Active: {app.is_active()}")
# {{/docs-fragment complete-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/activation_examples.py*

## Using CLI

### Activate

```bash
flyte update app --activate my-app
```

### Deactivate

```bash
flyte update app --deactivate my-app
```

### Check status

```bash
flyte get app my-app
```

Use `--project` and `--domain` to target a specific [project-domain pair](../projects-and-domains).
For all available options, see the [CLI reference](../../api-reference/flyte-cli).

## Best practices

1. **Activate after testing**: Test deployed apps before activating
2. **Version management**: Keep track of which version is active
4. **Blue-green deployments**: Use blue-green for zero-downtime
5. **Monitor**: Monitor apps after activation
6. **Cleanup**: Deactivate and remove old versions periodically

## Automatic activation with serve

Apps served with `flyte.serve()` are automatically activated:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""Activation examples for the activating-and-deactivating-apps.md documentation."""

import flyte
import flyte.app
from flyte.remote import App

app_env = flyte.app.AppEnvironment(
    name="my-app",
    # ...
)

# {{docs-fragment activate-after-deployment}}
# Deploy the app
deployments = flyte.deploy(app_env)

# Activate the app
app = App.get(name=app_env.name)
app.activate()

print(f"Activated app: {app.name}")
print(f"URL: {app.url}")
# {{/docs-fragment activate-after-deployment}}

# {{docs-fragment activate-app}}
app = App.get(name="my-app")
app.activate()
# {{/docs-fragment activate-app}}

# {{docs-fragment check-activation-status}}
app = App.get(name="my-app")
print(f"Active: {app.is_active()}")
print(f"Revision: {app.revision}")
# {{/docs-fragment check-activation-status}}

# {{docs-fragment deactivation}}
app = App.get(name="my-app")
app.deactivate()

print(f"Deactivated app: {app.name}")
# {{/docs-fragment deactivation}}

# {{docs-fragment typical-deployment-workflow}}
# 1. Deploy new version
deployments = flyte.deploy(
    app_env,
    version="v2.0.0",
)

# 2. Get the deployed app
new_app = App.get(name="my-app")
# Test endpoints, etc.

# 3. Activate the new version
new_app.activate()

print(f"Deployed and activated version {new_app.revision}")
# {{/docs-fragment typical-deployment-workflow}}

# {{docs-fragment blue-green-deployment}}
# Deploy new version without deactivating old
new_deployments = flyte.deploy(
    app_env,
    version="v2.0.0",
)

new_app = App.get(name="my-app")

# Test new version
# ... testing ...

# Switch traffic to new version
new_app.activate()

print(f"Activated revision {new_app.revision}")
# {{/docs-fragment blue-green-deployment}}

# {{docs-fragment automatic-activation}}
# Automatically activated
app = flyte.serve(app_env)
print(f"Active: {app.is_active()}")  # True
# {{/docs-fragment automatic-activation}}

# {{docs-fragment complete-example}}
app_env = flyte.app.AppEnvironment(
    name="my-prod-app",
    # ... configuration ...
)

if __name__ == "__main__":
    flyte.init_from_config()

    # Deploy
    deployments = flyte.deploy(
        app_env,
        version="v1.0.0",
        project="my-project",
        domain="production",
    )

    # Get the deployed app
    app = App.get(name="my-prod-app")

    # Activate
    app.activate()

    print(f"Deployed and activated: {app.name}")
    print(f"Revision: {app.revision}")
    print(f"URL: {app.url}")
    print(f"Active: {app.is_active()}")
# {{/docs-fragment complete-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/activation_examples.py*

This is convenient for development but less suitable for production where you want explicit control over activation.

## Example: Complete deployment and activation

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
# ]
# ///

"""Activation examples for the activating-and-deactivating-apps.md documentation."""

import flyte
import flyte.app
from flyte.remote import App

app_env = flyte.app.AppEnvironment(
    name="my-app",
    # ...
)

# {{docs-fragment activate-after-deployment}}
# Deploy the app
deployments = flyte.deploy(app_env)

# Activate the app
app = App.get(name=app_env.name)
app.activate()

print(f"Activated app: {app.name}")
print(f"URL: {app.url}")
# {{/docs-fragment activate-after-deployment}}

# {{docs-fragment activate-app}}
app = App.get(name="my-app")
app.activate()
# {{/docs-fragment activate-app}}

# {{docs-fragment check-activation-status}}
app = App.get(name="my-app")
print(f"Active: {app.is_active()}")
print(f"Revision: {app.revision}")
# {{/docs-fragment check-activation-status}}

# {{docs-fragment deactivation}}
app = App.get(name="my-app")
app.deactivate()

print(f"Deactivated app: {app.name}")
# {{/docs-fragment deactivation}}

# {{docs-fragment typical-deployment-workflow}}
# 1. Deploy new version
deployments = flyte.deploy(
    app_env,
    version="v2.0.0",
)

# 2. Get the deployed app
new_app = App.get(name="my-app")
# Test endpoints, etc.

# 3. Activate the new version
new_app.activate()

print(f"Deployed and activated version {new_app.revision}")
# {{/docs-fragment typical-deployment-workflow}}

# {{docs-fragment blue-green-deployment}}
# Deploy new version without deactivating old
new_deployments = flyte.deploy(
    app_env,
    version="v2.0.0",
)

new_app = App.get(name="my-app")

# Test new version
# ... testing ...

# Switch traffic to new version
new_app.activate()

print(f"Activated revision {new_app.revision}")
# {{/docs-fragment blue-green-deployment}}

# {{docs-fragment automatic-activation}}
# Automatically activated
app = flyte.serve(app_env)
print(f"Active: {app.is_active()}")  # True
# {{/docs-fragment automatic-activation}}

# {{docs-fragment complete-example}}
app_env = flyte.app.AppEnvironment(
    name="my-prod-app",
    # ... configuration ...
)

if __name__ == "__main__":
    flyte.init_from_config()

    # Deploy
    deployments = flyte.deploy(
        app_env,
        version="v1.0.0",
        project="my-project",
        domain="production",
    )

    # Get the deployed app
    app = App.get(name="my-prod-app")

    # Activate
    app.activate()

    print(f"Deployed and activated: {app.name}")
    print(f"Revision: {app.revision}")
    print(f"URL: {app.url}")
    print(f"Active: {app.is_active()}")
# {{/docs-fragment complete-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/activation_examples.py*

## Troubleshooting

**App not accessible after activation:**
- Verify activation succeeded
- Check app logs for startup errors
- Verify cluster connectivity
- Check that the app is listening on the correct port

**Activation fails:**
- Check that the app was deployed successfully
- Verify app configuration is correct
- Check cluster resources
- Review deployment logs

**Cannot deactivate:**
- Ensure you have proper permissions
- Check if there are dependencies preventing deactivation
- Verify the app name and version


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/serve-and-deploy-apps/prefetching-models ===

# Prefetching models

Prefetching allows you to download and prepare HuggingFace models (including sharding for multi-GPU inference) before
deploying [vLLM](../build-apps/vllm-app) or [SGLang](../build-apps/sglang-app) apps. This speeds up deployment and ensures models are ready when your app starts.

## Why prefetch?

Prefetching models provides several benefits:

- **Faster deployment**: Models are pre-downloaded, so apps start faster
- **Reproducibility**: Models are versioned and stored in Flyte's object store
- **Sharding support**: Pre-shard models for multi-GPU tensor parallelism
- **Cost efficiency**: Download once, use many times
- **Offline support**: Models are cached in your storage backend

## Basic prefetch

### Using Python SDK

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-vllm>=2.0.0b49",
# ]
# ///

"""Prefetch examples for the prefetching-models.md documentation."""

import flyte
from flyte.prefetch import ShardConfig, VLLMShardArgs
from flyteplugins.vllm import VLLMAppEnvironment

# {{docs-fragment basic-prefetch}}
# Prefetch a HuggingFace model
run = flyte.prefetch.hf_model(repo="Qwen/Qwen3-0.6B")

# Wait for prefetch to complete
run.wait()

# Get the model path
model_path = run.outputs()[0].path
print(f"Model prefetched to: {model_path}")
# {{/docs-fragment basic-prefetch}}

# {{docs-fragment using-prefetched-models}}
# Prefetch the model
run = flyte.prefetch.hf_model(repo="Qwen/Qwen3-0.6B")
run.wait()

# Use the prefetched model
vllm_app = VLLMAppEnvironment(
    name="my-llm-app",
    model_path=flyte.app.RunOutput(
        type="directory",
        run_name=run.name,
    ),
    model_id="qwen3-0.6b",
    resources=flyte.Resources(cpu="4", memory="16Gi", gpu="L40s:1"),
    stream_model=True,
)

app = flyte.serve(vllm_app)
# {{/docs-fragment using-prefetched-models}}

# {{docs-fragment custom-artifact-name}}
run = flyte.prefetch.hf_model(
    repo="Qwen/Qwen3-0.6B",
    artifact_name="qwen-0.6b-model",  # Custom name for the stored model
)
# {{/docs-fragment custom-artifact-name}}

# {{docs-fragment hf-token}}
run = flyte.prefetch.hf_model(
    repo="meta-llama/Llama-2-7b-hf",
    hf_token_key="HF_TOKEN",  # Name of Flyte secret containing HF token
)
# {{/docs-fragment hf-token}}

# {{docs-fragment with-resources}}
run = flyte.prefetch.hf_model(
    repo="Qwen/Qwen3-0.6B",
    cpu="4",
    mem="16Gi",
    ephemeral_storage="100Gi",
)
# {{/docs-fragment with-resources}}

# {{docs-fragment vllm-sharding}}
run = flyte.prefetch.hf_model(
    repo="meta-llama/Llama-2-70b-hf",
    resources=flyte.Resources(cpu="8", memory="32Gi", gpu="L40s:4"),
    shard_config=ShardConfig(
        engine="vllm",
        args=VLLMShardArgs(
            tensor_parallel_size=4,
            dtype="auto",
            trust_remote_code=True,
        ),
    ),
    hf_token_key="HF_TOKEN",
)

run.wait()
# {{/docs-fragment vllm-sharding}}

# {{docs-fragment using-sharded-models}}
# Use in vLLM app
vllm_app = VLLMAppEnvironment(
    name="multi-gpu-llm-app",
    # this will download the model from HuggingFace into the app container's filesystem
    model_hf_path="Qwen/Qwen3-0.6B",
    model_id="llama-2-70b",
    resources=flyte.Resources(
        cpu="8",
        memory="32Gi",
        gpu="L40s:4",  # Match the number of GPUs used for sharding
    ),
    extra_args=[
        "--tensor-parallel-size", "4",  # Match sharding config
    ],
)

if __name__ == "__main__":
    # Prefetch with sharding
    run = flyte.prefetch.hf_model(
        repo="meta-llama/Llama-2-70b-hf",
        accelerator="L40s:4",
        shard_config=ShardConfig(
            engine="vllm",
            args=VLLMShardArgs(tensor_parallel_size=4),
        ),
    )
    run.wait()

    flyte.serve(
        vllm_app.clone_with(
            name=vllm_app.name,
            # override the model path to use the prefetched model
            model_path=flyte.app.RunOutput(type="directory", run_name=run.name),
            # set the hf_model_path to None
            hf_model_path=None,
            # stream the model from flyte object store directly to the GPU
            stream_model=True,
        )
    )
# {{/docs-fragment using-sharded-models}}

# {{docs-fragment complete-example}}
# define the app environment
vllm_app = VLLMAppEnvironment(
    name="qwen-serving-app",
    # this will download the model from HuggingFace into the app container's filesystem
    model_hf_path="Qwen/Qwen3-0.6B",
    model_id="qwen3-0.6b",
    resources=flyte.Resources(
        cpu="4",
        memory="16Gi",
        gpu="L40s:1",
        disk="10Gi",
    ),
    scaling=flyte.app.Scaling(
        replicas=(0, 1),
        scaledown_after=600,
    ),
    requires_auth=False,
)

if __name__ == "__main__":
    # prefetch the model
    print("Prefetching model...")
    run = flyte.prefetch.hf_model(
        repo="Qwen/Qwen3-0.6B",
        artifact_name="qwen-0.6b",
        cpu="4",
        mem="16Gi",
        ephemeral_storage="50Gi",
    )

    # wait for completion
    print("Waiting for prefetch to complete...")
    run.wait()
    print(f"Model prefetched: {run.outputs()[0].path}")

    # deploy the app
    print("Deploying app...")
    flyte.init_from_config()
    app = flyte.serve(
        vllm_app.clone_with(
            name=vllm_app.name,
            model_path=flyte.app.RunOutput(type="directory", run_name=run.name),
            hf_model_path=None,
            stream_model=True,
        )
    )
    print(f"App deployed: {app.url}")
# {{/docs-fragment complete-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/prefetch_examples.py*

### Using CLI

```bash
flyte prefetch hf-model Qwen/Qwen3-0.6B
```

Wait for completion:

```bash
flyte prefetch hf-model Qwen/Qwen3-0.6B --wait
```

## Using prefetched models

Use the prefetched model in your vLLM or SGLang app:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-vllm>=2.0.0b49",
# ]
# ///

"""Prefetch examples for the prefetching-models.md documentation."""

import flyte
from flyte.prefetch import ShardConfig, VLLMShardArgs
from flyteplugins.vllm import VLLMAppEnvironment

# {{docs-fragment basic-prefetch}}
# Prefetch a HuggingFace model
run = flyte.prefetch.hf_model(repo="Qwen/Qwen3-0.6B")

# Wait for prefetch to complete
run.wait()

# Get the model path
model_path = run.outputs()[0].path
print(f"Model prefetched to: {model_path}")
# {{/docs-fragment basic-prefetch}}

# {{docs-fragment using-prefetched-models}}
# Prefetch the model
run = flyte.prefetch.hf_model(repo="Qwen/Qwen3-0.6B")
run.wait()

# Use the prefetched model
vllm_app = VLLMAppEnvironment(
    name="my-llm-app",
    model_path=flyte.app.RunOutput(
        type="directory",
        run_name=run.name,
    ),
    model_id="qwen3-0.6b",
    resources=flyte.Resources(cpu="4", memory="16Gi", gpu="L40s:1"),
    stream_model=True,
)

app = flyte.serve(vllm_app)
# {{/docs-fragment using-prefetched-models}}

# {{docs-fragment custom-artifact-name}}
run = flyte.prefetch.hf_model(
    repo="Qwen/Qwen3-0.6B",
    artifact_name="qwen-0.6b-model",  # Custom name for the stored model
)
# {{/docs-fragment custom-artifact-name}}

# {{docs-fragment hf-token}}
run = flyte.prefetch.hf_model(
    repo="meta-llama/Llama-2-7b-hf",
    hf_token_key="HF_TOKEN",  # Name of Flyte secret containing HF token
)
# {{/docs-fragment hf-token}}

# {{docs-fragment with-resources}}
run = flyte.prefetch.hf_model(
    repo="Qwen/Qwen3-0.6B",
    cpu="4",
    mem="16Gi",
    ephemeral_storage="100Gi",
)
# {{/docs-fragment with-resources}}

# {{docs-fragment vllm-sharding}}
run = flyte.prefetch.hf_model(
    repo="meta-llama/Llama-2-70b-hf",
    resources=flyte.Resources(cpu="8", memory="32Gi", gpu="L40s:4"),
    shard_config=ShardConfig(
        engine="vllm",
        args=VLLMShardArgs(
            tensor_parallel_size=4,
            dtype="auto",
            trust_remote_code=True,
        ),
    ),
    hf_token_key="HF_TOKEN",
)

run.wait()
# {{/docs-fragment vllm-sharding}}

# {{docs-fragment using-sharded-models}}
# Use in vLLM app
vllm_app = VLLMAppEnvironment(
    name="multi-gpu-llm-app",
    # this will download the model from HuggingFace into the app container's filesystem
    model_hf_path="Qwen/Qwen3-0.6B",
    model_id="llama-2-70b",
    resources=flyte.Resources(
        cpu="8",
        memory="32Gi",
        gpu="L40s:4",  # Match the number of GPUs used for sharding
    ),
    extra_args=[
        "--tensor-parallel-size", "4",  # Match sharding config
    ],
)

if __name__ == "__main__":
    # Prefetch with sharding
    run = flyte.prefetch.hf_model(
        repo="meta-llama/Llama-2-70b-hf",
        accelerator="L40s:4",
        shard_config=ShardConfig(
            engine="vllm",
            args=VLLMShardArgs(tensor_parallel_size=4),
        ),
    )
    run.wait()

    flyte.serve(
        vllm_app.clone_with(
            name=vllm_app.name,
            # override the model path to use the prefetched model
            model_path=flyte.app.RunOutput(type="directory", run_name=run.name),
            # set the hf_model_path to None
            hf_model_path=None,
            # stream the model from flyte object store directly to the GPU
            stream_model=True,
        )
    )
# {{/docs-fragment using-sharded-models}}

# {{docs-fragment complete-example}}
# define the app environment
vllm_app = VLLMAppEnvironment(
    name="qwen-serving-app",
    # this will download the model from HuggingFace into the app container's filesystem
    model_hf_path="Qwen/Qwen3-0.6B",
    model_id="qwen3-0.6b",
    resources=flyte.Resources(
        cpu="4",
        memory="16Gi",
        gpu="L40s:1",
        disk="10Gi",
    ),
    scaling=flyte.app.Scaling(
        replicas=(0, 1),
        scaledown_after=600,
    ),
    requires_auth=False,
)

if __name__ == "__main__":
    # prefetch the model
    print("Prefetching model...")
    run = flyte.prefetch.hf_model(
        repo="Qwen/Qwen3-0.6B",
        artifact_name="qwen-0.6b",
        cpu="4",
        mem="16Gi",
        ephemeral_storage="50Gi",
    )

    # wait for completion
    print("Waiting for prefetch to complete...")
    run.wait()
    print(f"Model prefetched: {run.outputs()[0].path}")

    # deploy the app
    print("Deploying app...")
    flyte.init_from_config()
    app = flyte.serve(
        vllm_app.clone_with(
            name=vllm_app.name,
            model_path=flyte.app.RunOutput(type="directory", run_name=run.name),
            hf_model_path=None,
            stream_model=True,
        )
    )
    print(f"App deployed: {app.url}")
# {{/docs-fragment complete-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/prefetch_examples.py*

> [!TIP]
> You can also use prefetched models as parameters to your generic `[[AppEnvironment]]`s or `FastAPIAppEnvironment`s.

## Prefetch options

### Custom artifact name

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-vllm>=2.0.0b49",
# ]
# ///

"""Prefetch examples for the prefetching-models.md documentation."""

import flyte
from flyte.prefetch import ShardConfig, VLLMShardArgs
from flyteplugins.vllm import VLLMAppEnvironment

# {{docs-fragment basic-prefetch}}
# Prefetch a HuggingFace model
run = flyte.prefetch.hf_model(repo="Qwen/Qwen3-0.6B")

# Wait for prefetch to complete
run.wait()

# Get the model path
model_path = run.outputs()[0].path
print(f"Model prefetched to: {model_path}")
# {{/docs-fragment basic-prefetch}}

# {{docs-fragment using-prefetched-models}}
# Prefetch the model
run = flyte.prefetch.hf_model(repo="Qwen/Qwen3-0.6B")
run.wait()

# Use the prefetched model
vllm_app = VLLMAppEnvironment(
    name="my-llm-app",
    model_path=flyte.app.RunOutput(
        type="directory",
        run_name=run.name,
    ),
    model_id="qwen3-0.6b",
    resources=flyte.Resources(cpu="4", memory="16Gi", gpu="L40s:1"),
    stream_model=True,
)

app = flyte.serve(vllm_app)
# {{/docs-fragment using-prefetched-models}}

# {{docs-fragment custom-artifact-name}}
run = flyte.prefetch.hf_model(
    repo="Qwen/Qwen3-0.6B",
    artifact_name="qwen-0.6b-model",  # Custom name for the stored model
)
# {{/docs-fragment custom-artifact-name}}

# {{docs-fragment hf-token}}
run = flyte.prefetch.hf_model(
    repo="meta-llama/Llama-2-7b-hf",
    hf_token_key="HF_TOKEN",  # Name of Flyte secret containing HF token
)
# {{/docs-fragment hf-token}}

# {{docs-fragment with-resources}}
run = flyte.prefetch.hf_model(
    repo="Qwen/Qwen3-0.6B",
    cpu="4",
    mem="16Gi",
    ephemeral_storage="100Gi",
)
# {{/docs-fragment with-resources}}

# {{docs-fragment vllm-sharding}}
run = flyte.prefetch.hf_model(
    repo="meta-llama/Llama-2-70b-hf",
    resources=flyte.Resources(cpu="8", memory="32Gi", gpu="L40s:4"),
    shard_config=ShardConfig(
        engine="vllm",
        args=VLLMShardArgs(
            tensor_parallel_size=4,
            dtype="auto",
            trust_remote_code=True,
        ),
    ),
    hf_token_key="HF_TOKEN",
)

run.wait()
# {{/docs-fragment vllm-sharding}}

# {{docs-fragment using-sharded-models}}
# Use in vLLM app
vllm_app = VLLMAppEnvironment(
    name="multi-gpu-llm-app",
    # this will download the model from HuggingFace into the app container's filesystem
    model_hf_path="Qwen/Qwen3-0.6B",
    model_id="llama-2-70b",
    resources=flyte.Resources(
        cpu="8",
        memory="32Gi",
        gpu="L40s:4",  # Match the number of GPUs used for sharding
    ),
    extra_args=[
        "--tensor-parallel-size", "4",  # Match sharding config
    ],
)

if __name__ == "__main__":
    # Prefetch with sharding
    run = flyte.prefetch.hf_model(
        repo="meta-llama/Llama-2-70b-hf",
        accelerator="L40s:4",
        shard_config=ShardConfig(
            engine="vllm",
            args=VLLMShardArgs(tensor_parallel_size=4),
        ),
    )
    run.wait()

    flyte.serve(
        vllm_app.clone_with(
            name=vllm_app.name,
            # override the model path to use the prefetched model
            model_path=flyte.app.RunOutput(type="directory", run_name=run.name),
            # set the hf_model_path to None
            hf_model_path=None,
            # stream the model from flyte object store directly to the GPU
            stream_model=True,
        )
    )
# {{/docs-fragment using-sharded-models}}

# {{docs-fragment complete-example}}
# define the app environment
vllm_app = VLLMAppEnvironment(
    name="qwen-serving-app",
    # this will download the model from HuggingFace into the app container's filesystem
    model_hf_path="Qwen/Qwen3-0.6B",
    model_id="qwen3-0.6b",
    resources=flyte.Resources(
        cpu="4",
        memory="16Gi",
        gpu="L40s:1",
        disk="10Gi",
    ),
    scaling=flyte.app.Scaling(
        replicas=(0, 1),
        scaledown_after=600,
    ),
    requires_auth=False,
)

if __name__ == "__main__":
    # prefetch the model
    print("Prefetching model...")
    run = flyte.prefetch.hf_model(
        repo="Qwen/Qwen3-0.6B",
        artifact_name="qwen-0.6b",
        cpu="4",
        mem="16Gi",
        ephemeral_storage="50Gi",
    )

    # wait for completion
    print("Waiting for prefetch to complete...")
    run.wait()
    print(f"Model prefetched: {run.outputs()[0].path}")

    # deploy the app
    print("Deploying app...")
    flyte.init_from_config()
    app = flyte.serve(
        vllm_app.clone_with(
            name=vllm_app.name,
            model_path=flyte.app.RunOutput(type="directory", run_name=run.name),
            hf_model_path=None,
            stream_model=True,
        )
    )
    print(f"App deployed: {app.url}")
# {{/docs-fragment complete-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/prefetch_examples.py*

### With HuggingFace token

If the model requires authentication:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-vllm>=2.0.0b49",
# ]
# ///

"""Prefetch examples for the prefetching-models.md documentation."""

import flyte
from flyte.prefetch import ShardConfig, VLLMShardArgs
from flyteplugins.vllm import VLLMAppEnvironment

# {{docs-fragment basic-prefetch}}
# Prefetch a HuggingFace model
run = flyte.prefetch.hf_model(repo="Qwen/Qwen3-0.6B")

# Wait for prefetch to complete
run.wait()

# Get the model path
model_path = run.outputs()[0].path
print(f"Model prefetched to: {model_path}")
# {{/docs-fragment basic-prefetch}}

# {{docs-fragment using-prefetched-models}}
# Prefetch the model
run = flyte.prefetch.hf_model(repo="Qwen/Qwen3-0.6B")
run.wait()

# Use the prefetched model
vllm_app = VLLMAppEnvironment(
    name="my-llm-app",
    model_path=flyte.app.RunOutput(
        type="directory",
        run_name=run.name,
    ),
    model_id="qwen3-0.6b",
    resources=flyte.Resources(cpu="4", memory="16Gi", gpu="L40s:1"),
    stream_model=True,
)

app = flyte.serve(vllm_app)
# {{/docs-fragment using-prefetched-models}}

# {{docs-fragment custom-artifact-name}}
run = flyte.prefetch.hf_model(
    repo="Qwen/Qwen3-0.6B",
    artifact_name="qwen-0.6b-model",  # Custom name for the stored model
)
# {{/docs-fragment custom-artifact-name}}

# {{docs-fragment hf-token}}
run = flyte.prefetch.hf_model(
    repo="meta-llama/Llama-2-7b-hf",
    hf_token_key="HF_TOKEN",  # Name of Flyte secret containing HF token
)
# {{/docs-fragment hf-token}}

# {{docs-fragment with-resources}}
run = flyte.prefetch.hf_model(
    repo="Qwen/Qwen3-0.6B",
    cpu="4",
    mem="16Gi",
    ephemeral_storage="100Gi",
)
# {{/docs-fragment with-resources}}

# {{docs-fragment vllm-sharding}}
run = flyte.prefetch.hf_model(
    repo="meta-llama/Llama-2-70b-hf",
    resources=flyte.Resources(cpu="8", memory="32Gi", gpu="L40s:4"),
    shard_config=ShardConfig(
        engine="vllm",
        args=VLLMShardArgs(
            tensor_parallel_size=4,
            dtype="auto",
            trust_remote_code=True,
        ),
    ),
    hf_token_key="HF_TOKEN",
)

run.wait()
# {{/docs-fragment vllm-sharding}}

# {{docs-fragment using-sharded-models}}
# Use in vLLM app
vllm_app = VLLMAppEnvironment(
    name="multi-gpu-llm-app",
    # this will download the model from HuggingFace into the app container's filesystem
    model_hf_path="Qwen/Qwen3-0.6B",
    model_id="llama-2-70b",
    resources=flyte.Resources(
        cpu="8",
        memory="32Gi",
        gpu="L40s:4",  # Match the number of GPUs used for sharding
    ),
    extra_args=[
        "--tensor-parallel-size", "4",  # Match sharding config
    ],
)

if __name__ == "__main__":
    # Prefetch with sharding
    run = flyte.prefetch.hf_model(
        repo="meta-llama/Llama-2-70b-hf",
        accelerator="L40s:4",
        shard_config=ShardConfig(
            engine="vllm",
            args=VLLMShardArgs(tensor_parallel_size=4),
        ),
    )
    run.wait()

    flyte.serve(
        vllm_app.clone_with(
            name=vllm_app.name,
            # override the model path to use the prefetched model
            model_path=flyte.app.RunOutput(type="directory", run_name=run.name),
            # set the hf_model_path to None
            hf_model_path=None,
            # stream the model from flyte object store directly to the GPU
            stream_model=True,
        )
    )
# {{/docs-fragment using-sharded-models}}

# {{docs-fragment complete-example}}
# define the app environment
vllm_app = VLLMAppEnvironment(
    name="qwen-serving-app",
    # this will download the model from HuggingFace into the app container's filesystem
    model_hf_path="Qwen/Qwen3-0.6B",
    model_id="qwen3-0.6b",
    resources=flyte.Resources(
        cpu="4",
        memory="16Gi",
        gpu="L40s:1",
        disk="10Gi",
    ),
    scaling=flyte.app.Scaling(
        replicas=(0, 1),
        scaledown_after=600,
    ),
    requires_auth=False,
)

if __name__ == "__main__":
    # prefetch the model
    print("Prefetching model...")
    run = flyte.prefetch.hf_model(
        repo="Qwen/Qwen3-0.6B",
        artifact_name="qwen-0.6b",
        cpu="4",
        mem="16Gi",
        ephemeral_storage="50Gi",
    )

    # wait for completion
    print("Waiting for prefetch to complete...")
    run.wait()
    print(f"Model prefetched: {run.outputs()[0].path}")

    # deploy the app
    print("Deploying app...")
    flyte.init_from_config()
    app = flyte.serve(
        vllm_app.clone_with(
            name=vllm_app.name,
            model_path=flyte.app.RunOutput(type="directory", run_name=run.name),
            hf_model_path=None,
            stream_model=True,
        )
    )
    print(f"App deployed: {app.url}")
# {{/docs-fragment complete-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/prefetch_examples.py*

The default value for `hf_token_key` is `HF_TOKEN`, where `HF_TOKEN` is the name of the Flyte secret containing your
HuggingFace token. If this secret doesn't exist, you can create a secret using the [flyte create secret CLI](../task-configuration/secrets).

### With resources

By default, the prefetch task uses minimal resources (2 CPUs, 8GB of memory, 50Gi of disk storage), using
filestreaming logic to move the model weights from HuggingFace to your storage backend directly.

In some cases, the HuggingFace model may not support filestreaming, in which case the prefetch task will fallback to
downloading the model weights to the task pod's disk storage first, then uploading them to your storage backend. In this
case, you can specify custom resources for the prefetch task to override the default resources.

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-vllm>=2.0.0b49",
# ]
# ///

"""Prefetch examples for the prefetching-models.md documentation."""

import flyte
from flyte.prefetch import ShardConfig, VLLMShardArgs
from flyteplugins.vllm import VLLMAppEnvironment

# {{docs-fragment basic-prefetch}}
# Prefetch a HuggingFace model
run = flyte.prefetch.hf_model(repo="Qwen/Qwen3-0.6B")

# Wait for prefetch to complete
run.wait()

# Get the model path
model_path = run.outputs()[0].path
print(f"Model prefetched to: {model_path}")
# {{/docs-fragment basic-prefetch}}

# {{docs-fragment using-prefetched-models}}
# Prefetch the model
run = flyte.prefetch.hf_model(repo="Qwen/Qwen3-0.6B")
run.wait()

# Use the prefetched model
vllm_app = VLLMAppEnvironment(
    name="my-llm-app",
    model_path=flyte.app.RunOutput(
        type="directory",
        run_name=run.name,
    ),
    model_id="qwen3-0.6b",
    resources=flyte.Resources(cpu="4", memory="16Gi", gpu="L40s:1"),
    stream_model=True,
)

app = flyte.serve(vllm_app)
# {{/docs-fragment using-prefetched-models}}

# {{docs-fragment custom-artifact-name}}
run = flyte.prefetch.hf_model(
    repo="Qwen/Qwen3-0.6B",
    artifact_name="qwen-0.6b-model",  # Custom name for the stored model
)
# {{/docs-fragment custom-artifact-name}}

# {{docs-fragment hf-token}}
run = flyte.prefetch.hf_model(
    repo="meta-llama/Llama-2-7b-hf",
    hf_token_key="HF_TOKEN",  # Name of Flyte secret containing HF token
)
# {{/docs-fragment hf-token}}

# {{docs-fragment with-resources}}
run = flyte.prefetch.hf_model(
    repo="Qwen/Qwen3-0.6B",
    cpu="4",
    mem="16Gi",
    ephemeral_storage="100Gi",
)
# {{/docs-fragment with-resources}}

# {{docs-fragment vllm-sharding}}
run = flyte.prefetch.hf_model(
    repo="meta-llama/Llama-2-70b-hf",
    resources=flyte.Resources(cpu="8", memory="32Gi", gpu="L40s:4"),
    shard_config=ShardConfig(
        engine="vllm",
        args=VLLMShardArgs(
            tensor_parallel_size=4,
            dtype="auto",
            trust_remote_code=True,
        ),
    ),
    hf_token_key="HF_TOKEN",
)

run.wait()
# {{/docs-fragment vllm-sharding}}

# {{docs-fragment using-sharded-models}}
# Use in vLLM app
vllm_app = VLLMAppEnvironment(
    name="multi-gpu-llm-app",
    # this will download the model from HuggingFace into the app container's filesystem
    model_hf_path="Qwen/Qwen3-0.6B",
    model_id="llama-2-70b",
    resources=flyte.Resources(
        cpu="8",
        memory="32Gi",
        gpu="L40s:4",  # Match the number of GPUs used for sharding
    ),
    extra_args=[
        "--tensor-parallel-size", "4",  # Match sharding config
    ],
)

if __name__ == "__main__":
    # Prefetch with sharding
    run = flyte.prefetch.hf_model(
        repo="meta-llama/Llama-2-70b-hf",
        accelerator="L40s:4",
        shard_config=ShardConfig(
            engine="vllm",
            args=VLLMShardArgs(tensor_parallel_size=4),
        ),
    )
    run.wait()

    flyte.serve(
        vllm_app.clone_with(
            name=vllm_app.name,
            # override the model path to use the prefetched model
            model_path=flyte.app.RunOutput(type="directory", run_name=run.name),
            # set the hf_model_path to None
            hf_model_path=None,
            # stream the model from flyte object store directly to the GPU
            stream_model=True,
        )
    )
# {{/docs-fragment using-sharded-models}}

# {{docs-fragment complete-example}}
# define the app environment
vllm_app = VLLMAppEnvironment(
    name="qwen-serving-app",
    # this will download the model from HuggingFace into the app container's filesystem
    model_hf_path="Qwen/Qwen3-0.6B",
    model_id="qwen3-0.6b",
    resources=flyte.Resources(
        cpu="4",
        memory="16Gi",
        gpu="L40s:1",
        disk="10Gi",
    ),
    scaling=flyte.app.Scaling(
        replicas=(0, 1),
        scaledown_after=600,
    ),
    requires_auth=False,
)

if __name__ == "__main__":
    # prefetch the model
    print("Prefetching model...")
    run = flyte.prefetch.hf_model(
        repo="Qwen/Qwen3-0.6B",
        artifact_name="qwen-0.6b",
        cpu="4",
        mem="16Gi",
        ephemeral_storage="50Gi",
    )

    # wait for completion
    print("Waiting for prefetch to complete...")
    run.wait()
    print(f"Model prefetched: {run.outputs()[0].path}")

    # deploy the app
    print("Deploying app...")
    flyte.init_from_config()
    app = flyte.serve(
        vllm_app.clone_with(
            name=vllm_app.name,
            model_path=flyte.app.RunOutput(type="directory", run_name=run.name),
            hf_model_path=None,
            stream_model=True,
        )
    )
    print(f"App deployed: {app.url}")
# {{/docs-fragment complete-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/prefetch_examples.py*

## Sharding models for multi-GPU

### vLLM sharding

Shard a model for tensor parallelism:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-vllm>=2.0.0b49",
# ]
# ///

"""Prefetch examples for the prefetching-models.md documentation."""

import flyte
from flyte.prefetch import ShardConfig, VLLMShardArgs
from flyteplugins.vllm import VLLMAppEnvironment

# {{docs-fragment basic-prefetch}}
# Prefetch a HuggingFace model
run = flyte.prefetch.hf_model(repo="Qwen/Qwen3-0.6B")

# Wait for prefetch to complete
run.wait()

# Get the model path
model_path = run.outputs()[0].path
print(f"Model prefetched to: {model_path}")
# {{/docs-fragment basic-prefetch}}

# {{docs-fragment using-prefetched-models}}
# Prefetch the model
run = flyte.prefetch.hf_model(repo="Qwen/Qwen3-0.6B")
run.wait()

# Use the prefetched model
vllm_app = VLLMAppEnvironment(
    name="my-llm-app",
    model_path=flyte.app.RunOutput(
        type="directory",
        run_name=run.name,
    ),
    model_id="qwen3-0.6b",
    resources=flyte.Resources(cpu="4", memory="16Gi", gpu="L40s:1"),
    stream_model=True,
)

app = flyte.serve(vllm_app)
# {{/docs-fragment using-prefetched-models}}

# {{docs-fragment custom-artifact-name}}
run = flyte.prefetch.hf_model(
    repo="Qwen/Qwen3-0.6B",
    artifact_name="qwen-0.6b-model",  # Custom name for the stored model
)
# {{/docs-fragment custom-artifact-name}}

# {{docs-fragment hf-token}}
run = flyte.prefetch.hf_model(
    repo="meta-llama/Llama-2-7b-hf",
    hf_token_key="HF_TOKEN",  # Name of Flyte secret containing HF token
)
# {{/docs-fragment hf-token}}

# {{docs-fragment with-resources}}
run = flyte.prefetch.hf_model(
    repo="Qwen/Qwen3-0.6B",
    cpu="4",
    mem="16Gi",
    ephemeral_storage="100Gi",
)
# {{/docs-fragment with-resources}}

# {{docs-fragment vllm-sharding}}
run = flyte.prefetch.hf_model(
    repo="meta-llama/Llama-2-70b-hf",
    resources=flyte.Resources(cpu="8", memory="32Gi", gpu="L40s:4"),
    shard_config=ShardConfig(
        engine="vllm",
        args=VLLMShardArgs(
            tensor_parallel_size=4,
            dtype="auto",
            trust_remote_code=True,
        ),
    ),
    hf_token_key="HF_TOKEN",
)

run.wait()
# {{/docs-fragment vllm-sharding}}

# {{docs-fragment using-sharded-models}}
# Use in vLLM app
vllm_app = VLLMAppEnvironment(
    name="multi-gpu-llm-app",
    # this will download the model from HuggingFace into the app container's filesystem
    model_hf_path="Qwen/Qwen3-0.6B",
    model_id="llama-2-70b",
    resources=flyte.Resources(
        cpu="8",
        memory="32Gi",
        gpu="L40s:4",  # Match the number of GPUs used for sharding
    ),
    extra_args=[
        "--tensor-parallel-size", "4",  # Match sharding config
    ],
)

if __name__ == "__main__":
    # Prefetch with sharding
    run = flyte.prefetch.hf_model(
        repo="meta-llama/Llama-2-70b-hf",
        accelerator="L40s:4",
        shard_config=ShardConfig(
            engine="vllm",
            args=VLLMShardArgs(tensor_parallel_size=4),
        ),
    )
    run.wait()

    flyte.serve(
        vllm_app.clone_with(
            name=vllm_app.name,
            # override the model path to use the prefetched model
            model_path=flyte.app.RunOutput(type="directory", run_name=run.name),
            # set the hf_model_path to None
            hf_model_path=None,
            # stream the model from flyte object store directly to the GPU
            stream_model=True,
        )
    )
# {{/docs-fragment using-sharded-models}}

# {{docs-fragment complete-example}}
# define the app environment
vllm_app = VLLMAppEnvironment(
    name="qwen-serving-app",
    # this will download the model from HuggingFace into the app container's filesystem
    model_hf_path="Qwen/Qwen3-0.6B",
    model_id="qwen3-0.6b",
    resources=flyte.Resources(
        cpu="4",
        memory="16Gi",
        gpu="L40s:1",
        disk="10Gi",
    ),
    scaling=flyte.app.Scaling(
        replicas=(0, 1),
        scaledown_after=600,
    ),
    requires_auth=False,
)

if __name__ == "__main__":
    # prefetch the model
    print("Prefetching model...")
    run = flyte.prefetch.hf_model(
        repo="Qwen/Qwen3-0.6B",
        artifact_name="qwen-0.6b",
        cpu="4",
        mem="16Gi",
        ephemeral_storage="50Gi",
    )

    # wait for completion
    print("Waiting for prefetch to complete...")
    run.wait()
    print(f"Model prefetched: {run.outputs()[0].path}")

    # deploy the app
    print("Deploying app...")
    flyte.init_from_config()
    app = flyte.serve(
        vllm_app.clone_with(
            name=vllm_app.name,
            model_path=flyte.app.RunOutput(type="directory", run_name=run.name),
            hf_model_path=None,
            stream_model=True,
        )
    )
    print(f"App deployed: {app.url}")
# {{/docs-fragment complete-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/prefetch_examples.py*

Currently, the `flyte.prefetch.hf_model` function only supports sharding models
using the `vllm` engine. Once sharded, these models can be loaded with other
frameworks such as `transformers`, `torch`, or `sglang`.

### Using shard config via CLI

You can also use a YAML file for sharding configuration to use with the
`flyte prefetch hf-model` CLI command:

```yaml
# shard_config.yaml
engine: vllm
args:
  tensor_parallel_size: 8
  dtype: auto
  trust_remote_code: true
```

Then run the CLI command:

```bash
flyte prefetch hf-model meta-llama/Llama-2-70b-hf \
    --shard-config shard_config.yaml \
    --accelerator L40s:8 \
    --hf-token-key HF_TOKEN
```

## Using prefetched sharded models

After prefetching and sharding, serve the model in your app:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-vllm>=2.0.0b49",
# ]
# ///

"""Prefetch examples for the prefetching-models.md documentation."""

import flyte
from flyte.prefetch import ShardConfig, VLLMShardArgs
from flyteplugins.vllm import VLLMAppEnvironment

# {{docs-fragment basic-prefetch}}
# Prefetch a HuggingFace model
run = flyte.prefetch.hf_model(repo="Qwen/Qwen3-0.6B")

# Wait for prefetch to complete
run.wait()

# Get the model path
model_path = run.outputs()[0].path
print(f"Model prefetched to: {model_path}")
# {{/docs-fragment basic-prefetch}}

# {{docs-fragment using-prefetched-models}}
# Prefetch the model
run = flyte.prefetch.hf_model(repo="Qwen/Qwen3-0.6B")
run.wait()

# Use the prefetched model
vllm_app = VLLMAppEnvironment(
    name="my-llm-app",
    model_path=flyte.app.RunOutput(
        type="directory",
        run_name=run.name,
    ),
    model_id="qwen3-0.6b",
    resources=flyte.Resources(cpu="4", memory="16Gi", gpu="L40s:1"),
    stream_model=True,
)

app = flyte.serve(vllm_app)
# {{/docs-fragment using-prefetched-models}}

# {{docs-fragment custom-artifact-name}}
run = flyte.prefetch.hf_model(
    repo="Qwen/Qwen3-0.6B",
    artifact_name="qwen-0.6b-model",  # Custom name for the stored model
)
# {{/docs-fragment custom-artifact-name}}

# {{docs-fragment hf-token}}
run = flyte.prefetch.hf_model(
    repo="meta-llama/Llama-2-7b-hf",
    hf_token_key="HF_TOKEN",  # Name of Flyte secret containing HF token
)
# {{/docs-fragment hf-token}}

# {{docs-fragment with-resources}}
run = flyte.prefetch.hf_model(
    repo="Qwen/Qwen3-0.6B",
    cpu="4",
    mem="16Gi",
    ephemeral_storage="100Gi",
)
# {{/docs-fragment with-resources}}

# {{docs-fragment vllm-sharding}}
run = flyte.prefetch.hf_model(
    repo="meta-llama/Llama-2-70b-hf",
    resources=flyte.Resources(cpu="8", memory="32Gi", gpu="L40s:4"),
    shard_config=ShardConfig(
        engine="vllm",
        args=VLLMShardArgs(
            tensor_parallel_size=4,
            dtype="auto",
            trust_remote_code=True,
        ),
    ),
    hf_token_key="HF_TOKEN",
)

run.wait()
# {{/docs-fragment vllm-sharding}}

# {{docs-fragment using-sharded-models}}
# Use in vLLM app
vllm_app = VLLMAppEnvironment(
    name="multi-gpu-llm-app",
    # this will download the model from HuggingFace into the app container's filesystem
    model_hf_path="Qwen/Qwen3-0.6B",
    model_id="llama-2-70b",
    resources=flyte.Resources(
        cpu="8",
        memory="32Gi",
        gpu="L40s:4",  # Match the number of GPUs used for sharding
    ),
    extra_args=[
        "--tensor-parallel-size", "4",  # Match sharding config
    ],
)

if __name__ == "__main__":
    # Prefetch with sharding
    run = flyte.prefetch.hf_model(
        repo="meta-llama/Llama-2-70b-hf",
        accelerator="L40s:4",
        shard_config=ShardConfig(
            engine="vllm",
            args=VLLMShardArgs(tensor_parallel_size=4),
        ),
    )
    run.wait()

    flyte.serve(
        vllm_app.clone_with(
            name=vllm_app.name,
            # override the model path to use the prefetched model
            model_path=flyte.app.RunOutput(type="directory", run_name=run.name),
            # set the hf_model_path to None
            hf_model_path=None,
            # stream the model from flyte object store directly to the GPU
            stream_model=True,
        )
    )
# {{/docs-fragment using-sharded-models}}

# {{docs-fragment complete-example}}
# define the app environment
vllm_app = VLLMAppEnvironment(
    name="qwen-serving-app",
    # this will download the model from HuggingFace into the app container's filesystem
    model_hf_path="Qwen/Qwen3-0.6B",
    model_id="qwen3-0.6b",
    resources=flyte.Resources(
        cpu="4",
        memory="16Gi",
        gpu="L40s:1",
        disk="10Gi",
    ),
    scaling=flyte.app.Scaling(
        replicas=(0, 1),
        scaledown_after=600,
    ),
    requires_auth=False,
)

if __name__ == "__main__":
    # prefetch the model
    print("Prefetching model...")
    run = flyte.prefetch.hf_model(
        repo="Qwen/Qwen3-0.6B",
        artifact_name="qwen-0.6b",
        cpu="4",
        mem="16Gi",
        ephemeral_storage="50Gi",
    )

    # wait for completion
    print("Waiting for prefetch to complete...")
    run.wait()
    print(f"Model prefetched: {run.outputs()[0].path}")

    # deploy the app
    print("Deploying app...")
    flyte.init_from_config()
    app = flyte.serve(
        vllm_app.clone_with(
            name=vllm_app.name,
            model_path=flyte.app.RunOutput(type="directory", run_name=run.name),
            hf_model_path=None,
            stream_model=True,
        )
    )
    print(f"App deployed: {app.url}")
# {{/docs-fragment complete-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/prefetch_examples.py*

## CLI options

Complete CLI usage:

```bash
flyte prefetch hf-model <repo> \
    --artifact-name <name> \
    --architecture <arch> \
    --task <task> \
    --modality text \
    --format safetensors \
    --model-type transformer \
    --short-description "Description" \
    --force 0 \
    --wait \
    --hf-token-key HF_TOKEN \
    --cpu 4 \
    --mem 16Gi \
    --ephemeral-storage 100Gi \
    --accelerator L40s:4 \
    --shard-config shard_config.yaml
```

## Complete example

Here's a complete example of prefetching and using a model:

```
# /// script
# requires-python = ">=3.12"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-vllm>=2.0.0b49",
# ]
# ///

"""Prefetch examples for the prefetching-models.md documentation."""

import flyte
from flyte.prefetch import ShardConfig, VLLMShardArgs
from flyteplugins.vllm import VLLMAppEnvironment

# {{docs-fragment basic-prefetch}}
# Prefetch a HuggingFace model
run = flyte.prefetch.hf_model(repo="Qwen/Qwen3-0.6B")

# Wait for prefetch to complete
run.wait()

# Get the model path
model_path = run.outputs()[0].path
print(f"Model prefetched to: {model_path}")
# {{/docs-fragment basic-prefetch}}

# {{docs-fragment using-prefetched-models}}
# Prefetch the model
run = flyte.prefetch.hf_model(repo="Qwen/Qwen3-0.6B")
run.wait()

# Use the prefetched model
vllm_app = VLLMAppEnvironment(
    name="my-llm-app",
    model_path=flyte.app.RunOutput(
        type="directory",
        run_name=run.name,
    ),
    model_id="qwen3-0.6b",
    resources=flyte.Resources(cpu="4", memory="16Gi", gpu="L40s:1"),
    stream_model=True,
)

app = flyte.serve(vllm_app)
# {{/docs-fragment using-prefetched-models}}

# {{docs-fragment custom-artifact-name}}
run = flyte.prefetch.hf_model(
    repo="Qwen/Qwen3-0.6B",
    artifact_name="qwen-0.6b-model",  # Custom name for the stored model
)
# {{/docs-fragment custom-artifact-name}}

# {{docs-fragment hf-token}}
run = flyte.prefetch.hf_model(
    repo="meta-llama/Llama-2-7b-hf",
    hf_token_key="HF_TOKEN",  # Name of Flyte secret containing HF token
)
# {{/docs-fragment hf-token}}

# {{docs-fragment with-resources}}
run = flyte.prefetch.hf_model(
    repo="Qwen/Qwen3-0.6B",
    cpu="4",
    mem="16Gi",
    ephemeral_storage="100Gi",
)
# {{/docs-fragment with-resources}}

# {{docs-fragment vllm-sharding}}
run = flyte.prefetch.hf_model(
    repo="meta-llama/Llama-2-70b-hf",
    resources=flyte.Resources(cpu="8", memory="32Gi", gpu="L40s:4"),
    shard_config=ShardConfig(
        engine="vllm",
        args=VLLMShardArgs(
            tensor_parallel_size=4,
            dtype="auto",
            trust_remote_code=True,
        ),
    ),
    hf_token_key="HF_TOKEN",
)

run.wait()
# {{/docs-fragment vllm-sharding}}

# {{docs-fragment using-sharded-models}}
# Use in vLLM app
vllm_app = VLLMAppEnvironment(
    name="multi-gpu-llm-app",
    # this will download the model from HuggingFace into the app container's filesystem
    model_hf_path="Qwen/Qwen3-0.6B",
    model_id="llama-2-70b",
    resources=flyte.Resources(
        cpu="8",
        memory="32Gi",
        gpu="L40s:4",  # Match the number of GPUs used for sharding
    ),
    extra_args=[
        "--tensor-parallel-size", "4",  # Match sharding config
    ],
)

if __name__ == "__main__":
    # Prefetch with sharding
    run = flyte.prefetch.hf_model(
        repo="meta-llama/Llama-2-70b-hf",
        accelerator="L40s:4",
        shard_config=ShardConfig(
            engine="vllm",
            args=VLLMShardArgs(tensor_parallel_size=4),
        ),
    )
    run.wait()

    flyte.serve(
        vllm_app.clone_with(
            name=vllm_app.name,
            # override the model path to use the prefetched model
            model_path=flyte.app.RunOutput(type="directory", run_name=run.name),
            # set the hf_model_path to None
            hf_model_path=None,
            # stream the model from flyte object store directly to the GPU
            stream_model=True,
        )
    )
# {{/docs-fragment using-sharded-models}}

# {{docs-fragment complete-example}}
# define the app environment
vllm_app = VLLMAppEnvironment(
    name="qwen-serving-app",
    # this will download the model from HuggingFace into the app container's filesystem
    model_hf_path="Qwen/Qwen3-0.6B",
    model_id="qwen3-0.6b",
    resources=flyte.Resources(
        cpu="4",
        memory="16Gi",
        gpu="L40s:1",
        disk="10Gi",
    ),
    scaling=flyte.app.Scaling(
        replicas=(0, 1),
        scaledown_after=600,
    ),
    requires_auth=False,
)

if __name__ == "__main__":
    # prefetch the model
    print("Prefetching model...")
    run = flyte.prefetch.hf_model(
        repo="Qwen/Qwen3-0.6B",
        artifact_name="qwen-0.6b",
        cpu="4",
        mem="16Gi",
        ephemeral_storage="50Gi",
    )

    # wait for completion
    print("Waiting for prefetch to complete...")
    run.wait()
    print(f"Model prefetched: {run.outputs()[0].path}")

    # deploy the app
    print("Deploying app...")
    flyte.init_from_config()
    app = flyte.serve(
        vllm_app.clone_with(
            name=vllm_app.name,
            model_path=flyte.app.RunOutput(type="directory", run_name=run.name),
            hf_model_path=None,
            stream_model=True,
        )
    )
    print(f"App deployed: {app.url}")
# {{/docs-fragment complete-example}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/serve-and-deploy-apps/prefetch_examples.py*

## Best practices

1. **Prefetch before deployment**: Prefetch models before deploying apps for faster startup
2. **Version models**: Use meaningful artifact names to easily identify the model in object store paths
3. **Shard appropriately**: Shard models for the GPU configuration you'll use for inference
4. **Cache prefetched models**: Once prefetched, models are cached in your storage backend for faster serving

## Troubleshooting

**Prefetch fails:**
- Check HuggingFace token (if required)
- Verify model repo exists and is accessible
- Check resource availability
- Review prefetch task logs

**Sharding fails:**
- Ensure accelerator matches shard config
- Check GPU memory is sufficient
- Verify `tensor_parallel_size` matches GPU count
- Review prefetch task logs for sharding-related errors

**Model not found in app:**
- Verify RunOutput references correct run name
- Check that prefetch completed successfully
- Ensure model_path is set correctly
- Review app startup logs


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/build-agent ===

# Build an agent

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

This section covers how to build, deploy, and run agentic AI applications on Union.ai. You'll learn how to implement common agent patterns like ReAct and Plan-and-Execute and deploy agents as hosted services.

## Quickstart

Here's how Union.ai maps to the agentic world:

- **`TaskEnvironment`**: The sandboxed execution environment for your agent steps. It configures the container image, hardware resources (CPU, GPU), and secrets (API keys). Think of it as defining "where this code runs."
- **`@env.task`**: Turns any Python function into a remotely-executed step. Each task runs in its own container with the resources you specified. This is the equivalent of a node in LangGraph or n8n.
- **Tasks calling tasks**: A task can `await` other tasks, and each called task gets its own container automatically. No separate workflow decorator needed. The calling task IS your workflow, this is how you build multi-step agentic pipelines.
- **`@flyte.trace`**: Marks helper functions inside a task for fine-grained observability and caching. Each traced call appears as a span in the Union.ai dashboard, with its inputs and outputs captured and checkpointed. Use this on your LLM calls, tool executions, and routing decisions to get full visibility into every turn of the agent loop.

> [!TIP]
> See the **Quickstart** for a hands-on walkthrough.

## Next steps

- **Build an agent > Deploy an agent as a service**: Host a FastAPI app, webhook pattern, model serving
- **Build an agent > Building agentic workflows on Union.ai**: ReAct pattern, Plan-and-Execute with fan-out, LangGraph integration, and more patterns

## Subpages
- **Build an agent > Building agentic workflows on Union.ai**
- **Build an agent > Deploy an agent as a service**


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/build-agent/building-agents ===

# Building agentic workflows on Union.ai

Union.ai is framework-agnostic: use any Python LLM library (OpenAI SDK, Anthropic SDK, LangChain, LiteLLM, etc.) inside your tasks. The platform provides the production infrastructure layer: sandboxed execution, parallel fan-out, durable checkpointing, and observability for every step of the agent loop.

Two decorators are all you need:

| Decorator | What it does | Think of it as... |
|-----------|-------------|-------------------|
| **`@env.task`** | Runs a function in its own container on Union.ai with dedicated resources, dependencies, and secrets | A sandboxed agent step with its own execution environment |
| **`@flyte.trace`** | Marks a helper function for observability, where each call appears as a span in the Union.ai dashboard with captured I/O | An observability hook on your LLM calls, tool executions, and routing decisions |

## ReAct pattern: Reason, Act, Observe (no framework needed)

The [ReAct pattern](https://arxiv.org/abs/2210.03629) is the most common agent architecture: the LLM reasons about what to do, calls a tool, observes the result, and repeats until done. This example is implemented directly with flyte:

```
Thought → Action → Observation → repeat until done
```

```python
# agent.py
import json
from pydantic import BaseModel

import flyte
from openai import AsyncOpenAI

env = flyte.TaskEnvironment(
    name="agent_env",
    image=flyte.Image.from_debian_base(python_version=(3, 13)).with_pip_packages("openai"),
    resources=flyte.Resources(cpu=2, memory="2Gi"),
    secrets=[flyte.Secret(key="OPENAI_API_KEY")],
)

TOOLS = {"add": lambda a, b: a + b, "multiply": lambda a, b: a * b}

@flyte.trace                                       # each call = a span in Union.ai dashboard
async def reason(goal: str, history: str) -> dict:
    """LLM picks a tool or returns a final answer."""
    r = await AsyncOpenAI().chat.completions.create(
        model="gpt-4.1-nano",
        response_format={"type": "json_object"},
        messages=[
            {"role": "system", "content":
                f"Tools: {list(TOOLS)}. Respond JSON: "
                '{"thought":..,"tool":..,"args":{}} or {"thought":..,"done":true,"answer":..}'},
            {"role": "user", "content": f"Goal: {goal}\n\n{history}\nWhat next?"},
        ],
    )
    return json.loads(r.choices[0].message.content)

@flyte.trace
async def act(tool: str, args: dict) -> str:
    """Execute the chosen tool."""
    return str(TOOLS[tool](**args))

class AgentResult(BaseModel):
    answer: str
    steps: int

@env.task                                          # runs in its own sandboxed container
async def react_agent(goal: str, max_steps: int = 10) -> AgentResult:
    history = ""
    for step in range(1, max_steps + 1):           # the agent loop
        decision = await reason(goal, history)      # Thought
        if decision.get("done"):
            return AgentResult(answer=str(decision["answer"]), steps=step)
        result = await act(decision["tool"], decision["args"])  # Action
        history += f"Step {step}: {decision['thought']} -> {decision['tool']}({decision['args']}) = {result}\n"  # Observation
    return AgentResult(answer="Max steps reached", steps=max_steps)
```

```bash
flyte run agent.py react_agent --goal "What is (12 + 8) * 3?"
# => AgentResult(answer='60', steps=3)
```

**What's happening under the hood:**
- `react_agent` runs in a sandboxed container with only `openai` installed and 2 CPU / 2GB RAM
- Each `reason()` and `act()` call is traced, so you see every LLM call, every tool invocation, and every intermediate result in the Union.ai dashboard
- The agent's inputs and final output are durably persisted, letting you inspect any past run end-to-end
- Swap in your own tools (web search, database queries, API calls) by adding to the `TOOLS` dict

> [!TIP]
> See the [Agentic Refinement docs](../advanced-project/agentic-refinement), [Traces docs](../task-programming/traces), and [more patterns (planner, debate, etc.)](https://github.com/unionai/workshops/tree/main/tutorials/multi-agent-workflows).

## Plan-and-Execute with parallel fan-out (LangGraph on Union.ai)

The [Plan-and-Execute pattern](https://blog.langchain.com/plan-and-execute-agents/) splits a complex query into sub-tasks, fans them out in parallel, then synthesizes the results. This example runs a LangGraph research agent with web search tool calling, and Union.ai handles the parallelization, giving each sub-task its own container.

Here's `graph.py`, a LangGraph agent with tool calling (search the web, then summarize):

```python
import flyte
from langchain_openai import ChatOpenAIe
from langchain_core.messages import SystemMessage
from langgraph.graph import StateGraph, MessagesState
from langgraph.prebuilt import ToolNode
from langchain_community.tools.tavily_search import TavilySearchResults

def build_research_graph(openai_key: str, tavily_key: str):
    tools = [TavilySearchResults(max_results=2, tavily_api_key=tavily_key)]
    llm = ChatOpenAI(model="gpt-4.1-nano", api_key=openai_key).bind_tools(tools)

    @flyte.trace
    async def agent(state: MessagesState):
        msgs = [SystemMessage(content="Research the topic. Use search, then summarize.")] + state["messages"]
        return {"messages": [await llm.ainvoke(msgs)]}

    @flyte.trace
    async def route(state: MessagesState):
        last = state["messages"][-1]
        return "tools" if getattr(last, "tool_calls", None) else "__end__"

    g = StateGraph(MessagesState)
    g.add_node("agent", agent)
    g.add_node("tools", ToolNode(tools))
    g.set_entry_point("agent")
    g.add_conditional_edges("agent", route, {"tools": "tools", "__end__": "__end__"})
    g.add_edge("tools", "agent")
    return g.compile()
```

And `workflow.py`, which plans topics, fans out research in parallel, and synthesizes:

```python
import os, json, asyncio, flyte
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
from graph import build_research_graph

env = flyte.TaskEnvironment(
    name="research_env",
    image=flyte.Image.from_debian_base(python_version=(3, 13))
        .with_pip_packages("openai", "langchain-openai", "langchain-community", "langgraph", "tavily-python"),
    resources=flyte.Resources(cpu=2, memory="2Gi"),
    secrets=[flyte.Secret(key="OPENAI_API_KEY"), flyte.Secret(key="TAVILY_API_KEY")],
)

@env.task
async def plan(query: str, n: int = 3) -> list[str]:
    """Split query into sub-topics."""
    r = await ChatOpenAI(model="gpt-4.1-nano", api_key=os.environ["OPENAI_API_KEY"]).ainvoke(
        f"Break into exactly {n} sub-topics. Return ONLY a JSON array of strings, e.g. [\"topic1\", \"topic2\"]. No objects.\n\n{query}")
    topics = json.loads(r.content)[:n]
    return [t if isinstance(t, str) else str(t.get("sub_topic", t)) for t in topics]

@env.task
async def research(topic: str) -> str:
    """Run LangGraph agent on one topic (each call = separate container)."""
    graph = build_research_graph(os.environ["OPENAI_API_KEY"], os.environ["TAVILY_API_KEY"])
    result = await graph.ainvoke({"messages": [HumanMessage(content=f"Research: {topic}")]})
    return json.dumps({"topic": topic, "report": result["messages"][-1].content})

@env.task
async def synthesize(query: str, reports: list[str]) -> str:
    """Combine sub-reports into a final summary."""
    parsed = [json.loads(r) for r in reports]
    sections = "\n\n".join(f"## {r['topic']}\n{r['report']}" for r in parsed)
    r = await ChatOpenAI(model="gpt-4.1-nano", api_key=os.environ["OPENAI_API_KEY"]).ainvoke(
        f"Synthesize reports on: {query}\n\n{sections}\n\nKey takeaways:")
    return r.content

@env.task
async def research_workflow(query: str, num_topics: int = 3) -> str:
    topics = await plan(query, num_topics)
    reports = list(await asyncio.gather(*[research(t) for t in topics]))  # parallel fan-out
    return await synthesize(query, reports)
```

```bash
flyte run workflow.py research_workflow --query "Impact of storms on travel insurance payouts"
```

**What's happening under the hood:**

```
research_workflow (orchestrator)
  ├── plan          → LLM breaks query into N sub-topics          [container 1]
  ├── research(t1)  → LangGraph agent loop with web search tools  [container 2]  ┐
  ├── research(t2)  → LangGraph agent loop with web search tools  [container 3]  ├ parallel
  ├── research(t3)  → LangGraph agent loop with web search tools  [container 4]  ┘
  └── synthesize    → LLM combines reports into final answer      [container 5]
```

- **Fan-out:** `asyncio.gather()` launches all research tasks in parallel, each in its own sandboxed container
- **Tool calling inside each research task:** The LangGraph agent calls Tavily web search, observes results, reasons about them, and loops until it has enough information (the inner agentic loop)
- **Observability:** `@flyte.trace` on the LangGraph nodes means every LLM call, every tool call, and every routing decision is visible as a span in the Union.ai dashboard
- **Durable checkpointing:** Each task's output is persisted. If `synthesize` fails, re-running skips the completed `plan` and `research` steps (with caching enabled)

## More agentic patterns

Union.ai is framework-agnostic, so these patterns work with any LLM library. Each maps to well-known agent architectures:

| Pattern | What it does | When to use it | Link |
|---------|-------------|----------------|------|
| **ReAct** | Reason → Act → Observe loop with tool calling | Single-agent tasks with tools (API calls, search, code execution) | [multi-agent-workflows/react](https://github.com/unionai/workshops/tree/main/tutorials/multi-agent-workflows) |
| **Plan-and-Execute** | LLM creates a plan, independent steps fan out in parallel, results are synthesized | Complex queries that decompose into parallel sub-tasks | [multi-agent-workflows/planner](https://github.com/unionai/workshops/tree/main/tutorials/multi-agent-workflows) |
| **Evaluator-Optimizer (Reflection)** | Generate → Critique → Refine loop until quality threshold met | Content generation, code generation, any task with clear quality criteria | [Agentic Refinement docs](../advanced-project/agentic-refinement) |
| **Orchestrator-Workers (Manager)** | Supervisor agent delegates to specialist worker agents, reviews quality, requests revisions | Multi-agent systems where sub-tasks require different expertise | [multi-agent-workflows/manager](https://github.com/unionai/workshops/tree/main/tutorials/multi-agent-workflows) |
| **Debate** | Multiple agents solve independently, then debate to consensus | High-stakes decisions where diverse reasoning improves accuracy | [multi-agent-workflows/debate](https://github.com/unionai/workshops/tree/main/tutorials/multi-agent-workflows) |
| **Sequential (Prompt Chaining)** | Static pipeline of LLM calls, no dynamic routing | Predictable multi-step transformations (extract → validate → format) | [multi-agent-workflows/sequential](https://github.com/unionai/workshops/tree/main/tutorials/multi-agent-workflows) |

## How Union.ai's primitives map to the agent stack

If you're coming from LangGraph, CrewAI, OpenAI Agents SDK, or similar frameworks, here's how the concepts you already know translate:

**Your agent loop** is a Python `for`/`while` loop inside an `@env.task`. Each iteration calls `@flyte.trace`-decorated functions for reasoning and tool execution. Union.ai doesn't impose a loop structure; you write it in plain Python, which means any pattern (ReAct, reflection, plan-and-execute) works naturally.

**Tool calling** is just calling Python functions. Define your tools as regular functions, decorate them with `@flyte.trace` for observability, and call them from within the agent loop. Use any tool-calling mechanism your LLM SDK provides (OpenAI function calling, Anthropic tool use, LangChain `bind_tools()`). MCP servers can be accessed from within tasks using the MCP Python SDK.

**Parallel fan-out** (LangGraph's `Send()`, n8n's Split in Batches) is `asyncio.gather()`. Each awaited task gets its own container, giving you true parallelism on separate hardware, not just concurrent coroutines.

**State and checkpointing** (LangGraph's Checkpointers, Threads) is automatic. Every task's inputs and outputs are durably persisted. `@flyte.trace` adds sub-step checkpoints within a task. Re-running with caching enabled skips completed steps, Union.ai's equivalent of replaying from a checkpoint.

**Routing and conditional logic** (LangGraph's `add_conditional_edges`, n8n's If/Switch nodes) is Python `if/else`. No special API needed.

**Environment isolation** (different dependencies per step) is `TaskEnvironment`. Your LLM step can use `langchain==0.3`; your data step can use `pandas` + GPU. Each gets its own container image.

**Guardrails and validation** are Python code between steps: `if/else` checks, Pydantic validation, structured output parsing, or libraries like NeMo Guardrails. Raise an exception to fail a step and trigger retries.

**Observability:** The Union.ai dashboard shows the full execution tree with per-step inputs, outputs, logs, resource usage, and timing. `@flyte.trace` adds spans within a task for fine-grained visibility into individual LLM calls and tool invocations. For LLM-specific metrics (token usage, cost per call), integrate with Langfuse or LangSmith from within your tasks.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/build-agent/deploy-agent-as-service ===

# Deploy an agent as a service

Union.ai makes it straightforward to deploy internal apps (chatbots, dashboards, API endpoints) behind a URL, with no separate infrastructure. This is how you turn an agent into a hosted service that your team (or other agents) can call.

## Chat agent with Gradio

This example takes the ReAct agent from [Building agentic workflows](./building-agents) and wraps it in a Gradio chat interface, deployed as a Union.ai app. Users interact in the browser, and each reasoning step streams back in real time.

```python
# app.py
import json

import gradio as gr

import flyte
from flyte.app import AppEnvironment
from openai import AsyncOpenAI

# --- ReAct agent (same pattern as the ReAct agent in Building agentic workflows on Union.ai) ---

TOOLS = {"add": lambda a, b: a + b, "multiply": lambda a, b: a * b}

async def reason(goal: str, history: str) -> dict:
    """LLM picks a tool or returns a final answer."""
    r = await AsyncOpenAI().chat.completions.create(
        model="gpt-4.1-nano",
        response_format={"type": "json_object"},
        messages=[
            {"role": "system", "content":
                f"Tools: {list(TOOLS)}. Respond JSON: "
                '{"thought":..,"tool":..,"args":{}} or '
                '{"thought":..,"done":true,"answer":..}'},
            {"role": "user", "content": f"Goal: {goal}\n\n{history}\nWhat next?"},
        ],
    )
    return json.loads(r.choices[0].message.content)

async def act(tool: str, args: dict) -> str:
    """Execute the chosen tool."""
    return str(TOOLS[tool](**args))

async def react_agent(message: str, history: list):
    """ReAct loop that streams intermediate steps, then the final answer."""
    output, trace = "", ""
    for step in range(1, 11):
        decision = await reason(message, trace)
        if decision.get("done"):
            yield output + f"\n\n**Answer:** {decision['answer']}"
            return
        result = await act(decision["tool"], decision["args"])
        trace += (
            f"Step {step}: {decision['thought']} "
            f"-> {decision['tool']}({decision['args']}) = {result}\n"
        )
        output += (
            f"**Step {step}:** {decision['thought']}\n"
            f"`{decision['tool']}({decision['args']})` -> `{result}`\n\n"
        )
        yield output
    yield output + "\n\nMax steps reached."

# --- Deploy as a Union.ai app ---

serving_env = AppEnvironment(
    name="react-agent-chat",
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
        "gradio", "openai",
    ),
    secrets=[flyte.Secret(key="OPENAI_API_KEY")],
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
    port=7860,
)

@serving_env.server
def server():
    gr.ChatInterface(
        react_agent,
        title="ReAct Agent",
        examples=["What is (12 + 8) * 3?", "Add 99 and 1, then multiply by 5"],
    ).launch(server_name="0.0.0.0", server_port=7860)

if __name__ == "__main__":
    flyte.init_from_config()
    flyte.serve(serving_env)
CODE0bash
# Local development
python app.py

# Deploy to Union.ai
flyte deploy app.py serving_env
```

Union.ai assigns a URL, handles TLS, and auto-scales the app.

**What's happening under the hood:**

- `AppEnvironment` defines the container image, secrets, resources, and port for the app
- `@serving_env.server` marks the function that Union.ai calls on remote deployment
- `gr.ChatInterface` with an async generator gives streaming output: users see each reasoning step appear as the agent works
- `requires_auth=False` makes the app publicly accessible; set to `True` to require Union.ai authentication

## Other deployment patterns

**FastAPI endpoint:** For API-first agents, use `FastAPIAppEnvironment` to expose your agent behind a REST endpoint that other services or agents can call programmatically.

**Webhook-triggered workflows:** [Deploy a FastAPI app](../build-apps/fastapi-app) that receives webhooks and calls `flyte.run()` on a [remote task](../task-programming/remote-tasks) to kick off longer agentic workflows as background tasks.

**Model serving:** [Serve open-weight LLMs](../build-apps/vllm-app) on GPUs behind an OpenAI-compatible API with `VLLMAppEnvironment` or `SGLangAppEnvironment`.

> [!TIP]
> See [Build Apps](../build-apps/_index), [App usage patterns](../build-apps/app-usage-patterns), and [Configure Apps](../configure-apps/_index) for more details.
> For a hands-on example with a research agent Gradio UI, see [workshops/starter-examples/flyte-local-dev](https://github.com/unionai/workshops/tree/main/tutorials/starter-examples/flyte-local-dev).


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/sandboxing ===

# Sandboxing

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

A **sandbox** is an isolated, secure environment where code can run without affecting the host system.
Sandboxes restrict what the executing code can do — limiting filesystem access, blocking network calls, and preventing arbitrary system operations — so that even malicious or buggy code cannot cause harm.

The exact restrictions depend on the sandboxing approach: some sandboxes eliminate dangerous operations entirely, while others provide full capabilities within an isolated, disposable container.

## Why sandboxing matters for AI

LLM-generated code is inherently untrusted.
The model may produce code that is correct and useful, but it can also produce code that is dangerous — and it does so without intent or awareness.

| Risk | Example |
|------|---------|
| Data destruction | `DELETE FROM orders WHERE 1=1` — wipes an entire table |
| Credential exfiltration | Reads environment variables and sends API keys to an external endpoint |
| Infinite loops | `while True: pass` — consumes CPU indefinitely |
| Resource abuse | Spawns thousands of threads or allocates unbounded memory |
| Filesystem damage | `rm -rf /` or overwrites critical configuration files |
| Network abuse | Makes unauthorized API calls, sends spam, or joins a botnet |

Running LLM-generated code without a sandbox means trusting the model to never make these mistakes.
Sandboxing eliminates this trust requirement by making dangerous operations structurally impossible.

## Types of sandboxes

There are three broad approaches to sandboxing LLM-generated code, each with different tradeoffs:

| Type | How it works | Tradeoffs | Examples |
|------|-------------|-----------|----------|
| **One-shot execution** | Code runs to completion in a disposable container, then the container is discarded. Stdout, stderr, and outputs are captured. | Simple, no state reuse. Good for single-turn tasks. | Container tasks, serverless functions |
| **Interactive sessions** | A persistent VM or container where you send commands incrementally and observe results between steps. Sessions last for the lifetime of the VM. | Flexible and multi-turn, but heavier to provision and manage. | E2B, Daytona, fly.io |
| **Programmatic tool calling** | The LLM generates orchestration code that calls a predefined set of tools. The orchestration code runs in a sandbox while the tools run in full containers. | Durable, observable, and secure. Tools are known ahead of time. | Flyte workflow sandboxing |

## What Flyte offers

Flyte provides two complementary sandboxing approaches:

### Workflow sandbox (Monty)

A **sandboxed orchestrator** built on [Monty](https://github.com/pydantic/pydantic-monty), a Rust-based sandboxed Python interpreter.
The sandbox starts in microseconds, runs pure Python control flow, and dispatches heavy work to full container tasks through the Flyte controller.

This enables the **programmatic tool calling** pattern (also known as code mode): LLMs generate Python orchestration code that invokes registered tools, and Flyte executes it safely with full durability, observability, and type checking.

### Code sandbox (container)

A **stateless code sandbox** that runs arbitrary Python scripts or shell commands inside an ephemeral Docker container.
The container is built on demand from declared dependencies, executed once, and discarded.

This is the right choice when you need full Python capabilities — third-party packages, file I/O, shell commands, or any computation that goes beyond pure control flow.

### When to use which

| | Workflow sandbox | Code sandbox |
|---|---|---|
| **Runtime** | Monty (Rust-based Python interpreter) | Ephemeral Docker container |
| **Startup** | Microseconds | Seconds (image build + container spin-up) |
| **Capabilities** | Pure Python control flow only — no imports, no I/O, no network | Full Python environment — any package, any library, full I/O |
| **Use case** | LLM-generated orchestration logic that calls registered tools | Arbitrary computation — data processing, test execution, ETL, shell pipelines |
| **State** | Runs within a worker container process | Stateless — fresh container per invocation |
| **Security model** | Dangerous operations are structurally impossible | Isolated container |

- Use the **workflow sandbox** when you need to run untrusted control flow (loops, conditionals, routing) that dispatches work to known tasks. It starts in microseconds and provides the strongest isolation guarantees.
- Use the **code sandbox** when you need full Python capabilities — third-party packages, file I/O, shell commands, or any computation that goes beyond pure control flow.

### Learn more

- **Sandboxing > Workflow sandboxing in Flyte** — How the Monty-based sandboxed orchestrator works, with examples
- **Sandboxing > Programmatic tool calling for agents** — The concept behind programmatic tool calling and how to build agents that use it
- **Sandboxing > Code sandboxing** — Running arbitrary code and commands in ephemeral containers with `flyte.sandbox.create()`

## Subpages
- **Sandboxing > Workflow sandboxing in Flyte**
- **Sandboxing > Programmatic tool calling for agents**
- **Sandboxing > Code sandboxing**


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/sandboxing/workflow-sandboxing-flyte ===

# Workflow sandboxing in Flyte

Flyte provides a sandboxed orchestrator that lets you run pure Python control flow in a secure sandbox while dispatching heavy work to full container tasks.
This enables patterns where LLMs generate orchestration code dynamically, and Flyte executes it safely with full durability and observability.

## Why workflow sandboxing?

Three properties of Flyte make it a natural fit for sandboxed code execution:

1. **Infrastructure on demand**: Flyte spins up containers with specific permissions, secrets, and resources for each task.
2. **LLMs are great at Python**: Models trained on billions of lines of code can reliably generate Python orchestration logic.
3. **Microsecond startup**: The sandbox is powered by [Monty](https://github.com/pydantic/pydantic-monty) (Pydantic's Rust-based Python interpreter), which starts in microseconds without the overhead of VMs or containers.

The result: LLMs generate the orchestration code (control flow, conditionals, loops), and Flyte tasks handle the heavy lifting (data access, computation, external APIs) in full containers.

## How it works

Your generated code runs inside one or more **Monty sandboxes** — lightweight Python interpreters embedded within a **worker container**. Each sandbox can execute pure Python (variables, loops, conditionals, function calls) but has no access to the filesystem, network, imports, or OS. A **bridge layer** acts as a hypervisor between the worker container and the sandboxes, handling opaque IO and routing callable tasks. When your code calls an external task, the bridge dispatches it — either as a method in the outer Python process or as a durable remote call through the Flyte controller (via the Queue Service):

```mermaid
flowchart TB
    subgraph worker["Worker Container"]
        subgraph bridge["Bridge / Hypervisor"]
            IO["Opaque IO: File, Dir, DataFrame"]
            subgraph sandbox1["Monty Sandbox 1"]
                A1["Your code: loops, variables, conditionals"]
                B1["result = add(x, y)"]
            end
            subgraph sandbox2["Monty Sandbox 2"]
                A2["More sandboxed code"]
            end
        end
    end

    A1 --> B1
    B1 -- "callable task" --> bridge
    bridge -- "result" --> B1
    IO -. "routed to tasks" .-> bridge
    bridge -- "external call" --> QS["Queue Service"]
    QS -- "completion" --> bridge
```

Each sandbox sees external tasks as opaque function calls. When your code hits one, Monty **pauses**, and the bridge layer dispatches the task — either directly in the outer Python process or as a remote durable call through the Flyte controller system (Queue Service). Once the call completes, Monty **resumes** with the result. Your code never knows the difference — it just looks like a regular function call that returns a value. Multiple Monty sandboxes can run within the same worker container, each isolated like a lightweight VM.

**Opaque IO types** like `File`, `Dir`, and `DataFrame` are managed by the bridge layer and pass through the sandbox without inspection. Your code can route them between tasks but cannot read or modify their contents.

## Example: sandboxed orchestrator

Use `@env.sandbox.orchestrator` to define a sandboxed task that calls regular worker tasks.
The orchestrator contains only pure Python control flow — all heavy computation runs in worker containers.

```python
import flyte

env = flyte.TaskEnvironment(name="sandboxed-demo")

# Worker tasks — run in their own containers
@env.task
def add(x: int, y: int) -> int:
    return x + y

@env.task
def multiply(x: int, y: int) -> int:
    return x * y

@env.task
def fib(n: int) -> int:
    """Compute the nth Fibonacci number iteratively."""
    a, b = 0, 1
    for _ in range(n):
        a, b = b, a + b
    return a

# Sandboxed orchestrator — pure Python control flow
@env.sandbox.orchestrator
def pipeline(n: int) -> dict[str, int]:
    fib_result = fib(n)
    linear_result = add(multiply(n, 2), 5)
    total = add(fib_result, linear_result)

    return {
        "fib": fib_result,
        "linear": linear_result,
        "total": total,
    }
```

When `pipeline` runs, Monty executes the control flow in the sandbox. Each call to `fib`, `multiply`, and `add` pauses the sandbox, runs the worker task in a container, and resumes with the result.

Both `def` and `async def` orchestrators are supported — Monty natively handles `await` expressions.

## Example: dynamic code execution

For cases where the code itself is generated at runtime — from templates, user input, or LLM output — use `orchestrator_from_str()` and `orchestrate_local()`.

### Reusable task from a code string

`orchestrator_from_str()` creates a reusable task template from a Python code string.
The value of the **last expression** becomes the return value.

```python
import flyte
import flyte.sandbox

env = flyte.TaskEnvironment(name="code-string-demo")

@env.task
def add(x: int, y: int) -> int:
    return x + y

@env.task
def multiply(x: int, y: int) -> int:
    return x * y

# Create a reusable task from a code string
compute_pipeline = flyte.sandbox.orchestrator_from_str(
    """
    partial = add(x, y)
    multiply(partial, scale)
    """,
    inputs={"x": int, "y": int, "scale": int},
    output=int,
    tasks=[add, multiply],
    name="compute-pipeline",
)
# flyte.run(compute_pipeline, x=2, y=3, scale=4)  → 20
```

### One-shot local execution

`orchestrate_local()` executes a code string and returns the result directly — no task template, no controller.
Use it for quick one-off computations.

```python
result = await flyte.sandbox.orchestrate_local(
    "add(x, y) * 2",
    inputs={"x": 1, "y": 2},
    tasks=[add],
)
# result → 6
```

### Parameterized code generation

Because the code is a string, you can generate it programmatically:

```python
def make_reducer(operation: str) -> flyte.sandbox.CodeTaskTemplate:
    """Create a sandboxed task that reduces a list using the given operation."""
    if operation == "sum":
        body = """
            acc = 0
            for v in values:
                acc = acc + v
            acc
        """
    elif operation == "product":
        body = """
            acc = 1
            for v in values:
                acc = acc * v
            acc
        """
    else:
        raise ValueError(f"Unknown operation: {operation}")

    return flyte.sandbox.orchestrator_from_str(
        body,
        inputs={"values": list},
        output=int,
        name=f"reduce-{operation}",
    )

sum_task = make_reducer("sum")
product_task = make_reducer("product")
```

## Building agents with programmatic tool calling

The sandboxed orchestrator and `orchestrate_local()` are the foundation for building agents that use **programmatic tool calling** — systems where an LLM generates Python orchestration code, and the sandbox executes it with registered tools.

Because `orchestrate_local()` accepts a plain code string and a list of tool functions, you can wire it into an LLM generate-execute-retry loop: the model writes code, the sandbox runs it, and on failure the error feeds back to the model for correction.

See [Programmatic tool calling for agents](./code-mode) for the full concept, agent implementation patterns, and end-to-end examples.

## Syntax restrictions

Monty enforces strict syntax restrictions to guarantee sandbox safety.
These restrictions are a feature, not a limitation — they ensure that sandboxed code is deterministic and side-effect free.

### Allowed

| Feature | Notes |
|---------|-------|
| Variables and assignment | `x = 1` |
| Arithmetic and comparisons | `x + y`, `x > y` |
| String operations | Concatenation, formatting |
| `if`/`elif`/`else` | Conditional logic |
| `for` loops | Iteration over lists, ranges, dicts |
| `while` loops | Condition-based loops |
| Function definitions (`def`) | Local helper functions |
| `async def` and `await` | Async orchestrators |
| List/dict/tuple literals | `[1, 2, 3]`, `{"key": "value"}` |
| List comprehensions | `[x * 2 for x in items]` |
| `.append()` on lists | Building lists incrementally |
| Subscript reading | `x = d["key"]`, `x = l[0]` |
| External task calls | Calling registered `@env.task` workers |
| `raise` | Raising exceptions |

### Not allowed

| Feature | Workaround |
|---------|------------|
| `import` | All available functions are provided directly |
| Subscript assignment (`d[k] = v`, `l[i] = v`) | Build dicts as literals; use `.append()` for lists |
| Augmented assignment (`x += 1`) | Use `x = x + 1` |
| `class` definitions | Use dicts or tuples |
| `with` statements | Not needed — no resource management in sandbox |
| `try`/`except` | Errors propagate to the controller |
| Walrus operator (`:=`) | Use separate assignment |
| `yield`/`yield from` | Not supported |
| `global`/`nonlocal` | Not supported |
| Set literals/comprehensions | Use lists |
| `del` statements | Not supported |
| `assert` statements | Use `if` + `raise` |

### Type restrictions

- **Primitive types**: `int`, `float`, `str`, `bool`, `bytes`, `None`
- **Collection types**: `list`, `dict`, `tuple` (including generic forms like `list[int]`, `dict[str, float]`)
- **Opaque IO handles**: `File`, `Dir`, `DataFrame` — pass-through only, cannot be inspected in the sandbox
- **Union types**: `Optional[T]` and `Union` of allowed types
- **Not allowed**: Custom classes, dataclasses, Pydantic models, or any user-defined types

## Security model

The sandboxed orchestrator provides security through restriction, not trust:

- **No filesystem access**: Cannot read, write, or list files
- **No network access**: Cannot make HTTP requests, open sockets, or resolve DNS
- **No OS access**: Cannot spawn processes, read environment variables, or access system resources
- **No imports**: Cannot load any Python modules
- **Opaque IO**: `File`, `Dir`, and `DataFrame` values pass through the sandbox without inspection — the sandbox can route them between tasks but cannot read their contents
- **Type-checked boundaries**: Inputs and outputs are validated against declared types at the sandbox boundary
- **Deterministic execution**: The same inputs always produce the same outputs (excluding external task results)

The sandbox runs untrusted code safely because dangerous operations are not just discouraged — they are structurally impossible in the Monty runtime.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/sandboxing/code-mode ===

# Programmatic tool calling for agents

**Programmatic tool calling** (also known as **code mode**) is a pattern where LLMs write executable code instead of making individual tool calls.
Rather than the model emitting a sequence of JSON tool-call objects and the system routing each one, the model generates a single block of code that calls multiple tools, transforms data, and applies logic — all executed in a sandbox.

The key insight: LLMs are trained on billions of lines of code, but only a small amount of synthetic tool-call data.
Code generation is a more natural and reliable output modality for models than structured tool-call schemas.

## Programmatic tool calling vs sequential tool calling

In sequential tool calling, every intermediate result passes through the model's context window.
The model calls one tool, reads the result, decides what to do next, calls another tool, and so on.
Each round-trip costs tokens and latency.

With programmatic tool calling, the model generates a complete program upfront.
The sandbox executes it, and only the final result returns to the model.

| Aspect | Sequential tool calling | Programmatic tool calling |
|--------|-------------|-----------|
| **Output format** | JSON tool-call objects, one at a time | A single block of executable code |
| **Data flow** | Every intermediate result passes through the model | Intermediate results stay in the sandbox |
| **Context overhead** | Grows with each tool call (all results in context) | Fixed — only tool signatures in context |
| **Multi-step logic** | Model re-invoked at every step | Sandbox executes loops, conditionals, transforms |
| **Scaling with tools** | Context grows linearly with number of tool definitions | Tools discovered progressively or loaded on demand |

## Why programmatic tool calling is powerful

### Token efficiency

Sequential tool calling loads all tool definitions into the context window upfront and passes every intermediate result through the model.
Programmatic tool calling reduces this dramatically:

- **98%+ context reduction** reported by Anthropic when using code execution with MCP servers — from 150,000 tokens down to 2,000 tokens for the same task.
- **99.9% reduction** reported by Cloudflare for large APIs — approximately 1,000 tokens with programmatic tool calling versus 1.17 million tokens when exposing each API endpoint as a separate tool.

### Performance

By eliminating round-trips through the model for intermediate steps, programmatic tool calling achieves significant speed improvements.
The sandbox evaluates conditionals, loops, and data transformations locally — no "time to first token" delay for each step.

### Natural programming patterns

Code naturally expresses patterns that are awkward or impossible in tool-call sequences:

- **Loops**: Process a list of items without the model deciding "call this tool again" for each one
- **Conditionals**: Branch on intermediate results without another model invocation
- **Data transformation**: Filter, map, and aggregate data before passing it to the next tool
- **Variable reuse**: Store intermediate results and reference them later

### Progressive tool discovery

Instead of loading hundreds of tool definitions into the context window, programmatic tool calling supports progressive discovery.
The model can search for relevant tools, load only what it needs, and compose them in code.

### Data privacy

Intermediate results stay in the sandbox execution environment.
They never re-enter the model's context window, which means sensitive data (PII, credentials, financial records) can be processed without the model seeing it.

## Example: sequential vs programmatic tool calling

Consider a task: "Analyze sales data, filter for Q4, calculate statistics, and create a chart."

### Sequential tool calling approach

The model makes serial tool calls, with each result passing through the context window:

```
Step 1: Model → tool_call: fetch_data("sales_2024")
        Result: [150KB of sales data] → back into model context

Step 2: Model → tool_call: filter_data(data, "month", ">=", "Oct")
        Result: [40KB of filtered data] → back into model context

Step 3: Model → tool_call: calculate_statistics(filtered, "revenue")
        Result: {"mean": 112000, ...} → back into model context

Step 4: Model → tool_call: create_chart("bar", "Q4 Revenue", ...)
        Result: "<canvas>...</canvas>" → back into model context
```

Four round-trips through the model.
The 150KB dataset enters the context window and stays there.

### Programmatic tool calling approach

The model generates a single code block:

```python
data = fetch_data("sales_2024")
q4_months = ["Oct", "Nov", "Dec"]
q4_data = [row for row in data if row["month"] in q4_months]
stats = calculate_statistics(q4_data, "revenue")

months = []
revenues = []
for row in q4_data:
    if row["month"] not in months:
        months.append(row["month"])
for month in months:
    total = 0
    for row in q4_data:
        if row["month"] == month:
            total = total + row["revenue"]
    revenues.append(total)

chart = create_chart("bar", "Q4 Revenue by Month", months, revenues)
{"charts": [chart], "summary": "Q4 stats: " + str(stats)}
```

One model invocation.
The data never re-enters the model's context window.
The sandbox handles the filtering, aggregation, and chart creation locally.

## Example: defining tools

Tools are plain Python functions with type annotations and docstrings.
The agent auto-generates its system prompt from these signatures, so adding a tool requires no other changes.

```python
async def fetch_data(dataset: str) -> list:
    """Fetch tabular data by dataset name.

    Available datasets:
    - "sales_2024": columns month, region, revenue, units
    - "employees": columns name, department, salary, years_exp, performance_rating
    - "website_traffic": columns date, page, visitors, bounce_rate, avg_duration
    - "inventory": columns product, category, stock, price, supplier
    """
    ...

async def create_chart(chart_type: str, title: str, labels: list, values: list) -> str:
    """Generate a self-contained Chart.js HTML snippet.

    Args:
        chart_type: One of "bar", "line", "pie", "doughnut".
        title: Chart title displayed above the canvas.
        labels: X-axis labels (or slice labels for pie/doughnut).
        values: Either a flat list of numbers, or a list of
                {"label": str, "data": list[number]} dicts for multi-series.
    """
    ...

async def calculate_statistics(data: list, column: str) -> dict:
    """Calculate descriptive statistics for a numeric column.

    Returns dict with keys: count, mean, median, min, max, std_dev.
    """
    ...

async def filter_data(data: list, column: str, operator: str, value: object) -> list:
    """Filter rows where column matches the condition.

    Operator: one of "==", "!=", ">", ">=", "<", "<=".
    """
    ...

ALL_TOOLS = {
    "fetch_data": fetch_data,
    "create_chart": create_chart,
    "calculate_statistics": calculate_statistics,
    "filter_data": filter_data,
}
```

The `ALL_TOOLS` dict is the single source of truth.
The agent introspects it to build the system prompt, and the sandbox uses it to resolve function calls.

## Example: programmatic tool-calling agent

The `CodeModeAgent` implements the generate-execute-retry loop:

```python
import flyte.sandbox
from _tools import ALL_TOOLS

class CodeModeAgent:
    def __init__(self, tools, *, model="claude-sonnet-4-6", max_retries=2):
        self._tools = tools
        self._model = model
        self._max_retries = max_retries
        # System prompt auto-generated from tool signatures + docstrings
        self.system_prompt = self._build_system_prompt()

    async def run(self, message: str, history: list[dict]) -> AgentResult:
        messages = [*history, {"role": "user", "content": message}]

        # Step 1: LLM generates Python code
        code = await generate_code(self._model, self.system_prompt, messages)

        # Step 2: Execute in Monty sandbox with registered tools
        for attempt in range(1 + self._max_retries):
            try:
                result = await flyte.sandbox.orchestrate_local(
                    code,
                    inputs={"_unused": 0},
                    tasks=list(self._tools.values()),
                )
                return AgentResult(code=code, charts=result.get("charts", []),
                                   summary=result.get("summary", ""))
            except Exception as exc:
                if attempt < self._max_retries:
                    # Step 3: Feed error back to LLM for retry
                    code = await generate_code(
                        self._model, self.system_prompt,
                        [*messages,
                         {"role": "assistant", "content": f"```python\n{code}\n```"},
                         {"role": "user", "content": f"Error: {exc}\nFix the code."}],
                    )
                    continue
                return AgentResult(code=code, error=str(exc))
```

The pattern:

1. **Generate**: The LLM receives tool signatures and the user's request, and outputs Python code.
2. **Execute**: The code runs in the Monty sandbox. Tool calls pause the sandbox, dispatch to real implementations, and resume with results.
3. **Retry**: If execution fails, the error message is fed back to the LLM, which generates a corrected version. This repeats up to `max_retries` times.

## Example: chat app

Wrap the agent in a FastAPI endpoint to create a conversational analytics assistant:

```python
from _agent import CodeModeAgent
from _tools import ALL_TOOLS
from fastapi import FastAPI

import flyte
from flyte.app.extras import FastAPIAppEnvironment

app = FastAPI(title="Chat Data Analytics Agent")

env = FastAPIAppEnvironment(
    name="chat-analytics-agent",
    app=app,
    image=flyte.Image.from_debian_base().with_pip_packages(
        "fastapi", "uvicorn", "httpx", "pydantic-monty",
    ),
    secrets=flyte.Secret(key="anthropic-api-key", as_env_var="ANTHROPIC_API_KEY"),
)

agent = CodeModeAgent(tools=ALL_TOOLS, max_retries=2)

@app.post("/api/chat")
async def chat(req: ChatRequest) -> ChatResponse:
    result = await agent.run(req.message, req.history)
    return ChatResponse(
        code=result.code,
        charts=result.charts,
        summary=result.summary,
        error=result.error,
    )
```

Users send natural language requests (`"Show me monthly revenue trends for 2024"`), the agent generates analysis code, the sandbox executes it with the registered tools, and the response includes charts and a text summary.

## Example: durable agent

For production workloads, wrap the tools as `@env.task` so the sandbox dispatches them as durable Flyte tasks through the controller.
This gives you execution history, retries, caching, and full observability.

```python
from _agent import CodeModeAgent
from _tools import ALL_TOOLS

import flyte
import flyte.report

env = flyte.TaskEnvironment(
    name="llm-code-mode",
    secrets=[flyte.Secret(key="anthropic-api-key", as_env_var="ANTHROPIC_API_KEY")],
    image=flyte.Image.from_debian_base().with_pip_packages(
        "httpx", "pydantic-monty", "unionai-reuse",
    ),
)

# Wrap each tool as a durable task
@env.task
async def fetch_data(dataset: str) -> list:
    return await _tools.fetch_data(dataset)

@env.task
async def create_chart(chart_type: str, title: str, labels: list, values: list) -> str:
    return await _tools.create_chart(chart_type, title, labels, values)

# ... wrap remaining tools similarly ...

# Agent uses plain functions for prompt generation,
# @env.task versions for durable sandbox execution
durable_tools = {t.func.__name__: t for t in [fetch_data, create_chart, ...]}
agent = CodeModeAgent(tools=ALL_TOOLS, execution_tools=durable_tools)

@env.task(report=True)
async def analyze(request: str) -> str:
    """Run the code-mode agent and render an HTML report."""
    result = await agent.run(request, [])
    report_html = build_report(request, result)
    await flyte.report.replace.aio(report_html)
    await flyte.report.flush.aio()
    return result.summary
```

The key difference from the chat app: each tool call goes through the Flyte controller as a durable task.
If `fetch_data` fails, Flyte retries it automatically.
Every tool invocation is recorded and visible in the execution timeline.

Run it with:

```bash
flyte run durable_agent.py analyze \
    --request "Show me monthly revenue trends for 2024, broken down by region"
```

## References

- [Code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) — Anthropic engineering blog on the code execution pattern
- [Code Mode](https://blog.cloudflare.com/code-mode/) — Cloudflare's introduction to code mode for LLM tool calling
- [Code Mode MCP](https://blog.cloudflare.com/code-mode-mcp/) — Cloudflare's server-side code mode implementation
- [Code Mode Protocol](https://github.com/universal-tool-calling-protocol/code-mode) — Open specification for the code mode pattern


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/sandboxing/code-sandboxing ===

# Code sandboxing

`flyte.sandbox.create()` runs arbitrary Python code or shell commands inside an ephemeral, stateless Docker container.
The container is built on demand from declared dependencies, executed once, and discarded.
Each invocation starts from a clean slate — no filesystem state, environment variables, or side effects carry over between runs.

## Execution modes

`flyte.sandbox.create()` supports three mutually exclusive execution modes.

### Auto-IO mode

The default mode. Write only the business logic — Flyte generates the I/O boilerplate automatically.

How it works:

1. Flyte generates an `argparse` preamble that parses declared inputs from CLI arguments.
2. Declared inputs become local variables in scope.
3. After your code runs, Flyte writes declared scalar outputs to `/var/outputs/` automatically.

```python{hl_lines=[2, 4, 6, 11]}
import flyte
import flyte.sandbox

sandbox = flyte.sandbox.create(
    name="double",
    code="result = x * 2",
    inputs={"x": int},
    outputs={"result": int},
)

result = await sandbox.run.aio(x=21)  # returns 42
```

No imports, no argument parsing, no file writing. The variable `x` is available directly, and the variable `result` is captured automatically because it matches a declared output name.

A more involved example with third-party packages:

```python{hl_lines=["4-9", 12, 20, 24]}
import datetime

_stats_code = """\
import numpy as np
nums = np.array([float(v) for v in values.split(",")])
mean = float(np.mean(nums))
std  = float(np.std(nums))

window_end = dt + delta
"""

stats_sandbox = flyte.sandbox.create(
    name="numpy-stats",
    code=_stats_code,
    inputs={
        "values": str,
        "dt": datetime.datetime,
        "delta": datetime.timedelta,
    },
    outputs={"mean": float, "std": float, "window_end": datetime.datetime},
    packages=["numpy"],
)

mean, std, window_end = await stats_sandbox.run.aio(
    values="1,2,3,4,5",
    dt=datetime.datetime(2024, 1, 1),
    delta=datetime.timedelta(days=1),
)
```

When there are multiple outputs, `.run()` returns them as a tuple in declaration order.

### Verbatim mode

Set `auto_io=False` to run a complete Python script with full control over I/O.
Flyte runs the script exactly as written — no injected preamble, no automatic output collection.

Your script must:

- Read inputs from `/var/inputs/<name>` (files are bind-mounted at these paths)
- Write outputs to `/var/outputs/<name>`

```python{hl_lines=["4-9", 12, 17]}
from flyte.io import File

_etl_script = """\
import json, pathlib

payload = json.loads(pathlib.Path("/var/inputs/payload").read_text())
total = sum(payload["values"])

pathlib.Path("/var/outputs/total").write_text(str(total))
"""

etl_sandbox = flyte.sandbox.create(
    name="etl-script",
    code=_etl_script,
    inputs={"payload": File},
    outputs={"total": int},
    auto_io=False,
)

total = await etl_sandbox.run.aio(payload=payload_file)
```

Use verbatim mode when you need precise control over how inputs are read and outputs are written, or when your script has its own argument parsing.

### Command mode

Run any shell command, binary, or pipeline. Provide `command` instead of `code`.

```python{hl_lines=[5]}
from flyte.io import File

linecount_sandbox = flyte.sandbox.create(
    name="line-counter",
    command=[
        "/bin/bash",
        "-c",
        "grep -c . /var/inputs/data_file > /var/outputs/line_count || echo 0 > /var/outputs/line_count",
    ],
    inputs={"data_file": File},
    outputs={"line_count": str},
)

count = await linecount_sandbox.run.aio(data_file=data_file)
```

Command mode is useful for running test suites, compiled binaries, shell pipelines, or any non-Python workload.

Use `arguments` to pass positional arguments to the command.
File inputs are bind-mounted at `/var/inputs/<name>` and can be referenced in the arguments list:

```python{hl_lines=[4, 5]}
sandbox = flyte.sandbox.create(
    name="test-runner",
    command=["/bin/bash", "-c", pytest_cmd],
    arguments=["/var/inputs/solution.py", "/var/inputs/tests.py"],
    inputs={"solution.py": File, "tests.py": File},
    outputs={"exit_code": str},
)
```

## Executing a sandbox

Call `.run()` on the sandbox object to build the image and execute.

**Async execution**

```python
result = await sandbox.run.aio(x=21)
```

**Sync execution**

```python
result = sandbox.run(x=21)
```

Both forms build the container image (if not already built), start the container, execute the code or command, collect outputs, and discard the container.

`flyte.sandbox.create()` defines the sandbox configuration and can be called at module level or inside a task. The actual container execution happens when you call `.run()`, which must run inside a Flyte task (either locally or remotely on the cluster).

### Error handling

If the sandbox code fails (non-zero exit code, Python exception, or timeout), `.run()` raises an exception with the error details.
If `retries` is set, Flyte automatically retries the execution before surfacing the error.

If the image build fails due to an invalid package, an `InvalidPackageError` is raised with the package name and the underlying error message.

## Supported types

Inputs and outputs must use one of the following types:

| Category         | Types                                     |
| ---------------- | ----------------------------------------- |
| **Primitive**    | `int`, `float`, `str`, `bool`             |
| **Date/time**    | `datetime.datetime`, `datetime.timedelta` |
| **File handles** | `flyte.io.File`                           |

### How types are handled

**In auto-IO mode:**

- **Primitive and date/time inputs** are injected as local variables with the correct Python type. Flyte generates an `argparse` preamble behind the scenes — your code just uses the variable names directly.
- **`File` inputs** are bind-mounted into the container. The input variable contains the file path as a string (e.g., `"/var/inputs/payload"`), so you can read it with `pathlib.Path(payload).read_text()`.
- **Primitive and date/time outputs** are written to `/var/outputs/<name>` automatically. Just assign the value to a variable matching the declared output name.
- **`File` outputs** are the exception — your code must write the file to `/var/outputs/<name>` manually.

**In verbatim mode:**

- All inputs (including primitives) are available at `/var/inputs/<name>`. Your script reads them directly from the filesystem.
- All outputs must be written to `/var/outputs/<name>` by your script.

**In command mode:**

- `File` inputs are bind-mounted at `/var/inputs/<name>`.
- All outputs must be written to `/var/outputs/<name>` by your command.

## Configuring the container image

### Python packages

Install PyPI packages with `packages`:

```python{hl_lines=[6]}
sandbox = flyte.sandbox.create(
    name="data-analysis",
    code="...",
    inputs={"data": str},
    outputs={"result": str},
    packages=["numpy", "pandas>=2.0", "scikit-learn"],
)
```

### System packages

Install system-level (apt) packages with `system_packages`:

```python{hl_lines=[7]}
sandbox = flyte.sandbox.create(
    name="image-processor",
    code="...",
    inputs={"image": File},
    outputs={"result": File},
    packages=["Pillow"],
    system_packages=["libgl1-mesa-glx", "libglib2.0-0"],
)
```

> [!NOTE]
> `gcc`, `g++`, and `make` are included automatically in every sandbox image.

### Additional Dockerfile commands

For advanced image customization, use `additional_commands` to inject arbitrary `RUN` commands into the Dockerfile:

```python{hl_lines=[6]}
sandbox = flyte.sandbox.create(
    name="custom-env",
    code="...",
    inputs={"x": int},
    outputs={"y": int},
    additional_commands=["curl -sSL https://example.com/setup.sh | bash"],
)
```

### Pre-built images

Skip the image build entirely by providing a pre-built image URI:

```python{hl_lines=[6]}
sandbox = flyte.sandbox.create(
    name="prebuilt",
    code="result = x + 1",
    inputs={"x": int},
    outputs={"result": int},
    image="ghcr.io/my-org/my-sandbox-image:latest",
)
```

### Image configuration

Control the registry and Python version with `ImageConfig`:

```python{hl_lines=["8-12"]}
from flyte.sandbox import ImageConfig

sandbox = flyte.sandbox.create(
    name="custom-registry",
    code="...",
    inputs={"x": int},
    outputs={"y": int},
    image_config=ImageConfig(
        registry="ghcr.io/my-org",
        registry_secret="ghcr-credentials",
        python_version=(3, 12),
    ),
)
```

## Runtime configuration

### Resources

Set CPU and memory limits for the container:

```python{hl_lines=[6]}
sandbox = flyte.sandbox.create(
    name="heavy-compute",
    code="...",
    inputs={"data": str},
    outputs={"result": str},
    resources=flyte.Resources(cpu=4, memory="8Gi"),
)
```

The default is 1 CPU and 1Gi memory.

### Retries

Automatically retry failed executions:

```python{hl_lines=[6]}
sandbox = flyte.sandbox.create(
    name="flaky-task",
    code="...",
    inputs={"x": int},
    outputs={"y": int},
    retries=3,
)
```

### Timeout

Set a maximum execution time in seconds:

```python{hl_lines=[6]}
sandbox = flyte.sandbox.create(
    name="bounded-task",
    code="...",
    inputs={"x": int},
    outputs={"y": int},
    timeout=300,  # 5 minutes
)
```

### Environment variables

Inject environment variables into the container:

```python{hl_lines=[6]}
sandbox = flyte.sandbox.create(
    name="configured-task",
    code="...",
    inputs={"x": int},
    outputs={"y": int},
    env_vars={"LOG_LEVEL": "DEBUG", "FEATURE_FLAG": "true"},
)
```

### Secrets

Mount Flyte secrets into the container:

```python{hl_lines=[6]}
sandbox = flyte.sandbox.create(
    name="authenticated-task",
    code="...",
    inputs={"query": str},
    outputs={"result": str},
    secrets=[flyte.Secret(key="api-key", as_env_var="API_KEY")],
)
```

### Caching

Control output caching behavior:

```python{hl_lines=["6-8"]}
sandbox = flyte.sandbox.create(
    name="cached-task",
    code="...",
    inputs={"x": int},
    outputs={"y": int},
    cache="auto",      # default — Flyte decides based on inputs
    # cache="override"  # force re-execution and update cache
    # cache="disable"   # no caching
)
```

## Deploying a sandbox as a task

Use `.as_task()` to convert a sandbox into a deployable `ContainerTask`.
The returned task has the generated script pre-filled as a default input, so retriggers from the UI only require user-declared inputs.

This pattern is useful when you want to define a sandbox dynamically (for example, with LLM-generated code) and then deploy it as a standalone task that others can trigger from the UI.

```python{hl_lines=[4, 11, "33-38"]}
import flyte
import flyte.sandbox
from flyte.io import File
from flyte.sandbox import sandbox_environment

# sandbox_environment provides the base runtime image for code sandboxes.
# Include it in depends_on so Flyte builds the sandbox runtime before your task runs.
env = flyte.TaskEnvironment(
    name="sandbox-demo",
    image=flyte.Image.from_debian_base(name="sandbox-demo"),
    depends_on=[sandbox_environment],
)

@env.task
async def deploy_sandbox_task() -> str:
    # Initialize the Flyte client for in-cluster operations (image building, deployment)
    flyte.init_in_cluster()

    sandbox = flyte.sandbox.create(
        name="deployable-sandbox",
        # In auto-IO mode, File inputs become path strings — read with pathlib
        code="""\
import json, pathlib
data = json.loads(pathlib.Path(payload).read_text())
total = sum(data["values"])
""",
        inputs={"payload": File},
        outputs={"total": int},
        resources=flyte.Resources(cpu=1, memory="512Mi"),
    )

    # Build the image and get a ContainerTask with the script pre-filled
    task = await sandbox.as_task.aio()

    # Create a TaskEnvironment from the task and deploy it
    deploy_env = flyte.TaskEnvironment.from_task("deployable-sandbox", task)
    versions = flyte.deploy(deploy_env)

    return versions[0].summary_repr()
```

## End-to-end example

The following example defines sandboxes in all three modes, creates helper tasks, and runs everything in a single pipeline:

```
import datetime
from pathlib import Path

import flyte
import flyte.sandbox
from flyte.io import File
from flyte.sandbox import sandbox_environment

# sandbox_environment provides the base runtime for code sandboxes.
# Include it in depends_on so the sandbox runtime is available when tasks execute.
env = flyte.TaskEnvironment(
    name="sandbox-demo",
    image=flyte.Image.from_debian_base(name="sandbox-demo"),
    depends_on=[sandbox_environment],
)

# Auto-IO mode: pure computation
sum_sandbox = flyte.sandbox.create(
    name="sum-to-n",
    code="total = sum(range(n + 1)) if conditional else 0",
    inputs={"n": int, "conditional": bool},
    outputs={"total": int},
)

# Auto-IO mode with packages
_stats_code = """\
import numpy as np
nums = np.array([float(v) for v in values.split(",")])
mean = float(np.mean(nums))
std  = float(np.std(nums))
window_end = dt + delta
"""

stats_sandbox = flyte.sandbox.create(
    name="numpy-stats",
    code=_stats_code,
    inputs={
        "values": str,
        "dt": datetime.datetime,
        "delta": datetime.timedelta,
    },
    outputs={"mean": float, "std": float, "window_end": datetime.datetime},
    packages=["numpy"],
)

# Verbatim mode: full script control
_etl_script = """\
import json, pathlib

payload = json.loads(pathlib.Path("/var/inputs/payload").read_text())
total = sum(payload["values"])

pathlib.Path("/var/outputs/total").write_text(str(total))
"""

etl_sandbox = flyte.sandbox.create(
    name="etl-script",
    code=_etl_script,
    inputs={"payload": File},
    outputs={"total": int},
    auto_io=False,
)

# Command mode: shell pipeline
linecount_sandbox = flyte.sandbox.create(
    name="line-counter",
    command=[
        "/bin/bash",
        "-c",
        "grep -c . /var/inputs/data_file > /var/outputs/line_count || echo 0 > /var/outputs/line_count",
    ],
    inputs={"data_file": File},
    outputs={"line_count": str},
)

@env.task
async def create_text_file() -> File:
    path = Path("/tmp/data.txt")
    path.write_text("line 1\n\nline 2\n")
    return await File.from_local(str(path))

@env.task
async def payload_generator() -> File:
    path = Path("/tmp/payload.json")
    path.write_text('{"values": [1, 2, 3, 4, 5]}')
    return await File.from_local(str(path))

@env.task
async def run_pipeline() -> dict:
    # Auto-IO: sum 1..10 = 55
    total = await sum_sandbox.run.aio(n=10, conditional=True)

    # Auto-IO with numpy
    mean, std, window_end = await stats_sandbox.run.aio(
        values="1,2,3,4,5",
        dt=datetime.datetime(2024, 1, 1),
        delta=datetime.timedelta(days=1),
    )

    # Verbatim ETL
    payload = await payload_generator()
    etl_total = await etl_sandbox.run.aio(payload=payload)

    # Command mode: line count
    data_file = await create_text_file()
    line_count = await linecount_sandbox.run.aio(data_file=data_file)

    return {
        "sum_1_to_10": total,
        "mean": round(mean, 4),
        "std": round(std, 4),
        "window_end": window_end.isoformat(),
        "etl_sum_1_to_10": etl_total,
        "line_count": line_count,
    }

if __name__ == "__main__":
    flyte.init_from_config()

    r = flyte.run(run_pipeline)
    print(f"run url: {r.url}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/sandboxing/code_sandbox.py*

## API reference

### `flyte.sandbox.create()`

| Parameter             | Type              | Description                                                |
| --------------------- | ----------------- | ---------------------------------------------------------- |
| `name`                | `str`             | Sandbox name. Derives task and image names.                |
| `code`                | `str`             | Python source to run. Mutually exclusive with `command`.   |
| `inputs`              | `dict[str, type]` | Input type declarations.                                   |
| `outputs`             | `dict[str, type]` | Output type declarations.                                  |
| `command`             | `list[str]`       | Shell command to run. Mutually exclusive with `code`.      |
| `arguments`           | `list[str]`       | Arguments forwarded to `command`.                          |
| `packages`            | `list[str]`       | Python packages to install via pip.                        |
| `system_packages`     | `list[str]`       | System packages to install via apt.                        |
| `additional_commands` | `list[str]`       | Extra Dockerfile `RUN` commands.                           |
| `resources`           | `flyte.Resources` | CPU and memory limits. Default: 1 CPU, 1Gi memory.         |
| `image_config`        | `ImageConfig`     | Registry and Python version settings.                      |
| `image_name`          | `str`             | Explicit image name (overrides auto-generated).            |
| `image`               | `str`             | Pre-built image URI (skips build).                         |
| `auto_io`             | `bool`            | Auto-generate I/O wiring. Default: `True`.                 |
| `retries`             | `int`             | Number of retries on failure. Default: `0`.                |
| `timeout`             | `int`             | Timeout in seconds.                                        |
| `env_vars`            | `dict[str, str]`  | Environment variables for the container.                   |
| `secrets`             | `list[Secret]`    | Flyte secrets to mount.                                    |
| `cache`               | `str`             | `"auto"`, `"override"`, or `"disable"`. Default: `"auto"`. |

### Sandbox methods

| Method                            | Description                                                       |
| --------------------------------- | ----------------------------------------------------------------- |
| `sandbox.run(**kwargs)`           | Build the image and execute synchronously. Returns typed outputs. |
| `await sandbox.run.aio(**kwargs)` | Async version of `run()`.                                         |
| `sandbox.as_task()`               | Build the image and return a deployable `ContainerTask`.          |
| `await sandbox.as_task.aio()`     | Async version of `as_task()`.                                     |

Both `run()` and `as_task()` accept an optional `image` parameter to provide a pre-built image URI, skipping the build step.


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/authenticating ===

# Authenticating with Union

Union supports three authentication modes to suit different environments and use cases. This guide will help you choose the right authentication method and configure it correctly.

## Quick start

For most users getting started with Union:

### Programmatic

```python
import flyte

# Initialize with PKCE authentication (default)
flyte.init(endpoint="dns:///your-endpoint.hosted.unionai.cloud")
```

Or, if you have a configuration file:

```python
import flyte

flyte.init_from_config()
```

### CLI

1. Create a configuration file:
    ```bash
      flyte create config --endpoint https://your-endpoint.unionai.cloud
    ```

    Optionally, you can also add a default project and domain.
    ```bash
      flyte create config --endpoint http://your-endpoint.unionai.cloud --project flytesnacks --domain development
    ```

2. Run any command to authenticate:
   ```bash
   flyte get project
   ```

This will automatically open your browser to complete authentication.

> [!NOTE]
> For details on creating and managing configuration files, see [Connecting to a cluster](./connecting-to-a-cluster#configuration-file).

## Authentication modes

### PKCE authentication (browser-based) {#pkce}

**Default mode** - Uses OAuth2 PKCE flow with automatic browser authentication.

#### When to use

- Interactive development on your laptop or workstation
- Jupyter notebooks running locally or on machines with browser access
- Any environment where you can open a web browser

#### How it works

When you run any Flyte command, Union automatically:
1. Opens your default web browser
2. Prompts you to authenticate
3. Stores credentials securely in your system's keyring that auto-refresh every few hours

> [!NOTE]
> Tokens are stored securely in your system's native keyring (e.g., Keychain Access on macOS). On systems without keyring support, see the **Authenticating with Union > Token storage and keyring** section.

#### Usage

### Programmatic

```python
import flyte
import flyte.remote as remote

# Initialize with PKCE authentication (default)
flyte.init(endpoint="dns:///your-endpoint.hosted.unionai.cloud")

print([t for t in remote.Task.listall(project="flytesnacks", domain="development")])
```

If your configuration file is accessible, you can also initialize with `init_from_config`:

```python
import flyte

flyte.init_from_config("/path/to/config.yaml")
```

Or omitting the path to pick up from the default locations:

```python
flyte.init_from_config()
```

### CLI

This is the default authentication type when you create a configuration from the `flyte create config` command. The generated file has the effect of:

```yaml
admin:
  endpoint: dns:///your-endpoint.hosted.unionai.cloud
  authType: Pkce
  insecure: false
```

Since the PKCE method is default, it's omitted from the generated file, as is disabling SSL.

Simply run any command - authentication happens automatically:

```bash
flyte get project
flyte run app.py main
flyte deploy app.py
```

### Device flow authentication {#device-flow}

**For headless or browser-restricted environments** - Uses OAuth2 device flow with code verification.

#### When to use

- Remote servers without GUI/browser access
- Hosted notebook environments (Google Colab, AWS SageMaker, Azure ML)
- SSH sessions or terminal-only environments
- Docker containers where browser redirect isn't possible

#### How it works

When you run a command, Union displays a URL and user code. You:
1. Open the URL on any browser (on any device)
2. Enter the displayed code
3. Complete authentication
4. Return to your terminal - the session is now authenticated

Tokens are stored securely in your system's keyring. On systems without keyring support (common in headless Linux environments), see the **Authenticating with Union > Token storage and keyring** section.

#### Usage

### Programmatic

**In Python scripts:**

```python
import flyte

env = flyte.TaskEnvironment("my-project")

@env.task
def my_task():
    return "Hello Union!"

if __name__ == "__main__":
    # Initialize with device flow authentication
    flyte.init(endpoint="dns:///your-union-endpoint", headless=True)

    # Your workflow execution code here
```

**Example: Google Colab**

```python
# In a Colab notebook
import flyte

# This will display a URL and code in the cell output
flyte.init(
    endpoint="dns:///your-union-endpoint",
    headless=True
)

# Define and run your workflows
env = flyte.TaskEnvironment("my-project")

@env.task
def process_data(data: str) -> str:
    return f"Processed: {data}"
```

### CLI

Create or update your config to use device flow:

```bash
flyte create config --endpoint http://your-endpoint.unionai.cloud --auth-type headless
```

Your config file will contain:

```yaml
admin:
  authType: DeviceFlow
  endpoint: dns:///your-endpoint.hosted.unionai.cloud
```

When you run a command, you'll see:

```bash
flyte get app
```

Output:

```bash
To Authenticate, navigate in a browser to the following URL:
https://signin.hosted.unionai.cloud/activate?user_code=TKBJXFFW
```

Open that URL on any device with a browser, enter the code, and authentication completes.

### API key authentication (OAuth2 app credentials) {#api-key}

**For automated and CI/CD environments** - Uses OAuth2 client credentials encoded as an API key.

#### When to use

- CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins)
- Automated deployment scripts
- Production workloads
- Any non-interactive environment
- Service-to-service authentication

#### How it works

Union encodes OAuth2 client credentials (client ID and client secret) into a single API key string. This key contains all information needed to connect to Union, including the endpoint.

> [!NOTE]
> **Security Note:** API keys are sensitive credentials. Treat them like passwords:
> - Store them in secret management systems (GitHub Secrets, AWS Secrets Manager, etc.)
> - Never commit them to version control
> - Rotate them regularly
> - Use different keys for different environments

#### Usage

### Programmatic

The Flyte SDK provides two methods for initializing with API keys:

1. **Using `flyte.init_from_api_key()`** (recommended for API key authentication):

```python
import flyte

# Initialize with API key from FLYTE_API_KEY environment variable (default)
flyte.init_from_api_key()

# Or explicitly pass the API key
flyte.init_from_api_key(api_key="your-encoded-api-key")

# Use with remote APIs
import flyte.remote as remote
tasks = remote.Task.listall(project="flytesnacks", domain="development")
```

2. **Using `flyte.init()` with api_key parameter**:

```python
import flyte

# Initialize with API key - endpoint is embedded in the key
flyte.init(api_key="your-encoded-api-key")

# Use with remote APIs
import flyte.remote as remote
tasks = remote.Task.listall(project="flytesnacks", domain="development")
```

Both methods work identically. The `init_from_api_key()` method is a convenience function specifically designed for API key authentication. If no `api_key` parameter is provided, it automatically reads from the `FLYTE_API_KEY` environment variable.

> [!NOTE]
> The API key is a base64-encoded string containing endpoint, client_id, client_secret, and org information. The SDK automatically decodes this and uses OAuth2 client credentials flow for authentication.

**Example: Automated deployment script**

```python
#!/usr/bin/env python3
import flyte

env = flyte.TaskEnvironment("my-project")

@env.task
def automated_task():
    return "Deployed from automation"

if __name__ == "__main__":
    # Option 1: Use init_from_api_key (reads from FLYTE_API_KEY env var by default)
    flyte.init_from_api_key()

    # Option 2: Explicitly pass the API key
    # import os
    # api_key = os.getenv("FLYTE_API_KEY")
    # if not api_key:
    #     raise ValueError("FLYTE_API_KEY environment variable not set")
    # flyte.init_from_api_key(api_key=api_key)

    # Deploy or run workflows
    # ... your deployment code here
```

**Example: Script using Flyte remote APIs**

When you're not declaring tasks but only calling remote APIs, you can call `flyte.init()` at module level (similar to notebooks):

```python
#!/usr/bin/env python3
import flyte
import flyte.remote as remote

# Initialize with API key
flyte.init_from_api_key()

# Use remote APIs
tasks = remote.Task.listall(project="flytesnacks", domain="development")
for task in tasks:
    print(f"Task: {task.name}")
```

### CLI

1. Install the Union plugin:

   ```bash
   pip install flyteplugins-union
   ```

2. Ensure the API key is there:

   ```bash
   flyte get api-key my-ci-key
   ```

3. Store this key securely (e.g., in GitHub Secrets, secret manager)

**Managing API keys**

List existing keys:
```bash
flyte get api-key
```

Delete a key:
```bash
flyte delete api-key my-ci-key
```

#### Using API keys with Union Apps

API keys created with `flyte create api-key` can be used to authenticate requests to Union Apps hosted on your Union cluster. However, note that:

> [!IMPORTANT]
> API keys **cannot** be used directly against Union APIs (like the admin API) unless you're using the Flyte SDK or another language SDK/OAuth2 client. For direct API access, contact the Union team for guidance on proper authentication methods.

**Using API keys with Union Apps:**

When you create an API key using `flyte create api-key`, you can use it to invoke HTTP endpoints in your Union Apps by passing it in the `Authorization: Bearer` header:

Create an API key:

```bash
flyte create api-key my-app-key
```

Use the API key to call a Union App endpoint:

```bash
curl -H "Authorization: Bearer <your-api-key>" \
  https://little-credit-4fff1.apps.dogfood-gcp.cloud-staging.union.ai/profile
```

**Example response:**

```json
{
  "subject": "Some-subject-id",
  "name": ""
}
```

The `/profile` endpoint (or similar identity endpoints in your app) returns information about the authenticated identity. When using an API key, this will be a bot identity, as the API key uses client app ID and secret for authentication.

> [!TIP]
> Different Union Apps may expose different endpoints. Common patterns include:
> - `/profile` or `/me` - Returns the authenticated user/bot identity
> - `/health` - Health check endpoint
> - Custom application endpoints specific to your workflow

## Comparison table

| Feature | PKCE | Device Flow | API Key |
|---------|------|-------------|---------|
| **Environment** | Browser available | Headless/remote | Fully automated |
| **Authentication** | Automatic browser | Manual code entry | Non-interactive |
| **Token refresh** | Automatic | Automatic | Automatic |
| **Best for** | Local development | Remote notebooks | CI/CD, production |
| **Setup complexity** | Minimal | Minimal | Moderate (requires plugin) |
| **Security** | User credentials | User credentials | App credentials |

## Switching between authentication modes

You can switch authentication modes by updating your config file:

Switch to PKCE:

```bash
flyte create config --endpoint dns:///your-endpoint.hosted.unionai.cloud
```

Switch to device flow:

```bash
flyte create config --endpoint dns:///your-endpoint.hosted.unionai.cloud --auth-type headless
```

Or manually edit your `~/.flyte/config.yaml`:

```yaml
admin:
  authType: Pkce  # or DeviceFlow
  endpoint: dns:///your-union-endpoint
```

## Token storage and keyring {#token-storage}

Flyte stores authentication tokens securely using your system's native keyring. This provides secure credential storage and allows you to stay authenticated across CLI commands and interactive sessions without re-authenticating.

### How it works

When you authenticate using PKCE or device flow, Flyte stores your OAuth tokens in:
- **macOS**: Keychain Access
- **Windows**: Windows Credential Manager
- **Linux**: Secret Service API (GNOME Keyring, KWallet, etc.)

These tokens are automatically refreshed as needed, providing a seamless experience across multiple commands and sessions.

### Systems without keyring support

Some environments, particularly headless Linux systems like remote desktops, Docker containers, or minimal server installations, may not have a keyring service available.

**Symptoms:**
- You are prompted to re-authenticate every time you run a Flyte command
- You need to authenticate again each time you start a new interactive Python session
- You see warnings about keyring access failures

### Solution: Install keyrings.alt

For systems without native keyring support, install the `keyrings.alt` package:

```bash
pip install keyrings.alt
```

This package provides an alternative keyring backend that stores credentials in an encrypted file on disk, allowing token persistence across sessions.

**Installation in different environments:**

Standard installation:

```bash
pip install keyrings.alt
```

With UV:

```bash
uv pip install keyrings.alt
```

In a Docker container (add to your Dockerfile):

```dockerfile
RUN pip install keyrings.alt
```

After installing `keyrings.alt`, Flyte will automatically use it to store tokens, eliminating the need for repeated authentication.

> [!NOTE]
> While `keyrings.alt` is less secure than native keyring systems, it's significantly better than re-authenticating for every command and is appropriate for headless development environments.

### Verifying keyring functionality

To check if keyring is working correctly:

```python
import keyring
print(keyring.get_keyring())
```

You should see output indicating which keyring backend is active:
- Native keyring: `keyring.backends.OS_X.Keyring` (macOS), `keyring.backends.Windows.WinVaultKeyring` (Windows), etc.
- Alternative keyring: `keyrings.alt.file.PlaintextKeyring` or similar

## Troubleshooting

### Browser doesn't open for PKCE

If the browser doesn't open automatically:
1. Copy the URL shown in your terminal
2. Open it manually in your browser
3. Complete the authentication flow

Alternatively, switch to device flow if you're in a headless environment.

### Device flow code expires

Device flow codes typically expire after a few minutes. If your code expires:
1. Run the command again to get a new code
2. Authenticate more quickly

### API key doesn't work

Ensure you've installed the required plugin:
```bash
pip install flyteplugins-union
```

Verify your API key is set correctly:
```bash
echo $FLYTE_API_KEY
```

## Best practices

1. **Local development**: Use PKCE authentication for the best experience
2. **Remote development**: Use device flow for hosted notebooks and SSH sessions
3. **Production/CI**: Always use API keys for automated environments
4. **API key security**:
   - Store in secret managers (GitHub Secrets, AWS Secrets Manager, Vault)
   - Never commit to version control
   - Rotate regularly
   - Use different keys per environment (dev, staging, prod)
5. **Config management**: Keep your `~/.flyte/config.yaml` in source control (without secrets) to maintain consistent settings across your team


=== PAGE: https://www.union.ai/docs/v2/union/user-guide/user-management ===

# User management

Union includes role-based access control (RBAC) for managing user and application permissions.
The system has four core concepts:

* **Role**: A named set of actions (e.g. view inventory, create executions).
* **Policy**: Binds one or more roles to specific projects, domains, or the entire organization.
* **User / Application**: An actor assigned to policies. Users are identified by email; applications by ID.
* **Action**: An operation like `view_flyte_inventory` or `create_flyte_executions`.

## Built-in policies

Union ships with three built-in policies:

| Policy | Actions | Summary |
|---|---|---|
| **Admin** | All actions | Full control including user management and billing |
| **Contributor** | `create_flyte_executions`, `register_flyte_inventory`, `view_flyte_executions`, `view_flyte_inventory` | Register and run workflows |
| **Viewer** | `view_flyte_executions`, `view_flyte_inventory` | Read-only access |

Users can hold multiple policies — permissions are the union of all assigned policies.

## Custom roles and policies

For fine-grained control, create custom roles and policies using the CLI or programmatically.

### Prerequisites

Install the Union CLI plugin:

```bash
pip install flyteplugins-union
```

This adds `role`, `policy`, `assignment`, `user`, and `member` subcommands to the `flyte` CLI.

### Walkthrough: restrict a team to run workflows in production only

The goal: create a role that can view and execute workflows but not register new ones,
bind it to the production domain of a specific project, and assign it to a user.

### Programmatic

```python
from flyteplugins.union.remote import Role, Policy, Assignment

# Step 1 — Create the role
Role.create(
    "Production Runner",
    description="Can view and execute workflows",
    actions=[
        "view_flyte_inventory",
        "view_flyte_executions",
        "create_flyte_executions",
    ],
)

# Step 2 — Create the policy
Policy.create(
    "Team Prod Access",
    description="Production execution access for the team",
    bindings=[
        {
            "role": "Production Runner",
            "resource": {
                "project": "my-project",
                "domain": "production",
            },
        },
    ],
)

# Step 3 — Assign the policy to a user
Assignment.create(email="jane@example.com", policy="Team Prod Access")
```

### CLI

**Step 1 — Create the role**

Use `--edit` to open an interactive editor (no YAML file needed):

```bash
flyte create role "Production Runner" --edit
```

Your `$EDITOR` opens with a template. Set the actions:

```yaml
name: Production Runner
description: Can view and execute workflows
actions:
  - view_flyte_inventory
  - view_flyte_executions
  - create_flyte_executions
```

Save and close — the role is created.

**Step 2 — Create the policy**

```bash
flyte create policy "Team Prod Access" --edit
```

Bind the role to a specific project and domain:

```yaml
name: Team Prod Access
description: Production execution access for the team
bindings:
  - role: Production Runner
    resource:
      project: my-project
      domain: production
```

**Step 3 — Assign the policy to a user**

```bash
flyte create assignment --email jane@example.com --policy "Team Prod Access"
```

You can also assign by user subject or application credentials subject:

```bash
flyte create assignment --user-subject user-123 --policy "Team Prod Access"
flyte create assignment --creds-subject app-456 --policy "Team Prod Access"
```

### Updating roles and policies

### Programmatic

```python
from flyteplugins.union.remote import Role, Policy

# Add an action to an existing role
Role.update(
    "Production Runner",
    actions=[
        "view_flyte_inventory",
        "view_flyte_executions",
        "create_flyte_executions",
        "register_flyte_inventory",  # newly added
    ],
)

# Update policy bindings
policy = Policy.get("Team Prod Access")
new_bindings = policy.bindings + [
    {
        "role": "Production Runner",
        "resource": {"project": "my-project", "domain": "staging"},
    },
]
Policy.update("Team Prod Access", old_bindings=policy.bindings, new_bindings=new_bindings)
```

### CLI

`update` opens the existing definition in your editor so you can modify it in place:

```bash
flyte update role "Production Runner"
flyte update policy "Team Prod Access"
```

## Managing users in the UI

Navigate to **Settings > User Management** to:

* **View users** — see all users and their assigned policies.
* **Add a user** — specify name, email, and policies. The user receives an email invite.
* **Change policies** — select a user and edit their assignments.
* **Remove a user** — select a user and remove them.

## Available actions

| Action | Description |
|---|---|
| `administer_project` | Archive/update projects, manage customizable resources |
| `manage_permissions` | Manage users, applications, and policy assignments |
| `create_flyte_executions` | Launch executions |
| `register_flyte_inventory` | Register workflows, tasks, and launch plans |
| `view_flyte_executions` | View execution history |
| `view_flyte_inventory` | View registered workflows, tasks, and launch plans |

## CLI command reference

| Command | Description |
|---|---|
| `flyte create role <name> --edit \| --file <path>` | Create a role interactively or from YAML |
| `flyte get role [<name>]` | List all roles or view a specific one |
| `flyte update role <name>` | Edit a role in `$EDITOR` |
| `flyte delete role <name>` | Delete a role |
| `flyte create policy <name> --edit \| --file <path>` | Create a policy interactively or from YAML |
| `flyte get policy [<name>]` | List all policies or view a specific one |
| `flyte update policy <name>` | Edit a policy in `$EDITOR` |
| `flyte delete policy <name>` | Delete a policy |
| `flyte create assignment --email <email> \| --user-subject <id> \| --creds-subject <id> --policy <name>` | Assign a policy to a user or application |
| `flyte get assignment [--user-subject <id> \| --creds-subject <id>]` | List all assignments or view a specific one |
| `flyte delete assignment --user-subject <id> \| --creds-subject <id> --policy <name>` | Unassign a policy from a user or application |
| `flyte get user [<subject>]` | List all users or view a specific one |
| `flyte delete user <subject>` | Delete a user |
| `flyte get member` | List all members (users and applications) |


=== PAGE: https://www.union.ai/docs/v2/union/tutorials ===

# Tutorials

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

This section contains tutorials that showcase relevant use cases and provide step-by-step instructions on how to implement various features using Flyte and Union.

### **Automatic prompt engineering**

Easily run prompt optimization with real-time observability, traceability, and automatic recovery.

### **GPU-accelerated climate modeling**

Run ensemble atmospheric simulations on H200 GPUs with multi-source data ingestion and real-time extreme event detection.

### **Run LLM-generated code**

Securely execute and iterate on LLM-generated code using a code agent with error reflection and retry logic.

### **Deep research**

Build an agentic workflow for deep research with multi-step reasoning and evaluation.

### **Distributed LLM pretraining**

Pretrain large language models at scale with PyTorch Lightning, FSDP, and H200 GPUs, featuring streaming data and real-time metrics.

### **Fine-tuning a vision-language model with a frozen backbone**

Adapt Qwen2.5-VL to occluded image classification by training a 10K-parameter adapter with multi-node DeepSpeed, automatic recovery, and live training dashboards.

### **Hyperparameter optimization**

Run large-scale HPO experiments with zero manual tracking, deterministic results, and automatic recovery.

### **Multi-agent trading simulation**

A multi-agent trading simulation, modeling how agents within a firm might interact, strategize, and make trades collaboratively.

### **Text-to-SQL**

Learn how to turn natural language questions into SQL queries with Flyte and LlamaIndex, and explore prompt optimization in practice.

## Subpages
- **Distributed LLM pretraining**
- **Fine-tuning a vision-language model with a frozen backbone**
- **GPU-accelerated climate modeling**
- **Multi-agent trading simulation**
- **Run LLM-generated code**
- **Text-to-SQL**
- **Automatic prompt engineering**
- **Batching strategies for efficient scaling**
- **Deep research**
- **Hyperparameter optimization**


=== PAGE: https://www.union.ai/docs/v2/union/tutorials/distributed-pretraining ===

# Distributed LLM pretraining

When training large models, infrastructure should not be the hardest part. The real work is in the model architecture, the data, and the hyperparameters. In practice, though, teams often spend weeks just trying to get distributed training to run reliably.

And when it breaks, it usually breaks in familiar ways: out-of-memory crashes, corrupted checkpoints, data loaders that silently fail, or runs that hang with no obvious explanation.

Most distributed training tutorials focus on PyTorch primitives. This one focuses on getting something that actually ships. We go into the technical details, such as how FSDP shards parameters, why gradient clipping behaves differently at scale, and how streaming datasets reduce memory pressure, but always with the goal of building a system that works in production.

Real training jobs need more than a training loop. They need checkpointing, fault tolerance, data streaming, visibility into what’s happening, and the ability to recover from failures. In this tutorial, we build all of that using Flyte, without having to stand up or manage any additional infrastructure.

> [!NOTE]
> Full code available [here](https://github.com/unionai/unionai-examples/tree/main/v2/tutorials/pretraining/train.py).

## Overview

We're going to pretrain a GPT-2 style language model from scratch. This involves training on raw text data starting from randomly initialized weights, rather than fine-tuning or adapting a pretrained model. This is the same process used to train the original GPT-2, LLaMA, and most other foundation models.

The model learns by predicting the next token. Given "The cat sat on the", it learns to predict "mat". Do this billions of times across terabytes of text, and the model develops surprisingly sophisticated language understanding. That's pretraining.

The challenge is scale. A 30B parameter model doesn't fit on a single GPU. The training dataset, [SlimPajama](https://huggingface.co/datasets/cerebras/SlimPajama-627B) in our case, is 627 billion tokens. Training runs last for days or even weeks. To make this work, you need:

- **Distributed training**: Split the model across multiple GPUs using [FSDP (Fully Sharded Data Parallel)](https://docs.pytorch.org/tutorials/intermediate/FSDP_tutorial.html)
- **Data streaming**: Pull training data on-demand instead of downloading terabytes upfront
- **Checkpointing**: Save progress regularly so a failure doesn’t wipe out days of compute
- **Observability**: See what's happening inside a multi-day training run

We’ll build a Flyte pipeline that takes care of all of this, using three tasks with clearly defined responsibilities:

1. **Data preparation**: Tokenizes your dataset and converts it to MDS (MosaicML Data Shard) format for streaming. This Flyte task is cached, so it only needs to be run once and can be reused across runs.
2. **Distributed training**: Runs FSDP across 8 H200 GPUs. Flyte's `Elastic` plugin handles the distributed setup. Checkpoints upload to S3 automatically via Flyte's `File` abstraction.
3. **Real-time reporting**: Streams loss curves and training metrics to Flyte Reports, a live dashboard integrated into the Flyte UI.

Why three separate tasks? Flyte makes this separation efficient:

- **Caching**: The data preparation step runs once. On subsequent runs, Flyte skips it entirely.
- **Resource isolation**: Training uses expensive H200 GPUs only while actively training, while the driver runs on inexpensive CPU instances.
- **Fault boundaries**: If training fails, the data preparation step does not re-run. Training can resume directly from the most recent checkpoint.

## Implementation

Let's walk through the code. We'll start with the infrastructure setup, build the model, then wire everything together into a pipeline.

### Setting up the environment

Every distributed training job needs a consistent environment across all nodes. Flyte handles this with container images:

```
import logging
import math
import os
from pathlib import Path
from typing import Optional

import flyte
import flyte.report
import lightning as L
import numpy as np
import torch
import torch.nn as nn
from flyte.io import Dir, File
from flyteplugins.pytorch.task import Elastic
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/pretraining/train.py*

The imports tell the story: `flyte` for orchestration, `flyte.report` for live dashboards, `lightning` for training loop management, and `Elastic` from Flyte's PyTorch plugin. This last one is key as it configures PyTorch's distributed launch without you writing any distributed setup code.

```
NUM_NODES = 1
DEVICES_PER_NODE = 8
VOCAB_SIZE = (
    50257  # GPT-2 BPE tokenizer vocabulary size (constant across all model sizes)
)
N_POSITIONS = 2048  # Maximum sequence length (constant across all model sizes)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/pretraining/train.py*

These constants define the distributed topology. We're using 1 node with 8 GPUs, but you can scale this up by changing `NUM_NODES`. The vocabulary size (50,257 tokens) and sequence length (2,048 tokens) match GPT-2's [Byte Pair Encoding (BPE) tokenizer](https://huggingface.co/learn/llm-course/en/chapter6/5).

```
image = flyte.Image.from_debian_base(
    name="distributed_training_h200"
).with_pip_packages(
    "transformers==4.57.3",
    "datasets==4.4.1",
    "tokenizers==0.22.1",
    "huggingface-hub==0.34.0",
    "mosaicml-streaming>=0.7.0",
    "pyarrow==22.0.0",
    "flyteplugins-pytorch>=2.0.0b33",
    "torch==2.9.1",
    "lightning==2.5.6",
    "tensorboard==2.20.0",
    "sentencepiece==0.2.1",
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/pretraining/train.py*

Flyte builds this container automatically when the pipeline is run. All dependencies required for distributed training, including PyTorch, Lightning, the streaming library, and NCCL for GPU communication, are baked in. There's no Dockerfile to maintain and no "works on my machine" debugging.

### Declaring resource requirements

Different parts of the pipeline need different resources. Data tokenization needs CPU and memory. Training needs GPUs. The driver just coordinates. Flyte's `TaskEnvironment` lets you declare exactly what each task needs:

```
data_loading_env = flyte.TaskEnvironment(
    name="data_loading_h200",
    image=image,
    resources=flyte.Resources(cpu=5, memory="28Gi", disk="100Gi"),
    env_vars={
        "HF_DATASETS_CACHE": "/tmp/hf_cache",  # Cache directory for datasets
        "TOKENIZERS_PARALLELISM": "true",  # Enable parallel tokenization
    },
    cache="auto",
)

distributed_llm_training_env = flyte.TaskEnvironment(
    name="distributed_llm_training_h200",
    image=image,
    resources=flyte.Resources(
        cpu=64,
        memory="512Gi",
        gpu=f"H200:{DEVICES_PER_NODE}",
        disk="1Ti",
        shm="16Gi",  # Explicit shared memory for NCCL communication
    ),
    plugin_config=Elastic(nnodes=NUM_NODES, nproc_per_node=DEVICES_PER_NODE),
    env_vars={
        "TORCH_DISTRIBUTED_DEBUG": "INFO",
        "NCCL_DEBUG": "WARN",
    },
    cache="auto",
)

driver_env = flyte.TaskEnvironment(
    name="llm_training_driver",
    image=image,
    resources=flyte.Resources(cpu=2, memory="4Gi"),
    cache="auto",
    depends_on=[data_loading_env, distributed_llm_training_env],
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/pretraining/train.py*

Let's break down the training environment, since this is where most of the complexity lives:

- **`gpu=f"H200:{DEVICES_PER_NODE}"`**: Flyte provisions exactly 8 H200 GPUs. These have 141GB of memory each, enough to train 30B+ parameter models with FSDP.
- **`shm="16Gi"`**: This allocates explicit shared memory. NCCL (NVIDIA's communication library) uses shared memory for inter-GPU communication on the same node. Without this, you'll see cryptic errors like "NCCL error: unhandled system error", which can be difficult to debug.
- **`Elastic(nnodes=NUM_NODES, nproc_per_node=DEVICES_PER_NODE)`**: This is Flyte's integration with PyTorch's elastic launch. It handles process spawning (one process per GPU), rank assignment (each process knows its ID), and environment setup (master address, world size). This replaces the boilerplate typically written in shell scripts.

The `driver_env` is intentionally lightweight, using 2 CPUs and 4 GB of memory. Its role is limited to orchestrating tasks and passing data between them, so allocating GPUs here would be unnecessary.

### Model configurations

Training a 1.5B model uses different hyperparameters than training a 65B model. Rather than hardcoding values, we define presets:

```
MODEL_CONFIGS = {
    "1.5B": {
        "n_embd": 2048,
        "n_layer": 24,
        "n_head": 16,
        "batch_size": 8,
        "learning_rate": 6e-4,
        "checkpoint_every_n_steps": 10,
        "report_every_n_steps": 5,
        "val_check_interval": 100,
    },  # Good for testing and debugging
    "30B": {
        "n_embd": 6656,
        "n_layer": 48,
        "n_head": 52,
        "batch_size": 1,
        "learning_rate": 1.6e-4,
        "checkpoint_every_n_steps": 7500,
        "report_every_n_steps": 200,
        "val_check_interval": 1000,
    },
    "65B": {
        "n_embd": 8192,
        "n_layer": 80,
        "n_head": 64,
        "batch_size": 1,
        "learning_rate": 1.5e-4,
        "checkpoint_every_n_steps": 10000,
        "report_every_n_steps": 250,
        "val_check_interval": 2000,
    },
}

def get_model_config(model_size: str) -> dict:
    if model_size not in MODEL_CONFIGS:
        available = ", ".join(MODEL_CONFIGS.keys())
        raise ValueError(f"Unknown model size: {model_size}. Available: {available}")

    return MODEL_CONFIGS[model_size]
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/pretraining/train.py*

A few things to notice:

- **Batch size decreases with model size**: For a fixed GPU memory budget, larger models consume more memory for parameters, optimizer state, and activations, leaving less room for per-GPU batch size. For example, a 1.5B parameter model may fit a batch size of 8 per GPU, while a 65B model may only fit a batch size of 1. This is typically compensated for using gradient accumulation to maintain a larger effective batch size.
- **Learning rate decreases with model size**: Larger models are more sensitive to optimization instability and typically require lower learning rates. The values here follow empirical best practices used in large-scale language model training, informed by work such as the [Chinchilla study](https://arxiv.org/pdf/2203.15556) on compute-optimal scaling.
- **Checkpoint frequency increases with model size**: Checkpointing a 65B model is expensive (the checkpoint is huge). We do it less often but make sure we don't lose too much progress if something fails.

The 1.5B config is good for testing your setup before committing to a serious training run.

### Building the GPT model

Now for the model itself. We're building a GPT-2 style decoder-only transformer from scratch.

First, the configuration class:

```
class GPTConfig:
    """Configuration for GPT model."""

    def __init__(
        self,
        vocab_size: int = VOCAB_SIZE,
        n_positions: int = N_POSITIONS,
        n_embd: int = 2048,
        n_layer: int = 24,
        n_head: int = 16,
        n_inner: Optional[int] = None,
        activation_function: str = "gelu_new",
        dropout: float = 0.1,
        layer_norm_epsilon: float = 1e-5,
    ):
        self.vocab_size = vocab_size
        self.n_positions = n_positions
        self.n_embd = n_embd
        self.n_layer = n_layer
        self.n_head = n_head
        self.n_inner = n_inner if n_inner is not None else 4 * n_embd
        self.activation_function = activation_function
        self.dropout = dropout
        self.layer_norm_epsilon = layer_norm_epsilon
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/pretraining/train.py*

The key architectural parameters:

- **`n_embd`**: The hidden (embedding) dimension. Larger values increase model capacity but also increase memory and compute requirements.
- **`n_layer`**: The number of transformer blocks. Model depth strongly influences expressiveness and performance.
- **`n_head`**: The number of attention heads. Each head can attend to different patterns or relationships in the input.
- **`n_inner`**: The hidden dimension of the feed-forward network (MLP), typically set to 4x the embedding dimension.

Next, we define a single transformer block:

```
class GPTBlock(nn.Module):
    """Transformer block with causal self-attention."""

    def __init__(self, config: GPTConfig):
        super().__init__()
        self.ln_1 = nn.LayerNorm(config.n_embd, eps=config.layer_norm_epsilon)
        self.attn = nn.MultiheadAttention(
            config.n_embd,
            config.n_head,
            dropout=config.dropout,
            batch_first=True,
        )
        self.ln_2 = nn.LayerNorm(config.n_embd, eps=config.layer_norm_epsilon)

        # Get activation function from config
        ACT_FNS = {
            "gelu": nn.GELU(),
            "gelu_new": nn.GELU(approximate="tanh"),  # GPT-2 uses approximate GELU
            "relu": nn.ReLU(),
            "silu": nn.SiLU(),
            "swish": nn.SiLU(),  # SiLU = Swish
        }
        act_fn = ACT_FNS.get(config.activation_function, nn.GELU())

        self.mlp = nn.Sequential(
            nn.Linear(config.n_embd, config.n_inner),
            act_fn,
            nn.Linear(config.n_inner, config.n_embd),
            nn.Dropout(config.dropout),
        )

    def forward(self, x, causal_mask, key_padding_mask=None):
        x_normed = self.ln_1(x)

        # Self-attention with causal and padding masks
        attn_output, _ = self.attn(
            x_normed,  # query
            x_normed,  # key
            x_normed,  # value
            attn_mask=causal_mask,  # Causal mask: (seq_len, seq_len)
            key_padding_mask=key_padding_mask,  # Padding mask: (batch, seq_len)
            need_weights=False,
        )
        x = x + attn_output

        # MLP with residual
        x = x + self.mlp(self.ln_2(x))
        return x
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/pretraining/train.py*

Each block has two sub-layers: causal self-attention and a feed-forward MLP. The causal mask ensures the model can only attend to previous tokens in the sequence, so it can't "cheat" by looking at the answer. This is what makes it *autoregressive*.

The full `GPTModel` class (see the complete code) stacks these blocks and adds token and positional embeddings. One important detail is that the input token embedding matrix is shared with the output projection layer (often called [weight tying](https://mbrenndoerfer.com/writing/weight-tying-shared-embeddings-transformers)). This reduces the number of parameters by roughly 50 million for typical vocabulary sizes and often leads to better generalization and more stable training.

### The Lightning training module

PyTorch Lightning handles the training loop boilerplate. We wrap our model in a `LightningModule` that defines how to train it:

```
class GPTPreTrainingModule(L.LightningModule):
    """PyTorch Lightning module for GPT pre-training."""

    def __init__(
        self,
        vocab_size: int = 50257,
        n_positions: int = 2048,
        n_embd: int = 2048,
        n_layer: int = 24,
        n_head: int = 16,
        learning_rate: float = 6e-4,
        weight_decay: float = 0.1,
        warmup_steps: int = 2000,
        max_steps: int = 100000,
    ):
        super().__init__()
        self.save_hyperparameters()

        config = GPTConfig(
            vocab_size=vocab_size,
            n_positions=n_positions,
            n_embd=n_embd,
            n_layer=n_layer,
            n_head=n_head,
        )
        self.model = GPTModel(config)

    def forward(self, input_ids, attention_mask=None):
        return self.model(input_ids, attention_mask)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/pretraining/train.py*

The `save_hyperparameters()` call is important because it stores all constructor arguments in the checkpoint. This allows the model to be reloaded later without having to manually reconstruct the original configuration.

The training and validation steps implement standard causal language modeling, where the model is trained to predict the next token given all previous tokens in the sequence.

```
    def training_step(self, batch, _batch_idx):
        # Convert int32 to int64 (long) - MDS stores as int32 but PyTorch expects long
        input_ids = batch["input_ids"].long()
        labels = batch["labels"].long()

        # Get attention mask if present (optional, for padded sequences)
        # attention_mask: 1 = real token, 0 = padding
        # Note: Current data pipeline creates fixed-length sequences without padding,
        # so attention_mask is not present. If using padded sequences, ensure:
        #   - Padded positions in labels are set to -100 (ignored by cross_entropy)
        #   - attention_mask marks real tokens (1) vs padding (0)
        attention_mask = batch.get("attention_mask", None)

        # Forward pass (causal mask is created internally in GPTModel)
        logits = self(input_ids, attention_mask=attention_mask)

        # Shift logits and labels for causal language modeling
        # Before shift: labels[i] = input_ids[i]
        # After shift: predict input_ids[i+1] from input_ids[:i+1]
        shift_logits = logits[..., :-1, :].contiguous()
        shift_labels = labels[..., 1:].contiguous()

        # Calculate loss
        loss = nn.functional.cross_entropy(
            shift_logits.view(-1, shift_logits.size(-1)),
            shift_labels.view(-1),
            ignore_index=-100,
        )

        # Log loss
        self.log(
            "train/loss",
            loss,
            on_step=True,
            on_epoch=True,
            prog_bar=True,
            sync_dist=True,
        )

        # Calculate and log perplexity only on epoch (exp is costly, less frequent is fine)
        perplexity = torch.exp(torch.clamp(loss, max=20.0))
        self.log(
            "train/perplexity",
            perplexity,
            on_step=False,
            on_epoch=True,
            prog_bar=True,
            sync_dist=True,
        )

        return loss

    def validation_step(self, batch, _batch_idx):
        # Convert int32 to int64 (long) - MDS stores as int32 but PyTorch expects long
        input_ids = batch["input_ids"].long()
        labels = batch["labels"].long()

        # Get attention mask if present (optional, for padded sequences)
        attention_mask = batch.get("attention_mask", None)

        # Forward pass (causal mask is created internally in GPTModel)
        logits = self(input_ids, attention_mask=attention_mask)

        # Shift logits and labels
        shift_logits = logits[..., :-1, :].contiguous()
        shift_labels = labels[..., 1:].contiguous()

        # Calculate loss
        loss = nn.functional.cross_entropy(
            shift_logits.view(-1, shift_logits.size(-1)),
            shift_labels.view(-1),
            ignore_index=-100,
        )

        # Log loss
        self.log("val/loss", loss, prog_bar=True, sync_dist=True)

        # Calculate and log perplexity (exp is costly, but validation is infrequent so OK)
        perplexity = torch.exp(torch.clamp(loss, max=20.0))
        self.log("val/perplexity", perplexity, prog_bar=True, sync_dist=True)

        return loss
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/pretraining/train.py*

The model performs a forward pass with a causal (autoregressive) mask created internally, ensuring each token can only attend to earlier positions. To align predictions with targets, the logits and labels are shifted so that the representation at position `i` is used to predict token `i + 1`.

Loss is computed using cross-entropy over the shifted logits and labels. Training loss and perplexity are logged during execution, with metrics synchronized across distributed workers.

The optimizer setup is where a lot of training stability comes from:

```
    def configure_optimizers(self):
        # Separate parameters into weight decay and no weight decay groups
        decay_params = []
        no_decay_params = []

        for param in self.model.parameters():
            if param.requires_grad:
                # 1D parameters (biases, LayerNorm) don't get weight decay
                # 2D+ parameters (weight matrices) get weight decay
                if param.ndim == 1:
                    no_decay_params.append(param)
                else:
                    decay_params.append(param)

        optimizer_grouped_parameters = [
            {"params": decay_params, "weight_decay": self.hparams.weight_decay},
            {"params": no_decay_params, "weight_decay": 0.0},
        ]

        # AdamW optimizer
        optimizer = torch.optim.AdamW(
            optimizer_grouped_parameters,
            lr=self.hparams.learning_rate,
            betas=(0.9, 0.95),
            eps=1e-8,
        )

        # Learning rate scheduler: warmup + cosine decay
        # Warmup: linear increase from 0 to 1.0 over warmup_steps
        # Decay: cosine decay from 1.0 to 0.0 over remaining steps
        def lr_lambda(current_step):
            if current_step < self.hparams.warmup_steps:
                # Linear warmup
                return float(current_step) / float(max(1, self.hparams.warmup_steps))

            # Cosine decay after warmup
            progress = (current_step - self.hparams.warmup_steps) / max(
                1, self.hparams.max_steps - self.hparams.warmup_steps
            )
            # Cosine annealing from 1.0 to 0.0 (returns float, not tensor)
            return 0.5 * (1.0 + math.cos(progress * math.pi))

        scheduler = torch.optim.lr_scheduler.LambdaLR(optimizer, lr_lambda)

        return {
            "optimizer": optimizer,
            "lr_scheduler": {
                "scheduler": scheduler,
                "interval": "step",
            },
        }
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/pretraining/train.py*

Two important choices here:

1. **Separate weight decay groups**: We only apply weight decay to the weight matrices, not to biases or LayerNorm parameters. This follows the original BERT paper and is now standard practice, as regularizing biases and normalization parameters does not improve performance and can be harmful.
2. **Cosine learning rate schedule with warmup**: We start with a low learning rate, ramp up linearly during warmup (helps stabilize early training when gradients are noisy), then decay following a cosine curve. This schedule outperforms constant or step decay for transformer training.

### Checkpointing for fault tolerance

Training a 30B-parameter model for 15,000 steps can take days. Hardware failures and spot instance preemptions are inevitable, which makes checkpointing essential.

```
class S3CheckpointCallback(L.Callback):
    """
    Periodically upload checkpoints to S3 for durability and resumption.

    This ensures checkpoints are safely stored in remote storage even if
    the training job is interrupted or the instance fails.
    """

    def __init__(self, checkpoint_dir: Path, upload_every_n_steps: int):
        super().__init__()
        self.checkpoint_dir = checkpoint_dir
        self.upload_every_n_steps = upload_every_n_steps
        self.last_uploaded_step = -1

    def on_train_batch_end(self, trainer, pl_module, outputs, batch, batch_idx):
        """Upload checkpoint to S3 every N steps."""
        if trainer.global_rank != 0:
            return  # Only upload from rank 0

        current_step = trainer.global_step

        # Upload every N steps (aligns with ModelCheckpoint's every_n_train_steps)
        if (
            current_step % self.upload_every_n_steps == 0
            and current_step > self.last_uploaded_step
            and current_step > 0
        ):
            try:
                # Find the most recent checkpoint file
                checkpoint_files = list(self.checkpoint_dir.glob("*.ckpt"))
                if not checkpoint_files:
                    print("No checkpoint files found to upload")
                    return

                # Get the latest checkpoint (by modification time)
                latest_checkpoint = max(
                    checkpoint_files, key=lambda p: p.stat().st_mtime
                )

                # Upload the checkpoint file directly to S3 using File.from_local_sync
                checkpoint_file = File.from_local_sync(str(latest_checkpoint))
                print(f"Checkpoint uploaded to S3 at: {checkpoint_file.path}")

                self.last_uploaded_step = current_step
            except Exception as e:
                print(f"Warning: Failed to upload checkpoint to S3: {e}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/pretraining/train.py*

This callback runs every `N` training steps and uploads the checkpoint to durable storage. The key line is `File.from_local_sync()` which is a Flyte abstraction for uploading files. There are no blob store credentials to manage and no bucket paths to hardcode. Flyte automatically uses the storage backend configured for your cluster.

The callback only runs on rank 0. In distributed training, all 8 GPUs have identical model states (that's the point of data parallelism). Having all of them upload the same checkpoint would be wasteful and could cause race conditions.

When you restart a failed run, pass the checkpoint via `resume_checkpoint` so training resumes exactly where it left off, including the same step count, optimizer state, and learning rate schedule position.

### Real-time metrics with Flyte Reports

Multi-day training runs need observability. Is the loss decreasing? Did training diverge? Is the learning rate schedule behaving correctly? Flyte Reports let you build live dashboards directly in the UI:

```
class FlyteReportingCallback(L.Callback):
    """Custom Lightning callback to report training metrics to Flyte Report."""

    def __init__(self, report_every_n_steps: int = 100):
        super().__init__()
        self.report_every_n_steps = report_every_n_steps
        self.metrics_history = {
            "step": [],
            "train_loss": [],
            "learning_rate": [],
            "val_loss": [],
            "val_perplexity": [],
        }
        self.initialized_report = False
        self.last_logged_step = -1

    def on_train_start(self, trainer, pl_module):
        """Initialize the live dashboard on training start."""
        if trainer.global_rank == 0 and not self.initialized_report:
            self._initialize_report()
            self.initialized_report = True
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/pretraining/train.py*

The `_initialize_report` method (see complete code) creates an HTML/JavaScript dashboard with interactive charts. The callback then calls `flyte.report.log()` every `N` steps to push new metrics. The charts update in real-time so you can watch your loss curve descend while training runs.

There is no need to deploy Grafana, configure Prometheus, or keep a TensorBoard server running. Using `flyte.report.log()` is sufficient to get live training metrics directly in the Flyte UI.

![Metrics viz](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/tutorials/distributed-llm-pretraining/metrics.png)

### Streaming data at scale

Training datasets are massive. SlimPajama contains 627 billion tokens and spans hundreds of gigabytes even when compressed. Downloading the entire dataset to each training node before starting would take hours and waste storage.

Instead, we convert the data to MDS (MosaicML Data Shard) format and stream it during training:

```
@data_loading_env.task
async def load_and_prepare_streaming_dataset(
    dataset_name: str,
    dataset_config: Optional[str],
    max_length: int,
    train_split: str,
    val_split: Optional[str],
    max_train_samples: Optional[int],
    max_val_samples: Optional[int],
    shard_size_mb: int,
) -> Dir:
    """Tokenize dataset and convert to MDS format for streaming."""
    from datasets import load_dataset
    from streaming import MDSWriter
    from transformers import GPT2TokenizerFast

    output_dir = Path("/tmp/streaming_dataset")
    output_dir.mkdir(parents=True, exist_ok=True)

    tokenizer = GPT2TokenizerFast.from_pretrained("gpt2")
    tokenizer.pad_token = tokenizer.eos_token

    # MDS schema: what each sample contains
    columns = {
        "input_ids": "ndarray:int32",
        "labels": "ndarray:int32",
    }
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/pretraining/train.py*

This task does three things:

1. **Tokenizes the text** using GPT-2's BPE tokenizer
2. **Concatenates documents** into fixed-length sequences (no padding waste)
3. **Writes shards** to storage in a format optimized for streaming

The task returns a Flyte `Dir` object, which is a reference to the output location. It's not the data itself, just a pointer. When the training task receives this `Dir`, it streams shards on-demand rather than downloading everything upfront.

Flyte caches this task automatically. Run the pipeline twice with the same dataset config, and Flyte skips tokenization entirely on the second run. Change the dataset or sequence length, and it re-runs.

### Distributed training with FSDP

Now we get to the core: actually training the model across multiple GPUs. FSDP is what makes this possible for large models.

```
@distributed_llm_training_env.task(report=True)
def train_distributed_llm(
    prepared_dataset: Dir,
    resume_checkpoint: Optional[Dir],
    vocab_size: int,
    n_positions: int,
    n_embd: int,
    n_layer: int,
    n_head: int,
    batch_size: int,
    num_workers: int,
    max_steps: int,
    learning_rate: float,
    weight_decay: float,
    warmup_steps: int,
    use_fsdp: bool,
    checkpoint_upload_steps: int,
    checkpoint_every_n_steps: int,
    report_every_n_steps: int,
    val_check_interval: int,
    grad_accumulation_steps: int = 1,
) -> Optional[Dir]:
    # ... setup code ...
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/pretraining/train.py*

Notice `report=True` on the task decorator. It enables Flyte Reports for this specific task.

The training task receives the prepared dataset as a `Dir` and streams data directly from storage:

```
    # StreamingDataset streams shards from the remote Flyte storage on-demand
    # It automatically detects torch.distributed context
    # and shards data across GPUs - each rank gets different data automatically
    train_dataset = StreamingDataset(
        remote=f"{remote_path}/train",  # Remote MDS shard location
        local=str(local_cache / "train"),  # Local cache for downloaded shards
        shuffle=True,  # Shuffle samples
        shuffle_algo="naive",  # Shuffling algorithm
        batch_size=batch_size,  # Used for shuffle buffer sizing
    )

    # Create validation StreamingDataset if it exists
    val_dataset = None
    try:
        val_dataset = StreamingDataset(
            remote=f"{remote_path}/validation",
            local=str(local_cache / "validation"),
            shuffle=False,  # No shuffling for validation
            batch_size=batch_size,
        )
        print(
            f"Validation dataset initialized with streaming from: {remote_path}/validation"
        )
    except Exception as e:
        print(f"No validation dataset found: {e}")

    # Create data loaders
    # StreamingDataset handles distributed sampling internally by detecting
    # torch.distributed.get_rank() and torch.distributed.get_world_size()
    train_loader = DataLoader(
        train_dataset,
        batch_size=batch_size,
        num_workers=num_workers,
        pin_memory=True,
        persistent_workers=True,
        drop_last=True,  # Drop incomplete batches for distributed training
        collate_fn=mds_collate_fn,  # Handle read-only arrays
    )

    # Create validation loader if validation dataset exists
    val_loader = None
    if val_dataset is not None:
        val_loader = DataLoader(
            val_dataset,
            batch_size=batch_size,
            num_workers=num_workers,
            pin_memory=True,
            persistent_workers=True,
            drop_last=False,
            collate_fn=mds_collate_fn,
        )
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/pretraining/train.py*

`prepared_dataset.path` provides the remote storage path for the dataset. MosaicML's `StreamingDataset` automatically shards data across GPUs so that each rank sees different samples, without requiring a manual distributed sampler. The credentials are already in the environment because Flyte set them up.

FSDP is where the memory magic happens. Instead of each GPU holding a full copy of the model (like Distributed Data Parallel (DDP)), FSDP shards the parameters, gradients, and optimizer states across all GPUs. Each GPU only holds 1/8th of the model. When a layer needs to run, FSDP all-gathers the full parameters, runs the computation, then discards them.

```
    # Configure distributed strategy
    if use_fsdp:
        from torch.distributed.fsdp.wrap import ModuleWrapPolicy

        strategy = FSDPStrategy(
            auto_wrap_policy=ModuleWrapPolicy([GPTBlock]),
            activation_checkpointing_policy=None,
            cpu_offload=False,  # H200 has 141GB - no CPU offload needed
            state_dict_type="full",
            sharding_strategy="FULL_SHARD",
            process_group_backend="nccl",
        )
    else:
        from lightning.pytorch.strategies import DDPStrategy

        strategy = DDPStrategy(process_group_backend="nccl")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/pretraining/train.py*

We wrap at the `GPTBlock` level because each transformer block becomes an FSDP unit. This balances communication overhead (more units = more all-gathers) against memory savings (smaller units = more granular sharding).

One subtle detail: gradient clipping. With FSDP, gradients are sharded across ranks, so computing a global gradient norm would require an expensive all-reduce operation. Instead of norm-based clipping, we use value-based gradient clipping, which clamps each individual gradient element to a fixed range. This can be done independently on each rank with no coordination overhead and is commonly used for large-scale FSDP training.

```
    # Initialize trainer
    trainer = L.Trainer(
        strategy=strategy,
        accelerator="gpu",
        devices=DEVICES_PER_NODE,
        num_nodes=NUM_NODES,
        # Training configuration
        max_steps=max_steps,
        precision="bf16-mixed",  # BFloat16 for better numerical stability
        # Optimization
        gradient_clip_val=1.0,
        gradient_clip_algorithm=(
            "value" if use_fsdp else "norm"
        ),  # FSDP requires 'value', DDP can use 'norm'
        accumulate_grad_batches=grad_accumulation_steps,
        # Logging and checkpointing
        callbacks=callbacks,
        log_every_n_steps=report_every_n_steps,
        val_check_interval=val_check_interval,
        # Performance
        benchmark=True,
        deterministic=False,
        # Enable gradient checkpointing for memory efficiency
        enable_checkpointing=True,
        use_distributed_sampler=False,  # StreamingDataset handles distributed sampling
    )

    # Train the model (resume from checkpoint if provided)
    trainer.fit(model, train_loader, val_loader, ckpt_path=ckpt_path)

    # Print final results
    if trainer.global_rank == 0:
        if val_loader is not None:
            print(
                f"Final validation loss: {trainer.callback_metrics.get('val/loss', 0.0):.4f}"
            )
            print(
                f"Final validation perplexity: {trainer.callback_metrics.get('val/perplexity', 0.0):.4f}"
            )
        print(f"Checkpoints saved to: {checkpoint_dir}")

        return Dir.from_local_sync(output_dir)

    return None
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/pretraining/train.py*

The trainer configuration brings together all the pieces we've discussed:

- **`precision="bf16-mixed"`**: BFloat16 mixed precision training. BF16 has the same dynamic range as FP32 (unlike FP16), so you don't need loss scaling. This is the standard choice for modern GPU training.
- **`gradient_clip_val=1.0`**: Clips gradients to prevent exploding gradients during training. Combined with value-based clipping for FSDP compatibility.
- **`accumulate_grad_batches`**: Accumulates gradients over multiple forward passes before updating weights. This lets us hit a larger effective batch size than what fits in GPU memory.
- **`val_check_interval`**: How often to run validation. For long training runs, you don't want to validate every epoch — that would be too infrequent. Instead, validate every `N` training steps.
- **`use_distributed_sampler=False`**: We disable Lightning's built-in distributed sampler because `StreamingDataset` handles data sharding internally. Using both would cause conflicts.
- **`benchmark=True`**: Enables cuDNN autotuning. PyTorch will benchmark different convolution algorithms on the first batch and pick the fastest one for your specific input sizes.

The trainer then calls `fit()` with the model, data loaders, and optionally a checkpoint path to resume from.

### Tying it together

The pipeline task orchestrates everything:

```
@driver_env.task
async def distributed_llm_pipeline(
    model_size: str,
    dataset_name: str = "Salesforce/wikitext",
    dataset_config: str = "wikitext-103-raw-v1",
    max_length: int = 2048,
    max_train_samples: Optional[int] = 10000,
    max_val_samples: Optional[int] = 1000,
    max_steps: int = 100000,
    resume_checkpoint: Optional[Dir] = None,
    checkpoint_upload_steps: int = 1000,
    # Optional overrides (if None, uses model preset defaults)
    batch_size: Optional[int] = None,
    learning_rate: Optional[float] = None,
    use_fsdp: bool = True,
) -> Optional[Dir]:
    # Get model configuration
    model_config = get_model_config(model_size)

    # Use preset values if not overridden
    actual_batch_size = (
        batch_size if batch_size is not None else model_config["batch_size"]
    )
    actual_learning_rate = (
        learning_rate if learning_rate is not None else model_config["learning_rate"]
    )

    # Step 1: Load and prepare streaming dataset
    prepared_dataset = await load_and_prepare_streaming_dataset(
        dataset_name=dataset_name,
        dataset_config=dataset_config,
        max_length=max_length,
        train_split="train",
        val_split="validation",
        max_train_samples=max_train_samples,
        max_val_samples=max_val_samples,
        shard_size_mb=64,  # 64MB shards
    )

    # Step 2: Run distributed training
    if resume_checkpoint is not None:
        print("\nStep 2: Resuming distributed training from checkpoint...")
    else:
        print("\nStep 2: Starting distributed training from scratch...")

    target_global_batch = 256
    world_size = NUM_NODES * DEVICES_PER_NODE
    effective_per_step = world_size * actual_batch_size
    grad_accumulation_steps = max(
        1, math.ceil(target_global_batch / max(1, effective_per_step))
    )

    checkpoint_dir = train_distributed_llm(
        prepared_dataset=prepared_dataset,
        resume_checkpoint=resume_checkpoint,
        vocab_size=VOCAB_SIZE,
        n_positions=N_POSITIONS,
        n_embd=model_config["n_embd"],
        n_layer=model_config["n_layer"],
        n_head=model_config["n_head"],
        batch_size=actual_batch_size,
        num_workers=8,
        max_steps=max_steps,
        learning_rate=actual_learning_rate,
        weight_decay=0.1,
        warmup_steps=500,
        use_fsdp=use_fsdp,
        checkpoint_upload_steps=checkpoint_upload_steps,
        checkpoint_every_n_steps=model_config["checkpoint_every_n_steps"],
        report_every_n_steps=model_config["report_every_n_steps"],
        val_check_interval=model_config["val_check_interval"],
        grad_accumulation_steps=grad_accumulation_steps,
    )

    return checkpoint_dir
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/pretraining/train.py*

The flow is straightforward: load the configuration, prepare the data, and run training. Flyte automatically manages the execution graph so data preparation runs first and training waits until it completes. If data preparation is cached from a previous run, training starts immediately.

The gradient accumulation calculation is worth noting. We want a global batch size of 256 (this affects training dynamics), but each GPU can only fit a small batch. With 8 GPUs and batch size 1 each, we need 32 accumulation steps to hit 256.

## Running the pipeline

With everything defined, running is simple:

```
if __name__ == "__main__":
    flyte.init_from_config()

    run = flyte.run(
        distributed_llm_pipeline,
        model_size="30B",
        dataset_name="cerebras/SlimPajama-627B",
        dataset_config=None,
        max_length=2048,
        max_train_samples=5_000_000,
        max_val_samples=50_000,
        max_steps=15_000,
        use_fsdp=True,
        checkpoint_upload_steps=1000,
    )

    print(f"Run URL: {run.url}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/pretraining/train.py*

This configuration is designed for testing and demonstration. Notice `max_train_samples=5_000_000` — that's 5 million samples from a dataset with 627 billion tokens. A tiny fraction, enough to verify everything works without burning through compute.

For a real pretraining run, you would remove this limit by setting `max_train_samples=None`, or increase it significantly. You would also increase `max_steps` to match your compute budget, likely scale to multiple nodes by setting `NUM_NODES=4` or higher, and allocate more resources. The rest of the pipeline remains unchanged.

```bash
flyte create config --endpoint <FLYTE_OR_UNION_ENDPOINT> --project <PROJECT_NAME> --domain <DOMAIN_NAME> --builder remote
uv run train.py
```

When you run this, Flyte:

1. **Builds the container** (cached after first run)
2. **Schedules data prep** on CPU nodes
3. **Waits for data prep** (or skips if cached)
4. **Provisions H200 nodes** and launches distributed training
5. **Streams logs and metrics** to the UI in real-time

Open the Flyte UI to observe the workflow execution. The data preparation task completes first, followed by the training task spinning up. As training begins, the Flyte Reports dashboard starts plotting loss curves. If anything goes wrong, the logs are immediately available in the UI.

![Training Log](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/tutorials/distributed-llm-pretraining/logs.png)

If training fails due to an out-of-memory error, a GPU driver error, or a hardware issue, check the logs, fix the problem, and restart the run with `resume_checkpoint` pointing to the most recent checkpoint. Training resumes from where it left off. Flyte tracks the full execution history, so it is easy to see exactly what happened.

## Going further

If you've run through this tutorial, here's where to go next depending on what you're trying to do:

**You want to train on your own data.** The data prep task accepts any HuggingFace dataset with a `text` column. If your data isn't on HuggingFace, you can modify `load_and_prepare_streaming_dataset` to read from S3, local files, or any other source. The key is getting your data into MDS format. Once it's there, the streaming and sharding just works. For production training, look at SlimPajama, [RedPajama](https://huggingface.co/datasets/togethercomputer/RedPajama-Data-1T), or [The Pile](https://huggingface.co/datasets/EleutherAI/pile) as starting points.

**You want to scale to more GPUs.** Bump `NUM_NODES` and Flyte handles the rest. The main thing to watch is the effective batch size. As you add more GPUs, you may want to reduce gradient accumulation steps to keep the same global batch size, or increase them if you want to experiment with larger batches.

**Your training keeps failing.** Add `retries=3` to your task decorator for automatic retry on transient failures. This handles spot instance preemption, temporary network issues, and the occasional GPU that decides to stop working. Combined with checkpointing, you get fault-tolerant training that can survive most infrastructure hiccups. For persistent failures, the Flyte UI logs are your friend as they capture stdout/stderr from all ranks.

**You want better visibility into what's happening.** We're actively working on surfacing GPU driver logs (xid/sxid errors), memory utilization breakdowns, and NCCL communication metrics directly in the Flyte UI. If you're hitting issues that the current logs don't explain, reach out. Your feedback helps us prioritize what observability features to build next!


=== PAGE: https://www.union.ai/docs/v2/union/tutorials/qwen-vl-finetuning ===

# Fine-tuning a vision-language model with a frozen backbone

Large vision-language models like Qwen2.5-VL are remarkably capable out of the box. But adapting one to a specialized task raises an immediate question: do you really need to update 3 billion parameters?

Usually, no. The **frozen backbone pattern** is a practical alternative: keep all pretrained weights frozen and train only a small, task-specific adapter inserted before the vision encoder. The adapter learns to transform its input in a way that makes the frozen model perform well on your task without touching the underlying billions of parameters. The result is faster training, lower memory pressure, and a much smaller set of weights to store and version.

This tutorial makes that pattern concrete. We take a partially-occluded image classification task — CIFAR-10 images with random black rectangles covering 22–45% of the frame — and train a tiny Conv2d adapter to "see through" the occlusion before the frozen VLM processes it. The adapter has approximately **10,500 trainable parameters**. The backbone has 3 billion.

The machine learning is interesting, but the real focus here is on shipping a production-grade training pipeline:

- **Multi-node distributed training** across 2 nodes × 4 GPUs using PyTorch Elastic and DeepSpeed Stage 2
- **Automatic fault tolerance**: checkpoints upload to object storage after every validation epoch; if training fails, the pipeline returns the last known-good checkpoint instead of crashing
- **Live observability**: a streaming HTML dashboard in the Flyte UI updates in real-time as training runs, no separate monitoring infrastructure required
- **Cached data preparation**: dataset processing runs once and is reused across all reruns
- **Clean task isolation**: each stage runs with exactly the resources it needs, nothing more

> [!NOTE]
> Full code available [here](https://github.com/unionai/unionai-examples/tree/main/v2/tutorials/qwen_vl_frozen_backbone_finetuning).

## Overview

The pipeline has four tasks with clearly defined responsibilities:

1. **Dataset preparation** (`prepare_occlusion_dataset`): Downloads CIFAR-10, applies random occlusions, and writes image manifests as streaming JSONL files to object storage. Runs on CPU and is cached, so it only runs once regardless of how many times you rerun the pipeline with the same config.
2. **Multi-node training** (`train_qwen_adapter_multinode`): Runs PyTorch Lightning with DeepSpeed Stage 2 across 2 nodes × 4 L40s GPUs. Only the adapter trains; the 3B backbone stays frozen.
3. **Evaluation** (`evaluate_qwen_adapter`): Loads the saved adapter, runs inference on validation examples, and produces a predictions report. Runs on a single GPU.
4. **Driver** (`qwen_vl_multinode_deepspeed`): The pipeline entry point. Orchestrates the three tasks above, manages WandB initialization, handles recovery from training failures, and produces a final HTML report in the Flyte UI.

Why this separation? It mirrors how production pipelines should be structured. Data prep is cheap and deterministic so we cache it. Training is expensive and failure-prone so we isolate it with fault tolerance. Evaluation needs different hardware than training. The driver is pure coordination, so it gets minimal resources.

## Implementation

### Setting up the environment

Different tasks need different compute. Flyte's `TaskEnvironment` is how you declare exactly what each task needs.

First, define the container images. Training needs a full CUDA stack with ML libraries, driver compatibility, and DeepSpeed's build tools:

```
gpu_image = (
    flyte.Image.from_base("nvidia/cuda:12.8.0-cudnn-devel-ubuntu22.04")
    .clone(name="qwen_vl_multinode_deepspeed", python_version=(3, 13), extendable=True)
    .with_apt_packages("build-essential")
    .with_pip_packages(
        "torch==2.9.1",
        "torchvision==0.24.1",
        "lightning==2.6.1",
        "transformers==4.57.3",
        "deepspeed==0.18.8",
        "datasets==4.4.1",
        "pillow==11.3.0",
        "flyteplugins-pytorch>=2.0.11",
        "flyteplugins-jsonl>=2.0.11",
        "flyteplugins-wandb>=2.0.11",
    )
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/qwen_vl_frozen_backbone_finetuning/config.py*

`from_base` starts from the official NVIDIA CUDA image, giving you NCCL, cuDNN, and the right driver headers out of the box. `with_apt_packages("build-essential")` is required because DeepSpeed compiles CUDA kernels at first use and without build tools, it silently falls back to slower CPU implementations. The non-GPU image for data preparation and orchestration is much lighter:

```
non_gpu_image = flyte.Image.from_debian_base(
    name="qwen_vl_multinode_deepspeed_non_gpu"
).with_pip_packages(
    "flyteplugins-pytorch>=2.0.11",
    "flyteplugins-jsonl>=2.0.11",
    "flyteplugins-wandb>=2.0.11",
    "lightning==2.6.1",
    "datasets==4.4.1",
    "pillow==11.3.0",
    "torchvision==0.24.1",
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/qwen_vl_frozen_backbone_finetuning/config.py*

With images defined, each task gets its own resource declaration:

```
dataset_env = flyte.TaskEnvironment(
    name="qwen_vl_dataset_prep",
    image=non_gpu_image,
    resources=flyte.Resources(cpu=5, memory="15Gi"),
    cache="auto",
)

training_env = flyte.TaskEnvironment(
    name="qwen_vl_multinode_training",
    image=gpu_image,
    resources=flyte.Resources(
        cpu=42,
        memory="256Gi",
        gpu=f"L40s:{DEVICES_PER_NODE}",
        shm="16Gi",
    ),
    plugin_config=Elastic(nnodes=NUM_NODES, nproc_per_node=DEVICES_PER_NODE),
    secrets=[
        flyte.Secret(key="wandb_api_key", as_env_var="WANDB_API_KEY")
    ],  # TODO: update with your own secret key
    env_vars={
        "TORCH_DISTRIBUTED_DEBUG": "INFO",
        "NCCL_DEBUG": "WARN",
        "TOKENIZERS_PARALLELISM": "false",
        "CUDA_HOME": "/usr/local/cuda",
        "DS_SKIP_CUDA_CHECK": "1",
    },
)

evaluation_env = flyte.TaskEnvironment(
    name="qwen_vl_adapter_eval",
    image=gpu_image,
    resources=flyte.Resources(cpu=16, memory="64Gi", gpu="L40s:1"),
    cache="auto",
)

driver_env = flyte.TaskEnvironment(
    name="qwen_vl_multinode_driver",
    image=non_gpu_image,
    resources=flyte.Resources(cpu=2, memory="4Gi"),
    depends_on=[dataset_env, training_env, evaluation_env],
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/qwen_vl_frozen_backbone_finetuning/config.py*

A few things worth noting here:

- **`Elastic(nnodes=2, nproc_per_node=4)`**: Flyte's integration with PyTorch's elastic launch. It handles process spawning (one process per GPU), rank assignment, and distributed environment setup — master address, world size, rendezvous — without any shell scripting or manual `torchrun` invocations.
- **`shm="16Gi"`**: Shared memory is required for NCCL inter-GPU communication on the same node. Without it, you'll see cryptic errors from the communication library when training starts.
- **`cache="auto"`**: The dataset preparation task is cached by input hash. Running the pipeline twice with the same hyperparameters skips it entirely on the second run.
- **`depends_on`**: The driver task declares that each worker image must finish building before it starts, ensuring containers are ready before the driver begins orchestrating.
- **`secrets`**: The WandB API key is injected from Flyte's secret store as an environment variable. No credentials in code.

All training hyperparameters flow through a single typed dataclass:

```
@dataclass
class Config:
    model_name: str = DEFAULT_MODEL_NAME
    image_size: int = IMAGE_SIZE
    max_train_samples: int = 1024
    max_val_samples: int = 256
    epochs: int = 8
    per_device_batch_size: int = 1
    target_global_batch_size: int = 16
    learning_rate: float = 2e-4
    weight_decay: float = 1e-2
    reconstruction_loss_weight: float = 0.35
    report_every_n_steps: int = 10
    num_workers: int = 4
    max_length: int = 512
    eval_examples: int = 16
    train_occlusion_min: float = 0.22
    train_occlusion_max: float = 0.42
    eval_occlusion_min: float = 0.28
    eval_occlusion_max: float = 0.45
    seed: int = 7

    def to_dict(self) -> dict:
        return asdict(self)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/qwen_vl_frozen_backbone_finetuning/config.py*

Using a dataclass rather than scattered constants or argparse arguments means the full config is serializable, can be stored in artifact metadata alongside the model checkpoint, and flows cleanly as a typed input between tasks. The `to_dict()` method serializes it for WandB logging.

### Preparing the dataset

The dataset task handles everything: downloading CIFAR-10, generating occlusions, and writing the manifests.

```
@dataset_env.task
async def prepare_occlusion_dataset(config: Config) -> DatasetArtifacts:
    from PIL import Image
    from torchvision.datasets import CIFAR10
    from flyte.io import Dir
    from flyteplugins.jsonl import JsonlFile
    import random

    rng = random.Random(config.seed)

    images_dir = Path("/tmp/qwen_vl_occlusion_images")
    train_images_dir = images_dir / "train" / "images"
    val_images_dir = images_dir / "validation" / "images"
    train_images_dir.mkdir(parents=True, exist_ok=True)
    val_images_dir.mkdir(parents=True, exist_ok=True)

    prompt = (
        "The image may be partially occluded. "
        "Answer with exactly one CIFAR-10 class label: "
        + ", ".join(CLASS_NAMES)
        + ". What is the main object?"
    )

    async def export_split(
        dataset,
        split_name: str,
        limit: int,
        local_image_dir: Path,
        occ_min: float,
        occ_max: float,
    ):
        out = JsonlFile.new_remote(f"{split_name}_manifest.jsonl")
        async with out.writer() as writer:
            for idx in range(limit):
                pil_image, label_idx = dataset[idx]
                resized = pil_image.resize(
                    (config.image_size, config.image_size),
                    resample=Image.Resampling.BICUBIC,
                )
                rel_path = f"{split_name}/images/{split_name}-{idx:05d}.png"
                resized.save(local_image_dir / f"{split_name}-{idx:05d}.png")
                occlusion = build_occlusion_box(
                    width=config.image_size,
                    height=config.image_size,
                    rng=rng,
                    min_fraction=occ_min,
                    max_fraction=occ_max,
                )
                await writer.write(
                    {
                        "image_path": rel_path,
                        "label": CLASS_NAMES[label_idx],
                        "label_index": int(label_idx),
                        "prompt": prompt,
                        "occlusion": occlusion,
                    }
                )
        return out

    train_dataset = CIFAR10(root="/tmp/cifar10", train=True, download=True)
    val_dataset = CIFAR10(root="/tmp/cifar10", train=False, download=True)

    train_manifest = await export_split(
        train_dataset,
        "train",
        config.max_train_samples,
        train_images_dir,
        config.train_occlusion_min,
        config.train_occlusion_max,
    )
    val_manifest = await export_split(
        val_dataset,
        "validation",
        config.max_val_samples,
        val_images_dir,
        config.eval_occlusion_min,
        config.eval_occlusion_max,
    )

    return DatasetArtifacts(
        train_manifest=train_manifest,
        val_manifest=val_manifest,
        images=await Dir.from_local(str(images_dir)),
    )
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/qwen_vl_frozen_backbone_finetuning/data.py*

Each image gets a randomly-placed black rectangle. The occlusion covers 22–42% of the image area during training and 28–45% during evaluation. The occlusion is deliberately harder at eval time to test how robust the adapter is. The bounding box coordinates are written into each manifest record alongside the image path and ground-truth label, so the training task can reconstruct the binary occlusion mask as the adapter's fourth input channel.

Two Flyte primitives handle data persistence without any manual storage management:

- **`JsonlFile.new_remote()`** opens a streaming writer that writes directly to remote object storage. The training task reads records back via `jf.iter_records_sync()`, so no local file paths and S3 credentials to manage.
- **`Dir.from_local()`** uploads the local images directory to object storage and returns a typed handle. The training task downloads it to a local path via `Dir.download_sync()`.

Because `cache="auto"` is set on this task, dataset preparation runs once. Subsequent reruns with the same config skip it entirely.

### The adapter

Here's the entire trainable component of the model with `~10,500` parameters:

```
class ResidualOcclusionAdapter(nn.Module):
    def __init__(self, hidden_channels: int = 32):
        super().__init__()
        self.net = nn.Sequential(
            nn.Conv2d(4, hidden_channels, kernel_size=3, padding=1),
            nn.GELU(),
            nn.Conv2d(hidden_channels, hidden_channels, kernel_size=3, padding=1),
            nn.GELU(),
            nn.Conv2d(hidden_channels, 3, kernel_size=1),
            nn.Tanh(),
        )
        self.gate = nn.Parameter(torch.tensor(0.10))

    def forward(
        self, pixel_values: torch.Tensor, occlusion_mask: torch.Tensor
    ) -> torch.Tensor:
        if pixel_values.ndim != 4:
            raise ValueError(
                "ResidualOcclusionAdapter expects dense image tensors with shape "
                f"(B, C, H, W), but received {tuple(pixel_values.shape)}."
            )
        if occlusion_mask.ndim == 3:
            occlusion_mask = occlusion_mask.unsqueeze(1)
        adapter_input = torch.cat(
            [pixel_values, occlusion_mask.to(pixel_values.dtype)],
            dim=1,
        )
        residual = self.net(adapter_input)
        return pixel_values + torch.tanh(self.gate) * residual
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/qwen_vl_frozen_backbone_finetuning/model.py*

The adapter takes the occluded image (3 channels) concatenated with the binary occlusion mask (1 channel) as a 4-channel input. It predicts a residual correction through a small convolutional network, then adds that correction back to the original pixels. The learnable `gate` scalar, initialized to `0.10`, controls how strongly the adapter modifies the image. It starts as a near-identity transformation and gradually grows during training as the adapter gains confidence.

The adapter is plugged into Qwen2.5-VL via a Lightning module:

```
class QwenVLAdapterModule(L.LightningModule):
    def __init__(
        self,
        model_name: str,
        learning_rate: float,
        weight_decay: float,
        reconstruction_loss_weight: float,
    ):
        super().__init__()
        from transformers import Qwen2_5_VLForConditionalGeneration

        self.save_hyperparameters()
        self.adapter = ResidualOcclusionAdapter()

        self.backbone = Qwen2_5_VLForConditionalGeneration.from_pretrained(
            model_name,
            torch_dtype=torch.bfloat16,
            attn_implementation="sdpa",
        )
        self.backbone.requires_grad_(False)
        self.backbone.gradient_checkpointing_enable()

        # DeepSpeed checkpoints only persist the trainable adapter weights when
        # `exclude_frozen_parameters=True`. On resume we rebuild the frozen
        # backbone from Hugging Face and load the checkpoint non-strictly.
        self.strict_loading = False

        self.total_params, self.trainable_params = count_parameters(self)
        self.example_input_array = None
        self.vision_patch_size = int(self.backbone.config.vision_config.patch_size)
        self.temporal_patch_size = int(
            getattr(self.backbone.config.vision_config, "temporal_patch_size", 1)
        )
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/qwen_vl_frozen_backbone_finetuning/model.py*

The key line is `self.backbone.requires_grad_(False)`. This freezes all 3 billion backbone parameters which means only the adapter's ~10,500 weights receive gradients. `gradient_checkpointing_enable()` trades compute for memory: instead of keeping the frozen backbone's intermediate activations in GPU memory during the backward pass, they're recomputed on the fly. This is critical when a 3B model is sitting in GPU memory alongside your optimizer state.

`strict_loading = False` handles an important DeepSpeed checkpoint detail. When `exclude_frozen_parameters=True` is set on the strategy, DeepSpeed only saves the adapter weights in checkpoints, not the 3B frozen backbone. On resume, the checkpoint won't contain backbone weights, so loading must be non-strict. The `on_load_checkpoint` hook fills in the missing backbone weights from the freshly-loaded HuggingFace model, combining the best of both worlds: small checkpoints and a fully initialized model.

The training loss combines two objectives:

```
    def _forward_losses(
        self, batch: dict[str, torch.Tensor]
    ) -> dict[str, torch.Tensor]:
        backbone_dtype = next(self.backbone.parameters()).dtype
        if batch["pixel_values"].ndim == 2:
            if "image_grid_thw" not in batch:
                raise ValueError(
                    "Packed Qwen pixel values require `image_grid_thw` to reconstruct "
                    "dense images for the Conv2d adapter."
                )
            grid_thw = batch["image_grid_thw"]
            dense_pixels = packed_pixels_to_dense_images(
                batch["pixel_values"].to(dtype=backbone_dtype),
                grid_thw,
                patch_size=self.vision_patch_size,
                temporal_patch_size=self.temporal_patch_size,
            )
            clean_pixels = packed_pixels_to_dense_images(
                batch["clean_pixel_values"].to(dtype=backbone_dtype),
                grid_thw,
                patch_size=self.vision_patch_size,
                temporal_patch_size=self.temporal_patch_size,
            )
            adapted_dense = self.adapter(dense_pixels, batch["occlusion_mask"])
            adapted_pixels = dense_images_to_packed_pixels(
                adapted_dense,
                grid_thw,
                patch_size=self.vision_patch_size,
                temporal_patch_size=self.temporal_patch_size,
            )
        else:
            clean_pixels = batch["clean_pixel_values"].to(dtype=backbone_dtype)
            adapted_dense = self.adapter(
                batch["pixel_values"].to(dtype=backbone_dtype),
                batch["occlusion_mask"],
            )
            adapted_pixels = adapted_dense

        forward_kwargs = {
            "input_ids": batch["input_ids"],
            "attention_mask": batch["attention_mask"],
            "pixel_values": adapted_pixels,
            "labels": batch["labels"],
        }
        if "image_grid_thw" in batch:
            forward_kwargs["image_grid_thw"] = batch["image_grid_thw"]
        outputs = self.backbone(**forward_kwargs)

        clean_pixels = clean_pixels.to(
            device=adapted_pixels.device, dtype=backbone_dtype
        )
        occlusion_mask = batch["occlusion_mask"].to(
            device=adapted_pixels.device,
            dtype=backbone_dtype,
        )
        if occlusion_mask.ndim == 3:
            occlusion_mask = occlusion_mask.unsqueeze(1)
        if occlusion_mask.shape[-2:] != adapted_dense.shape[-2:]:
            occlusion_mask = F.interpolate(
                occlusion_mask,
                size=adapted_dense.shape[-2:],
                mode="nearest",
            )

        reconstruction_error = (adapted_dense - clean_pixels).abs() * occlusion_mask
        mask_denominator = (occlusion_mask.sum() * adapted_dense.shape[1]).clamp_min(
            1.0
        )

        reconstruction_loss = reconstruction_error.sum() / mask_denominator
        total_loss = (
            outputs.loss + self.hparams.reconstruction_loss_weight * reconstruction_loss
        )

        return {
            "total_loss": total_loss,
            "lm_loss": outputs.loss,
            "reconstruction_loss": reconstruction_loss,
        }
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/qwen_vl_frozen_backbone_finetuning/model.py*

The **language modeling loss** (cross-entropy on the predicted class label tokens) drives the model to produce correct answers. The **reconstruction loss** (mean absolute error between the adapter's output and the clean image, computed only in the occluded region) pushes the adapter to actually restore the missing pixels rather than finding a representation shortcut. Without it, the adapter could overfit the frozen backbone's quirks and produce correct tokens while generating noise in the masked region. The `reconstruction_loss_weight` (default `0.35`) balances these two objectives.

Because Qwen2.5-VL's preprocessor packs image patches into a flat `(num_patches, patch_dim)` tensor, the adapter must unpack this into a spatial `(B, C, H, W)` tensor, apply the convolutions, then repack. The `packed_pixels_to_dense_images` and `dense_images_to_packed_pixels` utilities in `model.py` handle this format conversion transparently.

### Multi-node training with DeepSpeed

The training task is a standard PyTorch Lightning training loop with distributed infrastructure handled by Flyte and DeepSpeed:

CODE6

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/qwen_vl_frozen_backbone_finetuning/tasks.py*

The `@wandb_init` decorator integrates with the `wandb_config` context created in the driver task. It retrieves the initialized WandB run and attaches a `WandbLogger` to the trainer. The `report=True` flag on the task decorator enables Flyte Reports for live dashboard streaming from this task.

![Live Training](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/tutorials/qwen-vl-finetuning/live_training_graph.png)
![Live Training Contd](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/tutorials/qwen-vl-finetuning/losses.png)

DeepSpeed Stage 2 shards optimizer states and gradients across GPUs, reducing per-GPU memory usage significantly. The critical configuration flag here is `exclude_frozen_parameters=True`:

CODE7

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/qwen_vl_frozen_backbone_finetuning/tasks.py*

Without `exclude_frozen_parameters=True`, DeepSpeed would shard and checkpoint the frozen backbone weights too, producing enormous checkpoint files, slow checkpoint saves, and unnecessary communication overhead. With it, only the adapter participates in sharding and checkpointing. The backbone is loaded independently on each worker from HuggingFace.

Gradient accumulation is computed automatically to hit the target global batch size regardless of how many GPUs are actually running:

CODE8

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/qwen_vl_frozen_backbone_finetuning/tasks.py*

With 2 nodes × 4 GPUs × per-device batch size 1, the effective per-step batch is 8. To reach the default target of 16, the trainer accumulates over 2 steps. Change `NUM_NODES` or `per_device_batch_size` and the calculation adjusts automatically.

The trainer brings everything together:

CODE9

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/qwen_vl_frozen_backbone_finetuning/tasks.py*

`precision="bf16-mixed"` uses BFloat16, which matches FP32's dynamic range (unlike FP16), so you don't need loss scaling. This is the standard choice for modern VLM training. `benchmark=True` runs cuDNN autotuning on the first batch to select the fastest kernels for your specific input sizes.

### Fault tolerance and recovery

Multi-node GPU jobs fail. Hardware hiccups, spot instance preemptions, NCCL timeouts, memory spikes, etc. and the question is when, not if. This pipeline handles it with a two-part system.

After every validation epoch, the `RecoveryArtifactCallback` calls `trainer.save_checkpoint()` to write a DeepSpeed checkpoint directory, then uploads all shard files to the recovery URI. Each node's local rank 0 uploads its own shards; global rank 0 uploads the metadata files (`metrics.json`, `summary.json`). A distributed barrier between save and upload ensures all workers finish before training continues.

If training fails, the driver task catches the error and returns the last recovery artifact instead of propagating the failure:

CODE10

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/qwen_vl_frozen_backbone_finetuning/tasks.py*

A failed run still produces useful output: the best checkpoint reached before the failure, along with a partial training report. To resume from that point, pass the recovery artifact as `resume_training_artifacts` on the next run. The training task downloads it, finds the most recent `.ckpt` file, and passes it to `trainer.fit()` as `ckpt_path`. Training picks up at the last saved epoch with optimizer state and metrics history intact.

The recovery URI is constructed from the configurable base path and the run name:

CODE11

This means each run gets its own recovery location, so you can identify exactly which run a checkpoint came from.

### Live observability

`flyte.report` lets you push HTML content directly into the Flyte UI during task execution, with no separate monitoring infrastructure. The `LiveTrainingReportCallback` uses this to stream training metrics in real-time:

CODE12

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/qwen_vl_frozen_backbone_finetuning/callbacks.py*

`on_train_start` (see the full code) initializes the dashboard with an SVG loss chart and an HTML metrics table. Every `report_every_n_steps` training steps, `_push_update` serializes the latest metrics into a `<script>` block and calls `flyte.report.log()` to append it to the live page. The JavaScript `updateQwenLiveReport()` function then updates the chart polylines and appends a new table row for each step.

For resumed runs, the prior metrics history is seeded into the table on `on_train_start`, so the metrics view is continuous across runs rather than restarting from zero.

![Recovery](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/tutorials/qwen-vl-finetuning/recovery.png)

WandB metrics are logged in parallel by `AdapterMetricsCallback` after each validation epoch, including per-epoch train and validation losses, the LM loss component, the reconstruction loss component, and the current adapter gate value.

![WandB](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/tutorials/qwen-vl-finetuning/wandb.png)

### Evaluation

After training completes, a separate task runs inference on a single GPU:

CODE13

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/qwen_vl_frozen_backbone_finetuning/tasks.py*

The task is async so the driver can `asyncio.gather` the downloads of training artifacts and images in parallel rather than sequentially, a simple speedup that matters when downloading hundreds of megabytes from object storage.

The evaluation task loads the adapter state dict from `adapter_artifact.pt`, rebuilds the frozen backbone fresh from HuggingFace (there's no need to checkpoint 3B weights, only the ~10,500 adapter weights travel with the artifact), and runs greedy decoding on each validation example. The metric is exact-match accuracy between the model's predicted class token and the ground-truth CIFAR-10 label.

### Putting it all together

The driver task is the pipeline entry point that all other tasks flow through:

CODE14

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/qwen_vl_frozen_backbone_finetuning/tasks.py*

The driver constructs the recovery URI from `checkpoint_base_uri` and the current run name, prepares the dataset (or retrieves it from cache), then executes training inside a `wandb_config` context. The `wandb_config` context manager creates and registers a WandB run; the `@wandb_init` decorator on the training task retrieves it, updates it with the full `Config` dataclass, and attaches a `WandbLogger`. Neither the training task nor the callbacks need any WandB initialization code of their own.

The recovery handler (shown in the previous section) wraps the training call. If training succeeds, evaluation runs next. The driver then downloads both the training and evaluation artifacts concurrently and assembles a final HTML report with training curves, evaluation summary, per-epoch metrics table, and sample prediction cards with the actual occluded images, which is pushed to Flyte Reports.

## Running the tutorial

Before running, update two placeholders in `config.py`:

- `DEFAULT_CHECKPOINT_BASE_URI`: your S3, GCS, or Azure Blob URI for checkpoint storage
- The `wandb_api_key` secret key name to match your cluster's secret store configuration

Then configure and launch:

CODE15

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/qwen_vl_frozen_backbone_finetuning/train.py*

CODE16

When you run this, the pipeline:

1. **Builds containers** once and caches them for subsequent runs
2. **Prepares the dataset**: downloads CIFAR-10, generates occlusions, writes JSONL manifests; cached on subsequent runs with the same config
3. **Launches multi-node training**: provisions 2 × 4 L40s GPUs and starts the Elastic job
4. **Streams metrics to the live dashboard**: the Flyte Reports view starts updating as soon as the first step logs
5. **Runs evaluation**: a single-GPU task loads the adapter and runs inference, computing exact-match accuracy
6. **Generates the final report**: training curves, evaluation summary, and sample prediction cards appear in the Flyte UI

![Final Report](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/tutorials/qwen-vl-finetuning/final_report.png)
![Predictions](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/tutorials/qwen-vl-finetuning/predictions.png)

To resume a failed or interrupted run, uncomment the `resume_training_artifacts` line in `train.py` and point it to the recovery URI from the previous run. Training picks up from the last checkpoint with metrics history intact.

## Going further

**Adapting this to a different task.** The frozen backbone pattern transfers directly. Replace `QwenOcclusionDataset` and `prepare_occlusion_dataset` with your own data, update the prompt template, and adjust the dual loss if a pixel-level reconstruction term doesn't apply to your task. The multi-node Elastic setup, DeepSpeed Stage 2 config, recovery system, and live reporting are completely reusable.

**Using a larger Qwen model.** Change `DEFAULT_MODEL_NAME` to `Qwen/Qwen2.5-VL-7B-Instruct` or a larger variant. You may need to increase `memory` in `training_env` and reduce `per_device_batch_size`. The frozen backbone + adapter pattern becomes more valuable at larger scales where you're always training the same ~10,500-parameter adapter regardless of backbone size.

**Training keeps failing.** Add `retries=3` to the `@training_env.task` decorator. With the recovery callback uploading checkpoints after every validation epoch, Flyte automatically restarts training from the last checkpoint on transient failures. Spot instance preemptions and most hardware hiccups become non-events.

**Scaling to more nodes.** Increase `NUM_NODES` in `config.py`. The Elastic plugin, DeepSpeed strategy, and gradient accumulation calculation all adapt automatically. The recovery system is unchanged as each run still gets its own recovery URI.


=== PAGE: https://www.union.ai/docs/v2/union/tutorials/climate-modeling ===

# GPU-accelerated climate modeling

Climate modeling is hard for two reasons: data and compute. Satellite imagery arrives continuously from multiple sources. Reanalysis datasets have to be pulled from remote APIs. Weather station data shows up in different formats and schemas. And once all of that is finally in one place, running atmospheric physics simulations demands serious GPU compute.

In practice, many climate workflows are held together with scripts, cron jobs, and a lot of manual babysitting. Data ingestion breaks without warning. GPU jobs run overnight with little visibility into what's happening. When something interesting shows up in a simulation, like a developing hurricane, no one notices until the job finishes hours later.

In this tutorial, we build a production-grade climate modeling pipeline using Flyte. We ingest data from three different sources in parallel, combine it with Dask, run ensemble atmospheric simulations on H200 GPUs, detect extreme weather events as they emerge, and visualize everything in a live dashboard. The entire pipeline is orchestrated, cached, and fault-tolerant, so it can run reliably at scale.

![Report](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/tutorials/climate-modeling/report.png)

> [!NOTE]
> Full code available [here](https://github.com/unionai/unionai-examples/tree/main/v2/tutorials/climate_modeling/simulation.py).

## Overview

We're building an ensemble weather forecasting system. Ensemble forecasting runs the same simulation multiple times with slightly different initial conditions. This quantifies forecast uncertainty. Instead of saying "the temperature will be 25°C", we can say "the temperature will be 24-26°C with 90% confidence".

The pipeline has five stages:

1. **Data ingestion**: Pull satellite imagery from NOAA GOES, reanalysis data from ERA5, and surface observations from weather stations in parallel.
2. **Preprocessing**: Fuse the datasets, interpolate to a common grid, and run quality control using Dask for distributed computation.
3. **GPU simulation**: Run ensemble atmospheric physics on H200 GPUs. Each ensemble member evolves independently. PyTorch handles the tensor operations; `torch.compile` optimizes the kernels.
4. **Event detection**: Monitor for hurricanes (high wind + low pressure) and heatwaves during simulation. When extreme events are detected, the pipeline can adaptively refine the grid resolution.
5. **Real-time reporting**: Stream metrics to a live Flyte Reports dashboard showing convergence and detected events.

This workflow is a good example of where Flyte shines!

- **Parallel data ingestion**: Three different data sources, three different APIs, all running concurrently. Flyte's async task execution handles this naturally.
- **Resource heterogeneity**: Data ingestion needs CPU and network. Preprocessing needs a Dask cluster. Simulation needs GPUs. Flyte provisions exactly what each stage needs.
- **Caching**: ERA5 data fetches can take minutes. Run the pipeline twice with the same date range, and Flyte skips the fetch entirely.
- **Adaptive workflows**: When a hurricane is detected, we can dynamically refine the simulation. Flyte makes this kind of conditional logic straightforward.

## Implementation

### Dependencies and container image

```
import asyncio
import gc
import io
import json
import os
import tempfile
from dataclasses import dataclass
from datetime import datetime, timedelta
from typing import Literal

import flyte
import numpy as np
import pandas as pd
import xarray as xr
from flyte.io import File
from flyteplugins.dask import Dask, Scheduler, WorkerGroup
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/climate_modeling/simulation.py*

The key imports include `xarray` for multi-dimensional climate data, `flyteplugins.dask` for distributed preprocessing, and `flyte` for orchestration.

```
climate_image = (
    flyte.Image.from_debian_base(name="climate_modeling_h200")
    .with_apt_packages(
        "libnetcdf-dev",  # NetCDF for climate data
        "libhdf5-dev",  # HDF5 for large datasets
        "libeccodes-dev",  # GRIB format support (ECMWF's native format)
        "libudunits2-dev",  # Unit conversions
    )
    .with_pip_packages(
        "numpy==2.3.5",
        "pandas==2.3.3",
        "xarray==2025.11.0",
        "torch==2.9.1",
        "netCDF4==1.7.3",
        "s3fs==2025.10.0",
        "aiohttp==3.13.2",
        "ecmwf-datastores-client==0.4.1",
        "h5netcdf==1.7.3",
        "cfgrib==0.9.15.1",
        "pyarrow==22.0.0",
        "scipy==1.15.1",
        "flyteplugins-dask>=2.0.0b33",
        "nvidia-ml-py3==7.352.0",
    )
    .with_env_vars({"PYTORCH_CUDA_ALLOC_CONF": "max_split_size_mb:512"})
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/climate_modeling/simulation.py*

Climate data comes in specialized formats such as NetCDF, HDF5, and GRIB. The container image includes libraries to work with all of them, along with PyTorch for GPU computation and the ECMWF client for accessing ERA5 data.

### Simulation parameters and data structures

```
@dataclass
class SimulationParams:
    grid_resolution_km: float = 10.0
    time_step_minutes: int = 10
    simulation_hours: int = 240
    physics_model: Literal["WRF", "MPAS", "CAM"] = "WRF"
    boundary_layer_scheme: str = "YSU"
    microphysics_scheme: str = "Thompson"
    radiation_scheme: str = "RRTMG"

    # Ensemble forecasting parameters
    ensemble_size: int = 800
    perturbation_magnitude: float = 0.5

    # Convergence criteria for adaptive refinement
    convergence_threshold: float = 0.1  # 10% of initial ensemble spread
    max_iterations: int = 3

@dataclass
class ClimateMetrics:
    timestamp: str
    iteration: int
    convergence_rate: float
    energy_conservation_error: float
    max_wind_speed_mps: float
    min_pressure_mb: float
    detected_phenomena: list[str]
    compute_time_seconds: float
    ensemble_spread: float

@dataclass
class SimulationSummary:
    total_iterations: int
    final_resolution_km: float
    avg_convergence_rate: float
    total_compute_time_seconds: float
    hurricanes_detected: int
    heatwaves_detected: int
    converged: bool
    region: str
    output_files: list[File]
    date_range: list[str, str]
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/climate_modeling/simulation.py*

`SimulationParams` defines the core behavior of the simulation, including grid resolution, physics schemes, and ensemble size. The default configuration runs 800 ensemble members, which is sufficient to produce statistically meaningful uncertainty estimates.

> [!NOTE]
> Decreasing the grid spacing via `grid_resolution_km` (for example, from 10 km to 5 km) increases grid resolution and significantly increases memory usage because it introduces more data points and intermediate state. Even with 141 GB of H200 GPU memory, high-resolution or adaptively refined simulations may exceed available VRAM, especially when running large ensembles.
>
> To mitigate this, consider reducing the ensemble size, limiting the refined region, running fewer physics variables, or scaling the simulation across more GPUs so memory is distributed more evenly.

`ClimateMetrics` collects diagnostics at each iteration, such as convergence rate, energy conservation, and detected phenomena. These metrics are streamed to the real-time dashboard so you can monitor how the simulation evolves as it runs.

### Task environments

Different stages need different resources. Flyte's `TaskEnvironment` declares exactly what each task requires:

```
gpu_env = flyte.TaskEnvironment(
    name="climate_modeling_gpu",
    resources=flyte.Resources(
        cpu=5,
        memory="130Gi",
        gpu="H200:1",
    ),
    image=climate_image,
    cache="auto",
)

dask_env = flyte.TaskEnvironment(
    name="climate_modeling_dask",
    plugin_config=Dask(
        scheduler=Scheduler(resources=flyte.Resources(cpu=2, memory="6Gi")),
        workers=WorkerGroup(
            number_of_workers=2,
            resources=flyte.Resources(cpu=2, memory="12Gi"),
        ),
    ),
    image=climate_image,
    resources=flyte.Resources(cpu=2, memory="12Gi"),  # Head node
    cache="auto",
)

cpu_env = flyte.TaskEnvironment(
    name="climate_modeling_cpu",
    resources=flyte.Resources(cpu=8, memory="64Gi"),
    image=climate_image,
    cache="auto",
    secrets=[
        flyte.Secret(key="cds_api_key", as_env_var="ECMWF_DATASTORES_KEY"),
        flyte.Secret(key="cds_api_url", as_env_var="ECMWF_DATASTORES_URL"),
    ],
    depends_on=[gpu_env, dask_env],
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/climate_modeling/simulation.py*

Here’s what each environment is responsible for:

- **`gpu_env`**: Runs the atmospheric simulations on H200 GPUs. The 130 GB of GPU memory is used to hold the ensemble members in VRAM during execution.
- **`dask_env`**: Provides a distributed Dask cluster for preprocessing. A scheduler and multiple workers handle data fusion and transformation in parallel.
- **`cpu_env`**: Handles data ingestion and orchestration. This environment also includes the secrets required to access the ERA5 API.

The `depends_on` setting on `cpu_env` ensures that Flyte builds the GPU and Dask images first. Once those environments are ready, the orchestration task can launch the specialized simulation and preprocessing tasks.

### Data ingestion: multiple sources in parallel

Climate models need data from multiple sources. Each source has different formats, APIs, and failure modes. We handle them as separate Flyte tasks that run concurrently.

**Satellite imagery from NOAA GOES**

```
@cpu_env.task
async def ingest_satellite_data(region: str, date_range: list[str, str]) -> File:
    """Ingest GOES satellite imagery from NOAA's public S3 buckets."""
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/climate_modeling/simulation.py*

This task fetches cloud imagery and precipitable water products from NOAA's public S3 buckets. GOES-16 covers the Atlantic; GOES-17 covers the Pacific. The task selects the appropriate satellite based on region, fetches multiple days in parallel using `asyncio.gather`, and combines everything into a single xarray Dataset.

**ERA5 reanalysis from Copernicus**

```
@cpu_env.task
async def ingest_reanalysis_data(region: str, date_range: list[str, str]) -> File:
    """Fetch ERA5 reanalysis from Copernicus Climate Data Store."""
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/climate_modeling/simulation.py*

ERA5 provides 3D atmospheric fields such as temperature, wind, humidity at multiple pressure levels from surface to stratosphere. The ECMWF datastores client handles authentication via Flyte secrets. Each day fetches in parallel, then gets concatenated.

**Surface observations from weather stations:**

```
@cpu_env.task
async def ingest_station_data(
    region: str, date_range: list[str, str], max_stations: int = 100
) -> File:
    """Fetch ground observations from NOAA's Integrated Surface Database."""
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/climate_modeling/simulation.py*

Ground truth comes from NOAA's Integrated Surface Database. The task filters stations by geographic bounds, fetches hourly observations, and returns a Parquet file for efficient downstream processing.

All three tasks return Flyte `File` objects that hold references to data in blob storage. No data moves until a downstream task actually needs it.

### Preprocessing with Dask

The three data sources need to be combined into a unified atmospheric state. This means:
- Interpolating to a common grid
- Handling missing values
- Merging variables from different sources
- Quality control

This is a perfect fit for Dask to handle lazy evaluation over chunked arrays:

```python
@dask_env.task
async def preprocess_atmospheric_data(
    satellite_data: File,
    reanalysis_data: File,
    station_data: File,
    target_resolution_km: float,
) -> File:
```

This task connects to the Dask cluster provisioned by Flyte, loads the datasets with appropriate chunking, merges satellite and reanalysis grids, fills in missing values, and persists the result. Flyte caches the output, so preprocessing only runs when the inputs change.

### GPU-accelerated atmospheric simulation

Now the core: running atmospheric physics on the GPU. Each ensemble member is an independent forecast with slightly perturbed initial conditions.

```
@gpu_env.task
async def run_atmospheric_simulation(
    input_data: File,
    params: SimulationParams,
    partition_id: int = 0,
    ensemble_start: int | None = None,
    ensemble_end: int | None = None,
) -> tuple[File, ClimateMetrics]:
    """Run GPU-accelerated atmospheric simulation with ensemble forecasting."""
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/climate_modeling/simulation.py*

The task accepts a subset of ensemble members (`ensemble_start` to `ensemble_end`). This enables distributing 800 members across multiple GPUs.

The physics step is the computational kernel. It runs advection (wind transport), pressure gradients, Coriolis forces, turbulent diffusion, and moisture condensation:

```
    @torch.compile(mode="reduce-overhead")
    def physics_step(state_tensor, dt_val, dx_val):
        """Compiled atmospheric physics - 3-4x faster with torch.compile."""
        # Advection: transport by wind
        temp_grad_x = torch.roll(state_tensor[:, 0], -1, dims=2) - torch.roll(
            state_tensor[:, 0], 1, dims=2
        )
        temp_grad_y = torch.roll(state_tensor[:, 0], -1, dims=3) - torch.roll(
            state_tensor[:, 0], 1, dims=3
        )
        advection = -(
            state_tensor[:, 3] * temp_grad_x + state_tensor[:, 4] * temp_grad_y
        ) / (2 * dx_val)
        state_tensor[:, 0] = state_tensor[:, 0] + advection * dt_val

        # Pressure gradient with Coriolis
        pressure_grad_x = (
            torch.roll(state_tensor[:, 1], -1, dims=2)
            - torch.roll(state_tensor[:, 1], 1, dims=2)
        ) / (2 * dx_val)
        pressure_grad_y = (
            torch.roll(state_tensor[:, 1], -1, dims=3)
            - torch.roll(state_tensor[:, 1], 1, dims=3)
        ) / (2 * dx_val)

        coriolis_param = 1e-4  # ~45°N latitude
        coriolis_u = coriolis_param * state_tensor[:, 4]
        coriolis_v = -coriolis_param * state_tensor[:, 3]

        state_tensor[:, 3] = (
            state_tensor[:, 3] - pressure_grad_x * dt_val * 0.01 + coriolis_u * dt_val
        )
        state_tensor[:, 4] = (
            state_tensor[:, 4] - pressure_grad_y * dt_val * 0.01 + coriolis_v * dt_val
        )

        # Turbulent diffusion
        diffusion_coeff = 10.0
        laplacian_temp = (
            torch.roll(state_tensor[:, 0], 1, dims=2)
            + torch.roll(state_tensor[:, 0], -1, dims=2)
            + torch.roll(state_tensor[:, 0], 1, dims=3)
            + torch.roll(state_tensor[:, 0], -1, dims=3)
            - 4 * state_tensor[:, 0]
        ) / (dx_val * dx_val)
        state_tensor[:, 0] = (
            state_tensor[:, 0] + diffusion_coeff * laplacian_temp * dt_val
        )

        # Moisture condensation
        sat_vapor_pressure = 611.2 * torch.exp(
            17.67 * state_tensor[:, 0] / (state_tensor[:, 0] + 243.5)
        )
        condensation = torch.clamp(
            state_tensor[:, 2] - sat_vapor_pressure * 0.001, min=0
        )
        state_tensor[:, 2] = state_tensor[:, 2] - condensation * 0.1
        state_tensor[:, 0] = state_tensor[:, 0] + condensation * 2.5e6 / 1005 * dt_val

        return state_tensor
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/climate_modeling/simulation.py*

`@torch.compile(mode="reduce-overhead")` compiles this function into optimized CUDA kernels. Combined with mixed precision (`torch.cuda.amp.autocast`), this runs 3-4x faster than eager PyTorch.

Every 10 timesteps, the simulation checks for extreme events:
- **Hurricanes**: Wind speed > 33 m/s with low pressure
- **Heatwaves**: Temperature anomalies exceeding thresholds

Detected phenomena get logged to the metrics, which flow to the live dashboard.

### Distributing across multiple GPUs

800 ensemble members is a lot for one GPU, so we distribute them:

```
@cpu_env.task
async def run_distributed_simulation_ensemble(
    preprocessed_data: File, params: SimulationParams, n_gpus: int
) -> tuple[list[File], list[ClimateMetrics]]:
    total_members = params.ensemble_size
    members_per_gpu = total_members // n_gpus

    # Distribute ensemble members across GPUs
    tasks = []
    for gpu_id in range(n_gpus):
        # Calculate ensemble range for this GPU
        ensemble_start = gpu_id * members_per_gpu
        # Last GPU gets any remainder members
        if gpu_id == n_gpus - 1:
            ensemble_end = total_members
        else:
            ensemble_end = ensemble_start + members_per_gpu

        # Launch GPU task with ensemble subset
        gpu_task = run_atmospheric_simulation(
            preprocessed_data,
            params,
            gpu_id,
            ensemble_start=ensemble_start,
            ensemble_end=ensemble_end,
        )
        tasks.append(gpu_task)

    # Execute all GPUs in parallel
    results = await asyncio.gather(*tasks)

    output_files = [r[0] for r in results]
    metrics = [r[1] for r in results]

    return output_files, metrics
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/climate_modeling/simulation.py*

The task splits the ensemble members evenly across the available GPUs, launches the simulation runs in parallel using `asyncio.gather`, and then aggregates the results. With five GPUs, each GPU runs 160 ensemble members. Flyte takes care of scheduling, so GPU tasks start automatically as soon as resources become available.

### The main workflow

Everything comes together in the orchestration task:

```
@cpu_env.task(report=True)
async def adaptive_climate_modeling_workflow(
    region: str = "atlantic",
    date_range: list[str, str] = ["2024-09-01", "2024-09-10"],
    current_params: SimulationParams = SimulationParams(),
    enable_multi_gpu: bool = True,
    n_gpus: int = 5,
) -> SimulationSummary:
    """Orchestrates multi-source ingestion, GPU simulation, and adaptive refinement."""
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/climate_modeling/simulation.py*

`report=True` enables Flyte Reports for live monitoring.

```
    # Parallel data ingestion from three sources
    with flyte.group("data-ingestion"):
        satellite_task = ingest_satellite_data(region, date_range)
        reanalysis_task = ingest_reanalysis_data(region, date_range)
        station_task = ingest_station_data(region, date_range)

        satellite_data, reanalysis_data, station_data = await asyncio.gather(
            satellite_task,
            reanalysis_task,
            station_task,
        )
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/climate_modeling/simulation.py*

`flyte.group("data-ingestion")` visually groups the ingestion tasks in the Flyte UI. Inside the group, three tasks launch concurrently. `asyncio.gather` waits for all three to complete before preprocessing begins.

The workflow then enters an iterative loop:
1. Run GPU simulation (single or multi-GPU)
2. Check convergence by comparing forecasts across iterations
3. Detect extreme events
4. If a hurricane is detected and we haven't refined yet, double the grid resolution
5. Stream metrics to the live dashboard
6. Repeat until converged or max iterations reached

Adaptive mesh refinement is the key feature here. When the simulation detects a hurricane forming, it automatically increases resolution to capture the fine-scale dynamics. This is expensive, so we limit it to one refinement per run.

### Running the pipeline

```
if __name__ == "__main__":
    flyte.init_from_config()
    run_multi_gpu = flyte.run(adaptive_climate_modeling_workflow)

    print(f"Run URL: {run_multi_gpu.url}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/climate_modeling/simulation.py*

Before running, set up ERA5 API credentials:

```bash
flyte create secret cds_api_key <YOUR_CDS_API_KEY>
flyte create secret cds_api_url https://cds.climate.copernicus.eu/api
```

Then launch:

```bash
flyte create config --endpoint <FLYTE_OR_UNION_ENDPOINT> --project <PROJECT_NAME> --domain <DOMAIN_NAME> --builder remote
uv run simulation.py
```

The default configuration uses the Atlantic region for September 2024, which is hurricane season.

## Key concepts

### Ensemble forecasting

Weather prediction is inherently uncertain. Small errors in the initial conditions grow over time due to chaotic dynamics, which means a single forecast can only ever be one possible outcome.

Ensemble forecasting addresses this uncertainty by:
- Perturbing the initial conditions within known observational error bounds
- Running many independent forecasts
- Computing the ensemble mean as the most likely outcome and the ensemble spread as a measure of uncertainty

### Adaptive mesh refinement

When a hurricane begins to form, coarse spatial grids are not sufficient to resolve critical features like eyewall dynamics. Adaptive mesh refinement allows the simulation to focus compute where it matters most by:
- Increasing grid resolution, for example from 10 km to 5 km
- Reducing the timestep to maintain numerical stability
- Refining only the regions of interest instead of the entire domain

This approach is computationally expensive, but it is essential for producing accurate intensity forecasts.

### Real-time event detection

Rather than analyzing results after a simulation completes, this pipeline detects significant events as the simulation runs.

The system monitors for conditions such as:
- **Hurricanes**: Wind speeds exceeding 33 m/s (Category 1 threshold) combined with central pressure below 980 mb
- **Heatwaves**: Sustained temperature anomalies over a defined period

Detecting these events in real time enables adaptive responses, such as refining the simulation or triggering alerts, and supports earlier warnings for extreme weather.

## Where to go next

This example is intentionally scoped to keep the ideas clear, but there are several natural ways to extend it for more realistic workloads.

To model different ocean basins, change the `region` parameter to values like `"pacific"` or `"indian"`. The ingestion tasks automatically adjust to pull the appropriate satellite coverage for each region.

To run longer forecasts, increase `simulation_hours` in `SimulationParams`. The default of 240 hours, or 10 days, is typical for medium-range forecasting, but you can run longer simulations if you have the compute budget.

Finally, the physics step here is deliberately simplified. Production systems usually incorporate additional components such as radiation schemes, boundary layer parameterizations, and land surface models. These can be added incrementally as separate steps without changing the overall structure of the pipeline.


=== PAGE: https://www.union.ai/docs/v2/union/tutorials/trading-agents ===

# Multi-agent trading simulation

> [!NOTE]
> Code available [here](https://github.com/unionai/unionai-examples/tree/main/v2/tutorials/trading_agents); based on work by [TauricResearch](https://github.com/TauricResearch/TradingAgents).

This example walks you through building a multi-agent trading simulation, modeling how agents within a firm might interact, strategize, and make trades collaboratively.

![Trading agents execution visualization](https://raw.githubusercontent.com/unionai/unionai-docs-static/main/images/tutorials/trading-agents/execution.png)
_Trading agents execution visualization_

## TL;DR

- You'll build a trading firm made up of agents that analyze, argue, and act, modeled with Python functions.
- You'll use the Flyte SDK to orchestrate this world — giving you visibility, retries, caching, and durability.
- You'll learn how to plug in tools, structure conversations, and track decisions across agents.
- You'll see how agents debate, use context, generate reports, and retain memory via vector DBs.

## What is an agent, anyway?

Agentic workflows are a rising pattern for complex problem-solving with LLMs. Think of agents as:

- An LLM (like GPT-4 or Mistral)
- A loop that keeps them thinking until a goal is met
- A set of optional tools they can call (APIs, search, calculators, etc.)
- Enough tokens to reason about the problem at hand

That's it.

You define tools, bind them to an agent, and let it run, reasoning step-by-step, optionally using those tools, until it finishes.

## What's different here?

We're not building yet another agent framework. You're free to use LangChain, custom code, or whatever setup you like.

What we're giving you is the missing piece: a way to run these workflows **reliably, observably, and at scale, with zero rewrites.**

With Flyte, you get:

- Prompt + tool traceability and full state retention
- Built-in retries, caching, and failure recovery
- A native way to plug in your agents; no magic syntax required

## How it works: step-by-step walkthrough

This simulation is powered by a Flyte task that orchestrates multiple intelligent agents working together to analyze a company's stock and make informed trading decisions.

![Trading agents schema](https://raw.githubusercontent.com/unionai/unionai-docs-static/main/images/tutorials/trading-agents/schema.png)
_Trading agents schema_

### Entry point

Everything begins with a top-level Flyte task called `main`, which serves as the entry point to the workflow.

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#     "flyte>=2.0.0b52",
#     "akshare==1.16.98",
#     "backtrader==1.9.78.123",
#     "boto3==1.39.9",
#     "chainlit==2.5.5",
#     "eodhd==1.0.32",
#     "feedparser==6.0.11",
#     "finnhub-python==2.4.23",
#     "langchain-experimental==0.3.4",
#     "langchain-openai==0.3.23",
#     "pandas==2.3.0",
#     "parsel==1.10.0",
#     "praw==7.8.1",
#     "pytz==2025.2",
#     "questionary==2.1.0",
#     "redis==6.2.0",
#     "requests==2.32.4",
#     "stockstats==0.6.5",
#     "tqdm==4.67.1",
#     "tushare==1.4.21",
#     "typing-extensions==4.14.0",
#     "yfinance==0.2.63",
# ]
# main = "main"
# params = ""
# ///
import asyncio
from copy import deepcopy

import agents
import agents.analysts
from agents.managers import create_research_manager, create_risk_manager
from agents.researchers import create_bear_researcher, create_bull_researcher
from agents.risk_debators import (
    create_neutral_debator,
    create_risky_debator,
    create_safe_debator,
)
from agents.trader import create_trader
from agents.utils.utils import AgentState
from flyte_env import DEEP_THINKING_LLM, QUICK_THINKING_LLM, env, flyte
from langchain_openai import ChatOpenAI
from reflection import (
    reflect_bear_researcher,
    reflect_bull_researcher,
    reflect_research_manager,
    reflect_risk_manager,
    reflect_trader,
)

@env.task
async def process_signal(full_signal: str, QUICK_THINKING_LLM: str) -> str:
    """Process a full trading signal to extract the core decision."""

    messages = [
        {
            "role": "system",
            "content": """You are an efficient assistant designed to analyze paragraphs or
financial reports provided by a group of analysts.
Your task is to extract the investment decision: SELL, BUY, or HOLD.
Provide only the extracted decision (SELL, BUY, or HOLD) as your output,
without adding any additional text or information.""",
        },
        {"role": "human", "content": full_signal},
    ]

    return ChatOpenAI(model=QUICK_THINKING_LLM).invoke(messages).content

async def run_analyst(analyst_name, state, online_tools):
    # Create a copy of the state for isolation
    run_fn = getattr(agents.analysts, f"create_{analyst_name}_analyst")

    # Run the analyst's chain
    result_state = await run_fn(QUICK_THINKING_LLM, state, online_tools)

    # Determine the report key
    report_key = (
        "sentiment_report"
        if analyst_name == "social_media"
        else f"{analyst_name}_report"
    )
    report_value = getattr(result_state, report_key)

    return result_state.messages[1:], report_key, report_value

# {{docs-fragment main}}
@env.task
async def main(
    selected_analysts: list[str] = [
        "market",
        "fundamentals",
        "news",
        "social_media",
    ],
    max_debate_rounds: int = 1,
    max_risk_discuss_rounds: int = 1,
    online_tools: bool = True,
    company_name: str = "NVDA",
    trade_date: str = "2024-05-12",
) -> tuple[str, AgentState]:
    if not selected_analysts:
        raise ValueError(
            "No analysts selected. Please select at least one analyst from market, fundamentals, news, or social_media."
        )

    state = AgentState(
        messages=[{"role": "human", "content": company_name}],
        company_of_interest=company_name,
        trade_date=str(trade_date),
    )

    # Run all analysts concurrently
    results = await asyncio.gather(
        *[
            run_analyst(analyst, deepcopy(state), online_tools)
            for analyst in selected_analysts
        ]
    )

    # Flatten and append all resulting messages into the shared state
    for messages, report_attr, report in results:
        state.messages.extend(messages)
        setattr(state, report_attr, report)

    # Bull/Bear debate loop
    state = await create_bull_researcher(QUICK_THINKING_LLM, state)  # Start with bull
    while state.investment_debate_state.count < 2 * max_debate_rounds:
        current = state.investment_debate_state.current_response
        if current.startswith("Bull"):
            state = await create_bear_researcher(QUICK_THINKING_LLM, state)
        else:
            state = await create_bull_researcher(QUICK_THINKING_LLM, state)

    state = await create_research_manager(DEEP_THINKING_LLM, state)
    state = await create_trader(QUICK_THINKING_LLM, state)

    # Risk debate loop
    state = await create_risky_debator(QUICK_THINKING_LLM, state)  # Start with risky
    while state.risk_debate_state.count < 3 * max_risk_discuss_rounds:
        speaker = state.risk_debate_state.latest_speaker
        if speaker == "Risky":
            state = await create_safe_debator(QUICK_THINKING_LLM, state)
        elif speaker == "Safe":
            state = await create_neutral_debator(QUICK_THINKING_LLM, state)
        else:
            state = await create_risky_debator(QUICK_THINKING_LLM, state)

    state = await create_risk_manager(DEEP_THINKING_LLM, state)
    decision = await process_signal(state.final_trade_decision, QUICK_THINKING_LLM)

    return decision, state

# {{/docs-fragment main}}

# {{docs-fragment reflect_on_decisions}}
@env.task
async def reflect_and_store(state: AgentState, returns: str) -> str:
    await asyncio.gather(
        reflect_bear_researcher(state, returns),
        reflect_bull_researcher(state, returns),
        reflect_trader(state, returns),
        reflect_risk_manager(state, returns),
        reflect_research_manager(state, returns),
    )

    return "Reflection completed."

# Run the reflection task after the main function
@env.task(cache="disable")
async def reflect_on_decisions(
    returns: str,
    selected_analysts: list[str] = [
        "market",
        "fundamentals",
        "news",
        "social_media",
    ],
    max_debate_rounds: int = 1,
    max_risk_discuss_rounds: int = 1,
    online_tools: bool = True,
    company_name: str = "NVDA",
    trade_date: str = "2024-05-12",
) -> str:
    _, state = await main(
        selected_analysts,
        max_debate_rounds,
        max_risk_discuss_rounds,
        online_tools,
        company_name,
        trade_date,
    )

    return await reflect_and_store(state, returns)

# {{/docs-fragment reflect_on_decisions}}

# {{docs-fragment execute_main}}
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
    run.wait()

    # run = flyte.run(reflect_on_decisions, "+3.2% gain over 5 days")
    # print(run.url)

# {{/docs-fragment execute_main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/trading_agents/main.py*

This task accepts several inputs:

- the list of analysts to run,
- the number of debate and risk discussion rounds,
- a flag to enable online tools,
- the company you're evaluating,
- and the target trading date.

The most interesting parameter here is the list of analysts to run. It determines which analyst agents will be invoked and shapes the overall structure of the simulation. Based on this input, the task dynamically launches agent tasks, running them in parallel.

The `main` task is written as a regular asynchronous Python function wrapped with Flyte's task decorator. No domain-specific language or orchestration glue is needed — just idiomatic Python, optionally using async for better performance. The task environment is configured once and shared across all tasks for consistency.

```
# {{docs-fragment env}}
import flyte

QUICK_THINKING_LLM = "gpt-4o-mini"
DEEP_THINKING_LLM = "o4-mini"

env = flyte.TaskEnvironment(
    name="trading-agents",
    secrets=[
        flyte.Secret(key="finnhub_api_key", as_env_var="FINNHUB_API_KEY"),
        flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY"),
    ],
    image=flyte.Image.from_uv_script("main.py", name="trading-agents", pre=True),
    resources=flyte.Resources(cpu="1"),
    cache="auto",
)

# {{/docs-fragment env}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/trading_agents/flyte_env.py*

### Analyst agents

Each analyst agent comes equipped with a set of tools and a carefully designed prompt tailored to its specific domain. These tools are modular Flyte tasks — for example, downloading financial reports or computing technical indicators — and benefit from Flyte's built-in caching to avoid redundant computation.

```
from datetime import datetime

import pandas as pd
import tools.interface as interface
import yfinance as yf
from flyte_env import env

from flyte.io import File

@env.task
async def get_reddit_news(
    curr_date: str,  # Date you want to get news for in yyyy-mm-dd format
) -> str:
    """
    Retrieve global news from Reddit within a specified time frame.
    Args:
        curr_date (str): Date you want to get news for in yyyy-mm-dd format
    Returns:
        str: A formatted dataframe containing the latest global news
        from Reddit in the specified time frame.
    """

    global_news_result = interface.get_reddit_global_news(curr_date, 7, 5)

    return global_news_result

@env.task
async def get_finnhub_news(
    ticker: str,  # Search query of a company, e.g. 'AAPL, TSM, etc.
    start_date: str,  # Start date in yyyy-mm-dd format
    end_date: str,  # End date in yyyy-mm-dd format
) -> str:
    """
    Retrieve the latest news about a given stock from Finnhub within a date range
    Args:
        ticker (str): Ticker of a company. e.g. AAPL, TSM
        start_date (str): Start date in yyyy-mm-dd format
        end_date (str): End date in yyyy-mm-dd format
    Returns:
        str: A formatted dataframe containing news about the company
        within the date range from start_date to end_date
    """

    end_date_str = end_date

    end_date = datetime.strptime(end_date, "%Y-%m-%d")
    start_date = datetime.strptime(start_date, "%Y-%m-%d")
    look_back_days = (end_date - start_date).days

    finnhub_news_result = interface.get_finnhub_news(
        ticker, end_date_str, look_back_days
    )

    return finnhub_news_result

@env.task
async def get_reddit_stock_info(
    ticker: str,  # Ticker of a company. e.g. AAPL, TSM
    curr_date: str,  # Current date you want to get news for
) -> str:
    """
    Retrieve the latest news about a given stock from Reddit, given the current date.
    Args:
        ticker (str): Ticker of a company. e.g. AAPL, TSM
        curr_date (str): current date in yyyy-mm-dd format to get news for
    Returns:
        str: A formatted dataframe containing the latest news about the company on the given date
    """

    stock_news_results = interface.get_reddit_company_news(ticker, curr_date, 7, 5)

    return stock_news_results

@env.task
async def get_YFin_data(
    symbol: str,  # ticker symbol of the company
    start_date: str,  # Start date in yyyy-mm-dd format
    end_date: str,  # End date in yyyy-mm-dd format
) -> str:
    """
    Retrieve the stock price data for a given ticker symbol from Yahoo Finance.
    Args:
        symbol (str): Ticker symbol of the company, e.g. AAPL, TSM
        start_date (str): Start date in yyyy-mm-dd format
        end_date (str): End date in yyyy-mm-dd format
    Returns:
        str: A formatted dataframe containing the stock price data
        for the specified ticker symbol in the specified date range.
    """

    result_data = interface.get_YFin_data(symbol, start_date, end_date)

    return result_data

@env.task
async def get_YFin_data_online(
    symbol: str,  # ticker symbol of the company
    start_date: str,  # Start date in yyyy-mm-dd format
    end_date: str,  # End date in yyyy-mm-dd format
) -> str:
    """
    Retrieve the stock price data for a given ticker symbol from Yahoo Finance.
    Args:
        symbol (str): Ticker symbol of the company, e.g. AAPL, TSM
        start_date (str): Start date in yyyy-mm-dd format
        end_date (str): End date in yyyy-mm-dd format
    Returns:
        str: A formatted dataframe containing the stock price data
        for the specified ticker symbol in the specified date range.
    """

    result_data = interface.get_YFin_data_online(symbol, start_date, end_date)

    return result_data

@env.task
async def cache_market_data(symbol: str, start_date: str, end_date: str) -> File:
    data_file = f"{symbol}-YFin-data-{start_date}-{end_date}.csv"

    data = yf.download(
        symbol,
        start=start_date,
        end=end_date,
        multi_level_index=False,
        progress=False,
        auto_adjust=True,
    )
    data = data.reset_index()
    data.to_csv(data_file, index=False)

    return await File.from_local(data_file)

@env.task
async def get_stockstats_indicators_report(
    symbol: str,  # ticker symbol of the company
    indicator: str,  # technical indicator to get the analysis and report of
    curr_date: str,  # The current trading date you are trading on, YYYY-mm-dd
    look_back_days: int = 30,  # how many days to look back
) -> str:
    """
    Retrieve stock stats indicators for a given ticker symbol and indicator.
    Args:
        symbol (str): Ticker symbol of the company, e.g. AAPL, TSM
        indicator (str): Technical indicator to get the analysis and report of
        curr_date (str): The current trading date you are trading on, YYYY-mm-dd
        look_back_days (int): How many days to look back, default is 30
    Returns:
        str: A formatted dataframe containing the stock stats indicators
        for the specified ticker symbol and indicator.
    """

    today_date = pd.Timestamp.today()

    end_date = today_date
    start_date = today_date - pd.DateOffset(years=15)
    start_date = start_date.strftime("%Y-%m-%d")
    end_date = end_date.strftime("%Y-%m-%d")

    data_file = await cache_market_data(symbol, start_date, end_date)
    local_data_file = await data_file.download()

    result_stockstats = interface.get_stock_stats_indicators_window(
        symbol, indicator, curr_date, look_back_days, False, local_data_file
    )

    return result_stockstats

# {{docs-fragment get_stockstats_indicators_report_online}}
@env.task
async def get_stockstats_indicators_report_online(
    symbol: str,  # ticker symbol of the company
    indicator: str,  # technical indicator to get the analysis and report of
    curr_date: str,  # The current trading date you are trading on, YYYY-mm-dd"
    look_back_days: int = 30,  # "how many days to look back"
) -> str:
    """
    Retrieve stock stats indicators for a given ticker symbol and indicator.
    Args:
        symbol (str): Ticker symbol of the company, e.g. AAPL, TSM
        indicator (str): Technical indicator to get the analysis and report of
        curr_date (str): The current trading date you are trading on, YYYY-mm-dd
        look_back_days (int): How many days to look back, default is 30
    Returns:
        str: A formatted dataframe containing the stock stats indicators
        for the specified ticker symbol and indicator.
    """

    today_date = pd.Timestamp.today()

    end_date = today_date
    start_date = today_date - pd.DateOffset(years=15)
    start_date = start_date.strftime("%Y-%m-%d")
    end_date = end_date.strftime("%Y-%m-%d")

    data_file = await cache_market_data(symbol, start_date, end_date)
    local_data_file = await data_file.download()

    result_stockstats = interface.get_stock_stats_indicators_window(
        symbol, indicator, curr_date, look_back_days, True, local_data_file
    )

    return result_stockstats

# {{/docs-fragment get_stockstats_indicators_report_online}}

@env.task
async def get_finnhub_company_insider_sentiment(
    ticker: str,  # ticker symbol for the company
    curr_date: str,  # current date of you are trading at, yyyy-mm-dd
) -> str:
    """
    Retrieve insider sentiment information about a company (retrieved
    from public SEC information) for the past 30 days
    Args:
        ticker (str): ticker symbol of the company
        curr_date (str): current date you are trading at, yyyy-mm-dd
    Returns:
        str: a report of the sentiment in the past 30 days starting at curr_date
    """

    data_sentiment = interface.get_finnhub_company_insider_sentiment(
        ticker, curr_date, 30
    )

    return data_sentiment

@env.task
async def get_finnhub_company_insider_transactions(
    ticker: str,  # ticker symbol
    curr_date: str,  # current date you are trading at, yyyy-mm-dd
) -> str:
    """
    Retrieve insider transaction information about a company
    (retrieved from public SEC information) for the past 30 days
    Args:
        ticker (str): ticker symbol of the company
        curr_date (str): current date you are trading at, yyyy-mm-dd
    Returns:
        str: a report of the company's insider transactions/trading information in the past 30 days
    """

    data_trans = interface.get_finnhub_company_insider_transactions(
        ticker, curr_date, 30
    )

    return data_trans

@env.task
async def get_simfin_balance_sheet(
    ticker: str,  # ticker symbol
    freq: str,  # reporting frequency of the company's financial history: annual/quarterly
    curr_date: str,  # current date you are trading at, yyyy-mm-dd
):
    """
    Retrieve the most recent balance sheet of a company
    Args:
        ticker (str): ticker symbol of the company
        freq (str): reporting frequency of the company's financial history: annual / quarterly
        curr_date (str): current date you are trading at, yyyy-mm-dd
    Returns:
        str: a report of the company's most recent balance sheet
    """

    data_balance_sheet = interface.get_simfin_balance_sheet(ticker, freq, curr_date)

    return data_balance_sheet

@env.task
async def get_simfin_cashflow(
    ticker: str,  # ticker symbol
    freq: str,  # reporting frequency of the company's financial history: annual/quarterly
    curr_date: str,  # current date you are trading at, yyyy-mm-dd
) -> str:
    """
    Retrieve the most recent cash flow statement of a company
    Args:
        ticker (str): ticker symbol of the company
        freq (str): reporting frequency of the company's financial history: annual / quarterly
        curr_date (str): current date you are trading at, yyyy-mm-dd
    Returns:
            str: a report of the company's most recent cash flow statement
    """

    data_cashflow = interface.get_simfin_cashflow(ticker, freq, curr_date)

    return data_cashflow

@env.task
async def get_simfin_income_stmt(
    ticker: str,  # ticker symbol
    freq: str,  # reporting frequency of the company's financial history: annual/quarterly
    curr_date: str,  # current date you are trading at, yyyy-mm-dd
) -> str:
    """
    Retrieve the most recent income statement of a company
    Args:
        ticker (str): ticker symbol of the company
        freq (str): reporting frequency of the company's financial history: annual / quarterly
        curr_date (str): current date you are trading at, yyyy-mm-dd
    Returns:
            str: a report of the company's most recent income statement
    """

    data_income_stmt = interface.get_simfin_income_statements(ticker, freq, curr_date)

    return data_income_stmt

@env.task
async def get_google_news(
    query: str,  # Query to search with
    curr_date: str,  # Curr date in yyyy-mm-dd format
) -> str:
    """
    Retrieve the latest news from Google News based on a query and date range.
    Args:
        query (str): Query to search with
        curr_date (str): Current date in yyyy-mm-dd format
        look_back_days (int): How many days to look back
    Returns:
        str: A formatted string containing the latest news from Google News
        based on the query and date range.
    """

    google_news_results = interface.get_google_news(query, curr_date, 7)

    return google_news_results

@env.task
async def get_stock_news_openai(
    ticker: str,  # the company's ticker
    curr_date: str,  # Current date in yyyy-mm-dd format
) -> str:
    """
    Retrieve the latest news about a given stock by using OpenAI's news API.
    Args:
        ticker (str): Ticker of a company. e.g. AAPL, TSM
        curr_date (str): Current date in yyyy-mm-dd format
    Returns:
        str: A formatted string containing the latest news about the company on the given date.
    """

    openai_news_results = interface.get_stock_news_openai(ticker, curr_date)

    return openai_news_results

@env.task
async def get_global_news_openai(
    curr_date: str,  # Current date in yyyy-mm-dd format
) -> str:
    """
    Retrieve the latest macroeconomics news on a given date using OpenAI's macroeconomics news API.
    Args:
        curr_date (str): Current date in yyyy-mm-dd format
    Returns:
        str: A formatted string containing the latest macroeconomic news on the given date.
    """

    openai_news_results = interface.get_global_news_openai(curr_date)

    return openai_news_results

@env.task
async def get_fundamentals_openai(
    ticker: str,  # the company's ticker
    curr_date: str,  # Current date in yyyy-mm-dd format
) -> str:
    """
    Retrieve the latest fundamental information about a given stock
    on a given date by using OpenAI's news API.
    Args:
        ticker (str): Ticker of a company. e.g. AAPL, TSM
        curr_date (str): Current date in yyyy-mm-dd format

    Returns:
        str: A formatted string containing the latest fundamental information
        about the company on the given date.
    """

    openai_fundamentals_results = interface.get_fundamentals_openai(ticker, curr_date)

    return openai_fundamentals_results
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/trading_agents/tools/toolkit.py*

When initialized, an analyst enters a structured reasoning loop (via LangChain), where it can call tools, observe outputs, and refine its internal state before generating a final report. These reports are later consumed by downstream agents.

Here's an example of a news analyst that interprets global events and macroeconomic signals. We specify the tools accessible to the analyst, and the LLM selects which ones to use based on context.

```
import asyncio

from agents.utils.utils import AgentState
from flyte_env import env
from langchain_core.messages import ToolMessage, convert_to_openai_messages
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_openai import ChatOpenAI
from tools import toolkit

import flyte

MAX_ITERATIONS = 5

# {{docs-fragment agent_helper}}
async def run_chain_with_tools(
    type: str, state: AgentState, llm: str, system_message: str, tool_names: list[str]
) -> AgentState:
    prompt = ChatPromptTemplate.from_messages(
        [
            (
                "system",
                "You are a helpful AI assistant, collaborating with other assistants."
                " Use the provided tools to progress towards answering the question."
                " If you are unable to fully answer, that's OK; another assistant with different tools"
                " will help where you left off. Execute what you can to make progress."
                " If you or any other assistant has the FINAL TRANSACTION PROPOSAL: **BUY/HOLD/SELL** or deliverable,"
                " prefix your response with FINAL TRANSACTION PROPOSAL: **BUY/HOLD/SELL** so the team knows to stop."
                " You have access to the following tools: {tool_names}.\n{system_message}"
                " For your reference, the current date is {current_date}. The company we want to look at is {ticker}.",
            ),
            MessagesPlaceholder(variable_name="messages"),
        ]
    )

    prompt = prompt.partial(system_message=system_message)
    prompt = prompt.partial(tool_names=", ".join(tool_names))
    prompt = prompt.partial(current_date=state.trade_date)
    prompt = prompt.partial(ticker=state.company_of_interest)

    chain = prompt | ChatOpenAI(model=llm).bind_tools(
        [getattr(toolkit, tool_name).func for tool_name in tool_names]
    )

    iteration = 0
    while iteration < MAX_ITERATIONS:
        result = await chain.ainvoke(state.messages)
        state.messages.append(convert_to_openai_messages(result))

        if not result.tool_calls:
            # Final response — no tools required
            setattr(state, f"{type}_report", result.content or "")
            break

        # Run all tool calls in parallel
        async def run_single_tool(tool_call):
            tool_name = tool_call["name"]
            tool_args = tool_call["args"]
            tool = getattr(toolkit, tool_name, None)

            if not tool:
                return None

            content = await tool(**tool_args)
            return ToolMessage(
                tool_call_id=tool_call["id"], name=tool_name, content=content
            )

        with flyte.group(f"tool_calls_iteration_{iteration}"):
            tool_messages = await asyncio.gather(
                *[run_single_tool(tc) for tc in result.tool_calls]
            )

        # Add valid tool results to state
        tool_messages = [msg for msg in tool_messages if msg]
        state.messages.extend(convert_to_openai_messages(tool_messages))

        iteration += 1
    else:
        # Reached iteration cap — optionally raise or log
        print(f"Max iterations ({MAX_ITERATIONS}) reached for {type}")

    return state

# {{/docs-fragment agent_helper}}

@env.task
async def create_fundamentals_analyst(
    llm: str, state: AgentState, online_tools: bool
) -> AgentState:
    if online_tools:
        tools = [toolkit.get_fundamentals_openai]
    else:
        tools = [
            toolkit.get_finnhub_company_insider_sentiment,
            toolkit.get_finnhub_company_insider_transactions,
            toolkit.get_simfin_balance_sheet,
            toolkit.get_simfin_cashflow,
            toolkit.get_simfin_income_stmt,
        ]

    system_message = (
        "You are a researcher tasked with analyzing fundamental information over the past week about a company. "
        "Please write a comprehensive report of the company's fundamental information such as financial documents, "
        "company profile, basic company financials, company financial history, insider sentiment, and insider "
        "transactions to gain a full view of the company's "
        "fundamental information to inform traders. Make sure to include as much detail as possible. "
        "Do not simply state the trends are mixed, "
        "provide detailed and finegrained analysis and insights that may help traders make decisions. "
        "Make sure to append a Markdown table at the end of the report to organize key points in the report, "
        "organized and easy to read."
    )

    tool_names = [tool.func.__name__ for tool in tools]

    return await run_chain_with_tools(
        "fundamentals", state, llm, system_message, tool_names
    )

@env.task
async def create_market_analyst(
    llm: str, state: AgentState, online_tools: bool
) -> AgentState:
    if online_tools:
        tools = [
            toolkit.get_YFin_data_online,
            toolkit.get_stockstats_indicators_report_online,
        ]
    else:
        tools = [
            toolkit.get_YFin_data,
            toolkit.get_stockstats_indicators_report,
        ]

    system_message = (
        """You are a trading assistant tasked with analyzing financial markets.
Your role is to select the **most relevant indicators** for a given market condition
or trading strategy from the following list.
The goal is to choose up to **8 indicators** that provide complementary insights without redundancy.
Categories and each category's indicators are:

Moving Averages:
- close_50_sma: 50 SMA: A medium-term trend indicator.
Usage: Identify trend direction and serve as dynamic support/resistance.
Tips: It lags price; combine with faster indicators for timely signals.
- close_200_sma: 200 SMA: A long-term trend benchmark.
Usage: Confirm overall market trend and identify golden/death cross setups.
Tips: It reacts slowly; best for strategic trend confirmation rather than frequent trading entries.
- close_10_ema: 10 EMA: A responsive short-term average.
Usage: Capture quick shifts in momentum and potential entry points.
Tips: Prone to noise in choppy markets; use alongside longer averages for filtering false signals.

MACD Related:
- macd: MACD: Computes momentum via differences of EMAs.
Usage: Look for crossovers and divergence as signals of trend changes.
Tips: Confirm with other indicators in low-volatility or sideways markets.
- macds: MACD Signal: An EMA smoothing of the MACD line.
Usage: Use crossovers with the MACD line to trigger trades.
Tips: Should be part of a broader strategy to avoid false positives.
- macdh: MACD Histogram: Shows the gap between the MACD line and its signal.
Usage: Visualize momentum strength and spot divergence early.
Tips: Can be volatile; complement with additional filters in fast-moving markets.

Momentum Indicators:
- rsi: RSI: Measures momentum to flag overbought/oversold conditions.
Usage: Apply 70/30 thresholds and watch for divergence to signal reversals.
Tips: In strong trends, RSI may remain extreme; always cross-check with trend analysis.

Volatility Indicators:
- boll: Bollinger Middle: A 20 SMA serving as the basis for Bollinger Bands.
Usage: Acts as a dynamic benchmark for price movement.
Tips: Combine with the upper and lower bands to effectively spot breakouts or reversals.
- boll_ub: Bollinger Upper Band: Typically 2 standard deviations above the middle line.
Usage: Signals potential overbought conditions and breakout zones.
Tips: Confirm signals with other tools; prices may ride the band in strong trends.
- boll_lb: Bollinger Lower Band: Typically 2 standard deviations below the middle line.
Usage: Indicates potential oversold conditions.
Tips: Use additional analysis to avoid false reversal signals.
- atr: ATR: Averages true range to measure volatility.
Usage: Set stop-loss levels and adjust position sizes based on current market volatility.
Tips: It's a reactive measure, so use it as part of a broader risk management strategy.

Volume-Based Indicators:
- vwma: VWMA: A moving average weighted by volume.
Usage: Confirm trends by integrating price action with volume data.
Tips: Watch for skewed results from volume spikes; use in combination with other volume analyses.

- Select indicators that provide diverse and complementary information.
Avoid redundancy (e.g., do not select both rsi and stochrsi).
Also briefly explain why they are suitable for the given market context.
When you tool call, please use the exact name of the indicators provided above as they are defined parameters,
otherwise your call will fail.
Please make sure to call get_YFin_data first to retrieve the CSV that is needed to generate indicators.
Write a very detailed and nuanced report of the trends you observe.
Do not simply state the trends are mixed, provide detailed and finegrained analysis
and insights that may help traders make decisions."""
        """ Make sure to append a Markdown table at the end of the report to
        organize key points in the report, organized and easy to read."""
    )

    tool_names = [tool.func.__name__ for tool in tools]
    return await run_chain_with_tools("market", state, llm, system_message, tool_names)

# {{docs-fragment news_analyst}}
@env.task
async def create_news_analyst(
    llm: str, state: AgentState, online_tools: bool
) -> AgentState:
    if online_tools:
        tools = [
            toolkit.get_global_news_openai,
            toolkit.get_google_news,
        ]
    else:
        tools = [
            toolkit.get_finnhub_news,
            toolkit.get_reddit_news,
            toolkit.get_google_news,
        ]

    system_message = (
        "You are a news researcher tasked with analyzing recent news and trends over the past week. "
        "Please write a comprehensive report of the current state of the world that is relevant for "
        "trading and macroeconomics. "
        "Look at news from EODHD, and finnhub to be comprehensive. Do not simply state the trends are mixed, "
        "provide detailed and finegrained analysis and insights that may help traders make decisions."
        """ Make sure to append a Markdown table at the end of the report to organize key points in the report,
        organized and easy to read."""
    )

    tool_names = [tool.func.__name__ for tool in tools]

    return await run_chain_with_tools("news", state, llm, system_message, tool_names)

# {{/docs-fragment news_analyst}}

@env.task
async def create_social_media_analyst(
    llm: str, state: AgentState, online_tools: bool
) -> AgentState:
    if online_tools:
        tools = [toolkit.get_stock_news_openai]
    else:
        tools = [toolkit.get_reddit_stock_info]

    system_message = (
        "You are a social media and company specific news researcher/analyst tasked with analyzing social media posts, "
        "recent company news, and public sentiment for a specific company over the past week. "
        "You will be given a company's name your objective is to write a comprehensive long report "
        "detailing your analysis, insights, and implications for traders and investors on this company's current state "
        "after looking at social media and what people are saying about that company, "
        "analyzing sentiment data of what people feel each day about the company, and looking at recent company news. "
        "Try to look at all sources possible from social media to sentiment to news. Do not simply state the trends "
        "are mixed, provide detailed and finegrained analysis and insights that may help traders make decisions."
        """ Make sure to append a Makrdown table at the end of the report to organize key points in the report,
        organized and easy to read."""
    )

    tool_names = [tool.func.__name__ for tool in tools]

    return await run_chain_with_tools(
        "sentiment", state, llm, system_message, tool_names
    )
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/trading_agents/agents/analysts.py*

Each analyst agent uses a helper function to bind tools, iterate through reasoning steps (up to a configurable maximum), and produce an answer. Setting a max iteration count is crucial to prevent runaway loops. As agents reason, their message history is preserved in their internal state and passed along to the next agent in the chain.

```
import asyncio

from agents.utils.utils import AgentState
from flyte_env import env
from langchain_core.messages import ToolMessage, convert_to_openai_messages
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_openai import ChatOpenAI
from tools import toolkit

import flyte

MAX_ITERATIONS = 5

# {{docs-fragment agent_helper}}
async def run_chain_with_tools(
    type: str, state: AgentState, llm: str, system_message: str, tool_names: list[str]
) -> AgentState:
    prompt = ChatPromptTemplate.from_messages(
        [
            (
                "system",
                "You are a helpful AI assistant, collaborating with other assistants."
                " Use the provided tools to progress towards answering the question."
                " If you are unable to fully answer, that's OK; another assistant with different tools"
                " will help where you left off. Execute what you can to make progress."
                " If you or any other assistant has the FINAL TRANSACTION PROPOSAL: **BUY/HOLD/SELL** or deliverable,"
                " prefix your response with FINAL TRANSACTION PROPOSAL: **BUY/HOLD/SELL** so the team knows to stop."
                " You have access to the following tools: {tool_names}.\n{system_message}"
                " For your reference, the current date is {current_date}. The company we want to look at is {ticker}.",
            ),
            MessagesPlaceholder(variable_name="messages"),
        ]
    )

    prompt = prompt.partial(system_message=system_message)
    prompt = prompt.partial(tool_names=", ".join(tool_names))
    prompt = prompt.partial(current_date=state.trade_date)
    prompt = prompt.partial(ticker=state.company_of_interest)

    chain = prompt | ChatOpenAI(model=llm).bind_tools(
        [getattr(toolkit, tool_name).func for tool_name in tool_names]
    )

    iteration = 0
    while iteration < MAX_ITERATIONS:
        result = await chain.ainvoke(state.messages)
        state.messages.append(convert_to_openai_messages(result))

        if not result.tool_calls:
            # Final response — no tools required
            setattr(state, f"{type}_report", result.content or "")
            break

        # Run all tool calls in parallel
        async def run_single_tool(tool_call):
            tool_name = tool_call["name"]
            tool_args = tool_call["args"]
            tool = getattr(toolkit, tool_name, None)

            if not tool:
                return None

            content = await tool(**tool_args)
            return ToolMessage(
                tool_call_id=tool_call["id"], name=tool_name, content=content
            )

        with flyte.group(f"tool_calls_iteration_{iteration}"):
            tool_messages = await asyncio.gather(
                *[run_single_tool(tc) for tc in result.tool_calls]
            )

        # Add valid tool results to state
        tool_messages = [msg for msg in tool_messages if msg]
        state.messages.extend(convert_to_openai_messages(tool_messages))

        iteration += 1
    else:
        # Reached iteration cap — optionally raise or log
        print(f"Max iterations ({MAX_ITERATIONS}) reached for {type}")

    return state

# {{/docs-fragment agent_helper}}

@env.task
async def create_fundamentals_analyst(
    llm: str, state: AgentState, online_tools: bool
) -> AgentState:
    if online_tools:
        tools = [toolkit.get_fundamentals_openai]
    else:
        tools = [
            toolkit.get_finnhub_company_insider_sentiment,
            toolkit.get_finnhub_company_insider_transactions,
            toolkit.get_simfin_balance_sheet,
            toolkit.get_simfin_cashflow,
            toolkit.get_simfin_income_stmt,
        ]

    system_message = (
        "You are a researcher tasked with analyzing fundamental information over the past week about a company. "
        "Please write a comprehensive report of the company's fundamental information such as financial documents, "
        "company profile, basic company financials, company financial history, insider sentiment, and insider "
        "transactions to gain a full view of the company's "
        "fundamental information to inform traders. Make sure to include as much detail as possible. "
        "Do not simply state the trends are mixed, "
        "provide detailed and finegrained analysis and insights that may help traders make decisions. "
        "Make sure to append a Markdown table at the end of the report to organize key points in the report, "
        "organized and easy to read."
    )

    tool_names = [tool.func.__name__ for tool in tools]

    return await run_chain_with_tools(
        "fundamentals", state, llm, system_message, tool_names
    )

@env.task
async def create_market_analyst(
    llm: str, state: AgentState, online_tools: bool
) -> AgentState:
    if online_tools:
        tools = [
            toolkit.get_YFin_data_online,
            toolkit.get_stockstats_indicators_report_online,
        ]
    else:
        tools = [
            toolkit.get_YFin_data,
            toolkit.get_stockstats_indicators_report,
        ]

    system_message = (
        """You are a trading assistant tasked with analyzing financial markets.
Your role is to select the **most relevant indicators** for a given market condition
or trading strategy from the following list.
The goal is to choose up to **8 indicators** that provide complementary insights without redundancy.
Categories and each category's indicators are:

Moving Averages:
- close_50_sma: 50 SMA: A medium-term trend indicator.
Usage: Identify trend direction and serve as dynamic support/resistance.
Tips: It lags price; combine with faster indicators for timely signals.
- close_200_sma: 200 SMA: A long-term trend benchmark.
Usage: Confirm overall market trend and identify golden/death cross setups.
Tips: It reacts slowly; best for strategic trend confirmation rather than frequent trading entries.
- close_10_ema: 10 EMA: A responsive short-term average.
Usage: Capture quick shifts in momentum and potential entry points.
Tips: Prone to noise in choppy markets; use alongside longer averages for filtering false signals.

MACD Related:
- macd: MACD: Computes momentum via differences of EMAs.
Usage: Look for crossovers and divergence as signals of trend changes.
Tips: Confirm with other indicators in low-volatility or sideways markets.
- macds: MACD Signal: An EMA smoothing of the MACD line.
Usage: Use crossovers with the MACD line to trigger trades.
Tips: Should be part of a broader strategy to avoid false positives.
- macdh: MACD Histogram: Shows the gap between the MACD line and its signal.
Usage: Visualize momentum strength and spot divergence early.
Tips: Can be volatile; complement with additional filters in fast-moving markets.

Momentum Indicators:
- rsi: RSI: Measures momentum to flag overbought/oversold conditions.
Usage: Apply 70/30 thresholds and watch for divergence to signal reversals.
Tips: In strong trends, RSI may remain extreme; always cross-check with trend analysis.

Volatility Indicators:
- boll: Bollinger Middle: A 20 SMA serving as the basis for Bollinger Bands.
Usage: Acts as a dynamic benchmark for price movement.
Tips: Combine with the upper and lower bands to effectively spot breakouts or reversals.
- boll_ub: Bollinger Upper Band: Typically 2 standard deviations above the middle line.
Usage: Signals potential overbought conditions and breakout zones.
Tips: Confirm signals with other tools; prices may ride the band in strong trends.
- boll_lb: Bollinger Lower Band: Typically 2 standard deviations below the middle line.
Usage: Indicates potential oversold conditions.
Tips: Use additional analysis to avoid false reversal signals.
- atr: ATR: Averages true range to measure volatility.
Usage: Set stop-loss levels and adjust position sizes based on current market volatility.
Tips: It's a reactive measure, so use it as part of a broader risk management strategy.

Volume-Based Indicators:
- vwma: VWMA: A moving average weighted by volume.
Usage: Confirm trends by integrating price action with volume data.
Tips: Watch for skewed results from volume spikes; use in combination with other volume analyses.

- Select indicators that provide diverse and complementary information.
Avoid redundancy (e.g., do not select both rsi and stochrsi).
Also briefly explain why they are suitable for the given market context.
When you tool call, please use the exact name of the indicators provided above as they are defined parameters,
otherwise your call will fail.
Please make sure to call get_YFin_data first to retrieve the CSV that is needed to generate indicators.
Write a very detailed and nuanced report of the trends you observe.
Do not simply state the trends are mixed, provide detailed and finegrained analysis
and insights that may help traders make decisions."""
        """ Make sure to append a Markdown table at the end of the report to
        organize key points in the report, organized and easy to read."""
    )

    tool_names = [tool.func.__name__ for tool in tools]
    return await run_chain_with_tools("market", state, llm, system_message, tool_names)

# {{docs-fragment news_analyst}}
@env.task
async def create_news_analyst(
    llm: str, state: AgentState, online_tools: bool
) -> AgentState:
    if online_tools:
        tools = [
            toolkit.get_global_news_openai,
            toolkit.get_google_news,
        ]
    else:
        tools = [
            toolkit.get_finnhub_news,
            toolkit.get_reddit_news,
            toolkit.get_google_news,
        ]

    system_message = (
        "You are a news researcher tasked with analyzing recent news and trends over the past week. "
        "Please write a comprehensive report of the current state of the world that is relevant for "
        "trading and macroeconomics. "
        "Look at news from EODHD, and finnhub to be comprehensive. Do not simply state the trends are mixed, "
        "provide detailed and finegrained analysis and insights that may help traders make decisions."
        """ Make sure to append a Markdown table at the end of the report to organize key points in the report,
        organized and easy to read."""
    )

    tool_names = [tool.func.__name__ for tool in tools]

    return await run_chain_with_tools("news", state, llm, system_message, tool_names)

# {{/docs-fragment news_analyst}}

@env.task
async def create_social_media_analyst(
    llm: str, state: AgentState, online_tools: bool
) -> AgentState:
    if online_tools:
        tools = [toolkit.get_stock_news_openai]
    else:
        tools = [toolkit.get_reddit_stock_info]

    system_message = (
        "You are a social media and company specific news researcher/analyst tasked with analyzing social media posts, "
        "recent company news, and public sentiment for a specific company over the past week. "
        "You will be given a company's name your objective is to write a comprehensive long report "
        "detailing your analysis, insights, and implications for traders and investors on this company's current state "
        "after looking at social media and what people are saying about that company, "
        "analyzing sentiment data of what people feel each day about the company, and looking at recent company news. "
        "Try to look at all sources possible from social media to sentiment to news. Do not simply state the trends "
        "are mixed, provide detailed and finegrained analysis and insights that may help traders make decisions."
        """ Make sure to append a Makrdown table at the end of the report to organize key points in the report,
        organized and easy to read."""
    )

    tool_names = [tool.func.__name__ for tool in tools]

    return await run_chain_with_tools(
        "sentiment", state, llm, system_message, tool_names
    )
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/trading_agents/agents/analysts.py*

Once all analyst reports are complete, their outputs are collected and passed to the next stage of the workflow.

### Research agents

The research phase consists of two agents: a bullish researcher and a bearish one. They evaluate the company from opposing viewpoints, drawing on the analysts' reports. Unlike analysts, they don't use tools. Their role is to interpret, critique, and develop positions based on the evidence.

```
from agents.utils.utils import AgentState, InvestmentDebateState, memory_init
from flyte_env import env
from langchain_openai import ChatOpenAI

# {{docs-fragment bear_researcher}}
@env.task
async def create_bear_researcher(llm: str, state: AgentState) -> AgentState:
    investment_debate_state = state.investment_debate_state
    history = investment_debate_state.history
    bear_history = investment_debate_state.bear_history

    current_response = investment_debate_state.current_response
    market_research_report = state.market_report
    sentiment_report = state.sentiment_report
    news_report = state.news_report
    fundamentals_report = state.fundamentals_report

    memory = await memory_init(name="bear-researcher")

    curr_situation = f"{market_research_report}\n\n{sentiment_report}\n\n{news_report}\n\n{fundamentals_report}"
    past_memories = memory.get_memories(curr_situation, n_matches=2)

    past_memory_str = ""
    for rec in past_memories:
        past_memory_str += rec["recommendation"] + "\n\n"

    prompt = f"""You are a Bear Analyst making the case against investing in the stock.
Your goal is to present a well-reasoned argument emphasizing risks, challenges, and negative indicators.
Leverage the provided research and data to highlight potential downsides and counter bullish arguments effectively.

Key points to focus on:

- Risks and Challenges: Highlight factors like market saturation, financial instability,
or macroeconomic threats that could hinder the stock's performance.
- Competitive Weaknesses: Emphasize vulnerabilities such as weaker market positioning, declining innovation,
or threats from competitors.
- Negative Indicators: Use evidence from financial data, market trends, or recent adverse news to support your position.
- Bull Counterpoints: Critically analyze the bull argument with specific data and sound reasoning,
exposing weaknesses or over-optimistic assumptions.
- Engagement: Present your argument in a conversational style, directly engaging with the bull analyst's points
and debating effectively rather than simply listing facts.

Resources available:

Market research report: {market_research_report}
Social media sentiment report: {sentiment_report}
Latest world affairs news: {news_report}
Company fundamentals report: {fundamentals_report}
Conversation history of the debate: {history}
Last bull argument: {current_response}
Reflections from similar situations and lessons learned: {past_memory_str}
Use this information to deliver a compelling bear argument, refute the bull's claims, and engage in a dynamic debate
that demonstrates the risks and weaknesses of investing in the stock.
You must also address reflections and learn from lessons and mistakes you made in the past.
"""

    response = ChatOpenAI(model=llm).invoke(prompt)

    argument = f"Bear Analyst: {response.content}"

    new_investment_debate_state = InvestmentDebateState(
        history=history + "\n" + argument,
        bear_history=bear_history + "\n" + argument,
        bull_history=investment_debate_state.bull_history,
        current_response=argument,
        count=investment_debate_state.count + 1,
    )

    state.investment_debate_state = new_investment_debate_state
    return state

# {{/docs-fragment bear_researcher}}

@env.task
async def create_bull_researcher(llm: str, state: AgentState) -> AgentState:
    investment_debate_state = state.investment_debate_state
    history = investment_debate_state.history
    bull_history = investment_debate_state.bull_history

    current_response = investment_debate_state.current_response
    market_research_report = state.market_report
    sentiment_report = state.sentiment_report
    news_report = state.news_report
    fundamentals_report = state.fundamentals_report

    memory = await memory_init(name="bull-researcher")

    curr_situation = f"{market_research_report}\n\n{sentiment_report}\n\n{news_report}\n\n{fundamentals_report}"
    past_memories = memory.get_memories(curr_situation, n_matches=2)

    past_memory_str = ""
    for rec in past_memories:
        past_memory_str += rec["recommendation"] + "\n\n"

    prompt = f"""You are a Bull Analyst advocating for investing in the stock.
Your task is to build a strong, evidence-based case emphasizing growth potential, competitive advantages,
and positive market indicators.
Leverage the provided research and data to address concerns and counter bearish arguments effectively.

Key points to focus on:
- Growth Potential: Highlight the company's market opportunities, revenue projections, and scalability.
- Competitive Advantages: Emphasize factors like unique products, strong branding, or dominant market positioning.
- Positive Indicators: Use financial health, industry trends, and recent positive news as evidence.
- Bear Counterpoints: Critically analyze the bear argument with specific data and sound reasoning, addressing
concerns thoroughly and showing why the bull perspective holds stronger merit.
- Engagement: Present your argument in a conversational style, engaging directly with the bear analyst's points
and debating effectively rather than just listing data.

Resources available:
Market research report: {market_research_report}
Social media sentiment report: {sentiment_report}
Latest world affairs news: {news_report}
Company fundamentals report: {fundamentals_report}
Conversation history of the debate: {history}
Last bear argument: {current_response}
Reflections from similar situations and lessons learned: {past_memory_str}
Use this information to deliver a compelling bull argument, refute the bear's concerns, and engage in a dynamic debate
that demonstrates the strengths of the bull position.
You must also address reflections and learn from lessons and mistakes you made in the past.
"""

    response = ChatOpenAI(model=llm).invoke(prompt)

    argument = f"Bull Analyst: {response.content}"

    new_investment_debate_state = InvestmentDebateState(
        history=history + "\n" + argument,
        bull_history=bull_history + "\n" + argument,
        bear_history=investment_debate_state.bear_history,
        current_response=argument,
        count=investment_debate_state.count + 1,
    )

    state.investment_debate_state = new_investment_debate_state
    return state
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/trading_agents/agents/researchers.py*

To aid reasoning, the agents can also retrieve relevant "memories" from a vector database, giving them richer historical context. The number of debate rounds is configurable, and after a few iterations of back-and-forth between the bull and bear, a research manager agent reviews their arguments and makes a final investment decision.

```
from agents.utils.utils import (
    AgentState,
    InvestmentDebateState,
    RiskDebateState,
    memory_init,
)
from flyte_env import env
from langchain_openai import ChatOpenAI

# {{docs-fragment research_manager}}
@env.task
async def create_research_manager(llm: str, state: AgentState) -> AgentState:
    history = state.investment_debate_state.history
    investment_debate_state = state.investment_debate_state
    market_research_report = state.market_report
    sentiment_report = state.sentiment_report
    news_report = state.news_report
    fundamentals_report = state.fundamentals_report

    memory = await memory_init(name="research-manager")

    curr_situation = f"{market_research_report}\n\n{sentiment_report}\n\n{news_report}\n\n{fundamentals_report}"
    past_memories = memory.get_memories(curr_situation, n_matches=2)

    past_memory_str = ""
    for rec in past_memories:
        past_memory_str += rec["recommendation"] + "\n\n"

    prompt = f"""As the portfolio manager and debate facilitator, your role is to critically evaluate
this round of debate and make a definitive decision:
align with the bear analyst, the bull analyst,
or choose Hold only if it is strongly justified based on the arguments presented.

Summarize the key points from both sides concisely, focusing on the most compelling evidence or reasoning.
Your recommendation—Buy, Sell, or Hold—must be clear and actionable.
Avoid defaulting to Hold simply because both sides have valid points;
commit to a stance grounded in the debate's strongest arguments.

Additionally, develop a detailed investment plan for the trader. This should include:

Your Recommendation: A decisive stance supported by the most convincing arguments.
Rationale: An explanation of why these arguments lead to your conclusion.
Strategic Actions: Concrete steps for implementing the recommendation.
Take into account your past mistakes on similar situations.
Use these insights to refine your decision-making and ensure you are learning and improving.
Present your analysis conversationally, as if speaking naturally, without special formatting.

Here are your past reflections on mistakes:
\"{past_memory_str}\"

Here is the debate:
Debate History:
{history}"""
    response = ChatOpenAI(model=llm).invoke(prompt)

    new_investment_debate_state = InvestmentDebateState(
        judge_decision=response.content,
        history=investment_debate_state.history,
        bear_history=investment_debate_state.bear_history,
        bull_history=investment_debate_state.bull_history,
        current_response=response.content,
        count=investment_debate_state.count,
    )

    state.investment_debate_state = new_investment_debate_state
    state.investment_plan = response.content

    return state

# {{/docs-fragment research_manager}}

@env.task
async def create_risk_manager(llm: str, state: AgentState) -> AgentState:
    history = state.risk_debate_state.history
    risk_debate_state = state.risk_debate_state
    trader_plan = state.investment_plan
    market_research_report = state.market_report
    sentiment_report = state.sentiment_report
    news_report = state.news_report
    fundamentals_report = state.fundamentals_report

    memory = await memory_init(name="risk-manager")

    curr_situation = f"{market_research_report}\n\n{sentiment_report}\n\n{news_report}\n\n{fundamentals_report}"
    past_memories = memory.get_memories(curr_situation, n_matches=2)

    past_memory_str = ""
    for rec in past_memories:
        past_memory_str += rec["recommendation"] + "\n\n"

    prompt = f"""As the Risk Management Judge and Debate Facilitator,
your goal is to evaluate the debate between three risk analysts—Risky,
Neutral, and Safe/Conservative—and determine the best course of action for the trader.
Your decision must result in a clear recommendation: Buy, Sell, or Hold.
Choose Hold only if strongly justified by specific arguments, not as a fallback when all sides seem valid.
Strive for clarity and decisiveness.

Guidelines for Decision-Making:
1. **Summarize Key Arguments**: Extract the strongest points from each analyst, focusing on relevance to the context.
2. **Provide Rationale**: Support your recommendation with direct quotes and counterarguments from the debate.
3. **Refine the Trader's Plan**: Start with the trader's original plan, **{trader_plan}**,
and adjust it based on the analysts' insights.
4. **Learn from Past Mistakes**: Use lessons from **{past_memory_str}** to address prior misjudgments
and improve the decision you are making now to make sure you don't make a wrong BUY/SELL/HOLD call that loses money.

Deliverables:
- A clear and actionable recommendation: Buy, Sell, or Hold.
- Detailed reasoning anchored in the debate and past reflections.

---

**Analysts Debate History:**
{history}

---

Focus on actionable insights and continuous improvement.
Build on past lessons, critically evaluate all perspectives, and ensure each decision advances better outcomes."""

    response = ChatOpenAI(model=llm).invoke(prompt)

    new_risk_debate_state = RiskDebateState(
        judge_decision=response.content,
        history=risk_debate_state.history,
        risky_history=risk_debate_state.risky_history,
        safe_history=risk_debate_state.safe_history,
        neutral_history=risk_debate_state.neutral_history,
        latest_speaker="Judge",
        current_risky_response=risk_debate_state.current_risky_response,
        current_safe_response=risk_debate_state.current_safe_response,
        current_neutral_response=risk_debate_state.current_neutral_response,
        count=risk_debate_state.count,
    )

    state.risk_debate_state = new_risk_debate_state
    state.final_trade_decision = response.content

    return state
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/trading_agents/agents/managers.py*

### Trading agent

The trader agent consolidates the insights from analysts and researchers to generate a final recommendation. It synthesizes competing signals and produces a conclusion such as _Buy for long-term growth despite short-term volatility_.

```
from agents.utils.utils import AgentState, memory_init
from flyte_env import env
from langchain_core.messages import convert_to_openai_messages
from langchain_openai import ChatOpenAI

# {{docs-fragment trader}}
@env.task
async def create_trader(llm: str, state: AgentState) -> AgentState:
    company_name = state.company_of_interest
    investment_plan = state.investment_plan
    market_research_report = state.market_report
    sentiment_report = state.sentiment_report
    news_report = state.news_report
    fundamentals_report = state.fundamentals_report

    memory = await memory_init(name="trader")

    curr_situation = f"{market_research_report}\n\n{sentiment_report}\n\n{news_report}\n\n{fundamentals_report}"
    past_memories = memory.get_memories(curr_situation, n_matches=2)

    past_memory_str = ""
    for rec in past_memories:
        past_memory_str += rec["recommendation"] + "\n\n"

    context = {
        "role": "user",
        "content": f"Based on a comprehensive analysis by a team of analysts, "
        f"here is an investment plan tailored for {company_name}. "
        "This plan incorporates insights from current technical market trends, "
        "macroeconomic indicators, and social media sentiment. "
        "Use this plan as a foundation for evaluating your next trading decision.\n\n"
        f"Proposed Investment Plan: {investment_plan}\n\n"
        "Leverage these insights to make an informed and strategic decision.",
    }

    messages = [
        {
            "role": "system",
            "content": f"""You are a trading agent analyzing market data to make investment decisions.
Based on your analysis, provide a specific recommendation to buy, sell, or hold.
End with a firm decision and always conclude your response with 'FINAL TRANSACTION PROPOSAL: **BUY/HOLD/SELL**'
to confirm your recommendation.
Do not forget to utilize lessons from past decisions to learn from your mistakes.
Here is some reflections from similar situatiosn you traded in and the lessons learned: {past_memory_str}""",
        },
        context,
    ]

    result = ChatOpenAI(model=llm).invoke(messages)

    state.messages.append(convert_to_openai_messages(result))
    state.trader_investment_plan = result.content
    state.sender = "Trader"

    return state

# {{/docs-fragment trader}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/trading_agents/agents/trader.py*

### Risk agents

Risk agents comprise agents with different risk tolerances: a risky debater, a neutral one, and a conservative one. They assess the portfolio through lenses like market volatility, liquidity, and systemic risk. Similar to the bull-bear debate, these agents engage in internal discussion, after which a risk manager makes the final call.

```
from agents.utils.utils import AgentState, RiskDebateState
from flyte_env import env
from langchain_openai import ChatOpenAI

# {{docs-fragment risk_debator}}
@env.task
async def create_risky_debator(llm: str, state: AgentState) -> AgentState:
    risk_debate_state = state.risk_debate_state
    history = risk_debate_state.history
    risky_history = risk_debate_state.risky_history

    current_safe_response = risk_debate_state.current_safe_response
    current_neutral_response = risk_debate_state.current_neutral_response

    market_research_report = state.market_report
    sentiment_report = state.sentiment_report
    news_report = state.news_report
    fundamentals_report = state.fundamentals_report

    trader_decision = state.trader_investment_plan

    prompt = f"""As the Risky Risk Analyst, your role is to actively champion high-reward, high-risk opportunities,
emphasizing bold strategies and competitive advantages.
When evaluating the trader's decision or plan, focus intently on the potential upside, growth potential,
and innovative benefits—even when these come with elevated risk.
Use the provided market data and sentiment analysis to strengthen your arguments and challenge the opposing views.
Specifically, respond directly to each point made by the conservative and neutral analysts,
countering with data-driven rebuttals and persuasive reasoning.
Highlight where their caution might miss critical opportunities or where their assumptions may be overly conservative.
Here is the trader's decision:

{trader_decision}

Your task is to create a compelling case for the trader's decision by questioning and critiquing the conservative
and neutral stances to demonstrate why your high-reward perspective offers the best path forward.
Incorporate insights from the following sources into your arguments:

Market Research Report: {market_research_report}
Social Media Sentiment Report: {sentiment_report}
Latest World Affairs Report: {news_report}
Company Fundamentals Report: {fundamentals_report}
Here is the current conversation history: {history}
Here are the last arguments from the conservative analyst: {current_safe_response}
Here are the last arguments from the neutral analyst: {current_neutral_response}.
If there are no responses from the other viewpoints, do not halluncinate and just present your point.

Engage actively by addressing any specific concerns raised, refuting the weaknesses in their logic,
and asserting the benefits of risk-taking to outpace market norms.
Maintain a focus on debating and persuading, not just presenting data.
Challenge each counterpoint to underscore why a high-risk approach is optimal.
Output conversationally as if you are speaking without any special formatting."""

    response = ChatOpenAI(model=llm).invoke(prompt)

    argument = f"Risky Analyst: {response.content}"

    new_risk_debate_state = RiskDebateState(
        history=history + "\n" + argument,
        risky_history=risky_history + "\n" + argument,
        safe_history=risk_debate_state.safe_history,
        neutral_history=risk_debate_state.neutral_history,
        latest_speaker="Risky",
        current_risky_response=argument,
        current_safe_response=current_safe_response,
        current_neutral_response=current_neutral_response,
        count=risk_debate_state.count + 1,
    )

    state.risk_debate_state = new_risk_debate_state
    return state

# {{/docs-fragment risk_debator}}

@env.task
async def create_safe_debator(llm: str, state: AgentState) -> AgentState:
    risk_debate_state = state.risk_debate_state
    history = risk_debate_state.history
    safe_history = risk_debate_state.safe_history

    current_risky_response = risk_debate_state.current_risky_response
    current_neutral_response = risk_debate_state.current_neutral_response

    market_research_report = state.market_report
    sentiment_report = state.sentiment_report
    news_report = state.news_report
    fundamentals_report = state.fundamentals_report

    trader_decision = state.trader_investment_plan

    prompt = f"""As the Safe/Conservative Risk Analyst, your primary objective is to protect assets,
minimize volatility, and ensure steady, reliable growth. You prioritize stability, security, and risk mitigation,
carefully assessing potential losses, economic downturns, and market volatility.
When evaluating the trader's decision or plan, critically examine high-risk elements,
pointing out where the decision may expose the firm to undue risk and where more cautious
alternatives could secure long-term gains.
Here is the trader's decision:

{trader_decision}

Your task is to actively counter the arguments of the Risky and Neutral Analysts,
highlighting where their views may overlook potential threats or fail to prioritize sustainability.
Respond directly to their points, drawing from the following data sources
to build a convincing case for a low-risk approach adjustment to the trader's decision:

Market Research Report: {market_research_report}
Social Media Sentiment Report: {sentiment_report}
Latest World Affairs Report: {news_report}
Company Fundamentals Report: {fundamentals_report}
Here is the current conversation history: {history}
Here is the last response from the risky analyst: {current_risky_response}
Here is the last response from the neutral analyst: {current_neutral_response}.
If there are no responses from the other viewpoints, do not halluncinate and just present your point.

Engage by questioning their optimism and emphasizing the potential downsides they may have overlooked.
Address each of their counterpoints to showcase why a conservative stance is ultimately the
safest path for the firm's assets.
Focus on debating and critiquing their arguments to demonstrate the strength of a low-risk strategy
over their approaches.
Output conversationally as if you are speaking without any special formatting."""

    response = ChatOpenAI(model=llm).invoke(prompt)

    argument = f"Safe Analyst: {response.content}"

    new_risk_debate_state = RiskDebateState(
        history=history + "\n" + argument,
        risky_history=risk_debate_state.risky_history,
        safe_history=safe_history + "\n" + argument,
        neutral_history=risk_debate_state.neutral_history,
        latest_speaker="Safe",
        current_risky_response=current_risky_response,
        current_safe_response=argument,
        current_neutral_response=current_neutral_response,
        count=risk_debate_state.count + 1,
    )

    state.risk_debate_state = new_risk_debate_state
    return state

@env.task
async def create_neutral_debator(llm: str, state: AgentState) -> AgentState:
    risk_debate_state = state.risk_debate_state
    history = risk_debate_state.history
    neutral_history = risk_debate_state.neutral_history

    current_risky_response = risk_debate_state.current_risky_response
    current_safe_response = risk_debate_state.current_safe_response

    market_research_report = state.market_report
    sentiment_report = state.sentiment_report
    news_report = state.news_report
    fundamentals_report = state.fundamentals_report

    trader_decision = state.trader_investment_plan

    prompt = f"""As the Neutral Risk Analyst, your role is to provide a balanced perspective,
weighing both the potential benefits and risks of the trader's decision or plan.
You prioritize a well-rounded approach, evaluating the upsides
and downsides while factoring in broader market trends,
potential economic shifts, and diversification strategies.Here is the trader's decision:

{trader_decision}

Your task is to challenge both the Risky and Safe Analysts,
pointing out where each perspective may be overly optimistic or overly cautious.
Use insights from the following data sources to support a moderate, sustainable strategy
to adjust the trader's decision:

Market Research Report: {market_research_report}
Social Media Sentiment Report: {sentiment_report}
Latest World Affairs Report: {news_report}
Company Fundamentals Report: {fundamentals_report}
Here is the current conversation history: {history}
Here is the last response from the risky analyst: {current_risky_response}
Here is the last response from the safe analyst: {current_safe_response}.
If there are no responses from the other viewpoints, do not halluncinate and just present your point.

Engage actively by analyzing both sides critically, addressing weaknesses in the risky
and conservative arguments to advocate for a more balanced approach.
Challenge each of their points to illustrate why a moderate risk strategy might offer the best of both worlds,
providing growth potential while safeguarding against extreme volatility.
Focus on debating rather than simply presenting data, aiming to show that a balanced view can lead to
the most reliable outcomes. Output conversationally as if you are speaking without any special formatting."""

    response = ChatOpenAI(model=llm).invoke(prompt)

    argument = f"Neutral Analyst: {response.content}"

    new_risk_debate_state = RiskDebateState(
        history=history + "\n" + argument,
        risky_history=risk_debate_state.risky_history,
        safe_history=risk_debate_state.safe_history,
        neutral_history=neutral_history + "\n" + argument,
        latest_speaker="Neutral",
        current_risky_response=current_risky_response,
        current_safe_response=current_safe_response,
        current_neutral_response=argument,
        count=risk_debate_state.count + 1,
    )

    state.risk_debate_state = new_risk_debate_state
    return state
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/trading_agents/agents/risk_debators.py*

The outcome of the risk manager — whether to proceed with the trade or not — is considered the final decision of the trading simulation.

You can visualize this full pipeline in the Flyte/Union UI, where every step is logged.
You’ll see input/output metadata for each tool and agent task.
Thanks to Flyte's caching, repeated steps are skipped unless inputs change, saving time and compute resources.

### Retaining agent memory with S3 vectors

To help agents learn from past decisions, we persist their memory in a vector store. In this example, we use an [S3 vector](https://aws.amazon.com/s3/features/vectors/) bucket for their simplicity and tight integration with Flyte and Union, but any vector database can be used.

Note: To use the S3 vector store, make sure your IAM role has the following permissions configured:

```
s3vectors:CreateVectorBucket
s3vectors:CreateIndex
s3vectors:PutVectors
s3vectors:GetIndex
s3vectors:GetVectors
s3vectors:QueryVectors
s3vectors:GetVectorBucket
```

After each trade decision, you can run a `reflect_on_decisions` task. This evaluates whether the final outcome aligned with the agent's recommendation and stores that reflection in the vector store. These stored insights can later be retrieved to provide historical context and improve future decision-making.

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#     "flyte>=2.0.0b52",
#     "akshare==1.16.98",
#     "backtrader==1.9.78.123",
#     "boto3==1.39.9",
#     "chainlit==2.5.5",
#     "eodhd==1.0.32",
#     "feedparser==6.0.11",
#     "finnhub-python==2.4.23",
#     "langchain-experimental==0.3.4",
#     "langchain-openai==0.3.23",
#     "pandas==2.3.0",
#     "parsel==1.10.0",
#     "praw==7.8.1",
#     "pytz==2025.2",
#     "questionary==2.1.0",
#     "redis==6.2.0",
#     "requests==2.32.4",
#     "stockstats==0.6.5",
#     "tqdm==4.67.1",
#     "tushare==1.4.21",
#     "typing-extensions==4.14.0",
#     "yfinance==0.2.63",
# ]
# main = "main"
# params = ""
# ///
import asyncio
from copy import deepcopy

import agents
import agents.analysts
from agents.managers import create_research_manager, create_risk_manager
from agents.researchers import create_bear_researcher, create_bull_researcher
from agents.risk_debators import (
    create_neutral_debator,
    create_risky_debator,
    create_safe_debator,
)
from agents.trader import create_trader
from agents.utils.utils import AgentState
from flyte_env import DEEP_THINKING_LLM, QUICK_THINKING_LLM, env, flyte
from langchain_openai import ChatOpenAI
from reflection import (
    reflect_bear_researcher,
    reflect_bull_researcher,
    reflect_research_manager,
    reflect_risk_manager,
    reflect_trader,
)

@env.task
async def process_signal(full_signal: str, QUICK_THINKING_LLM: str) -> str:
    """Process a full trading signal to extract the core decision."""

    messages = [
        {
            "role": "system",
            "content": """You are an efficient assistant designed to analyze paragraphs or
financial reports provided by a group of analysts.
Your task is to extract the investment decision: SELL, BUY, or HOLD.
Provide only the extracted decision (SELL, BUY, or HOLD) as your output,
without adding any additional text or information.""",
        },
        {"role": "human", "content": full_signal},
    ]

    return ChatOpenAI(model=QUICK_THINKING_LLM).invoke(messages).content

async def run_analyst(analyst_name, state, online_tools):
    # Create a copy of the state for isolation
    run_fn = getattr(agents.analysts, f"create_{analyst_name}_analyst")

    # Run the analyst's chain
    result_state = await run_fn(QUICK_THINKING_LLM, state, online_tools)

    # Determine the report key
    report_key = (
        "sentiment_report"
        if analyst_name == "social_media"
        else f"{analyst_name}_report"
    )
    report_value = getattr(result_state, report_key)

    return result_state.messages[1:], report_key, report_value

# {{docs-fragment main}}
@env.task
async def main(
    selected_analysts: list[str] = [
        "market",
        "fundamentals",
        "news",
        "social_media",
    ],
    max_debate_rounds: int = 1,
    max_risk_discuss_rounds: int = 1,
    online_tools: bool = True,
    company_name: str = "NVDA",
    trade_date: str = "2024-05-12",
) -> tuple[str, AgentState]:
    if not selected_analysts:
        raise ValueError(
            "No analysts selected. Please select at least one analyst from market, fundamentals, news, or social_media."
        )

    state = AgentState(
        messages=[{"role": "human", "content": company_name}],
        company_of_interest=company_name,
        trade_date=str(trade_date),
    )

    # Run all analysts concurrently
    results = await asyncio.gather(
        *[
            run_analyst(analyst, deepcopy(state), online_tools)
            for analyst in selected_analysts
        ]
    )

    # Flatten and append all resulting messages into the shared state
    for messages, report_attr, report in results:
        state.messages.extend(messages)
        setattr(state, report_attr, report)

    # Bull/Bear debate loop
    state = await create_bull_researcher(QUICK_THINKING_LLM, state)  # Start with bull
    while state.investment_debate_state.count < 2 * max_debate_rounds:
        current = state.investment_debate_state.current_response
        if current.startswith("Bull"):
            state = await create_bear_researcher(QUICK_THINKING_LLM, state)
        else:
            state = await create_bull_researcher(QUICK_THINKING_LLM, state)

    state = await create_research_manager(DEEP_THINKING_LLM, state)
    state = await create_trader(QUICK_THINKING_LLM, state)

    # Risk debate loop
    state = await create_risky_debator(QUICK_THINKING_LLM, state)  # Start with risky
    while state.risk_debate_state.count < 3 * max_risk_discuss_rounds:
        speaker = state.risk_debate_state.latest_speaker
        if speaker == "Risky":
            state = await create_safe_debator(QUICK_THINKING_LLM, state)
        elif speaker == "Safe":
            state = await create_neutral_debator(QUICK_THINKING_LLM, state)
        else:
            state = await create_risky_debator(QUICK_THINKING_LLM, state)

    state = await create_risk_manager(DEEP_THINKING_LLM, state)
    decision = await process_signal(state.final_trade_decision, QUICK_THINKING_LLM)

    return decision, state

# {{/docs-fragment main}}

# {{docs-fragment reflect_on_decisions}}
@env.task
async def reflect_and_store(state: AgentState, returns: str) -> str:
    await asyncio.gather(
        reflect_bear_researcher(state, returns),
        reflect_bull_researcher(state, returns),
        reflect_trader(state, returns),
        reflect_risk_manager(state, returns),
        reflect_research_manager(state, returns),
    )

    return "Reflection completed."

# Run the reflection task after the main function
@env.task(cache="disable")
async def reflect_on_decisions(
    returns: str,
    selected_analysts: list[str] = [
        "market",
        "fundamentals",
        "news",
        "social_media",
    ],
    max_debate_rounds: int = 1,
    max_risk_discuss_rounds: int = 1,
    online_tools: bool = True,
    company_name: str = "NVDA",
    trade_date: str = "2024-05-12",
) -> str:
    _, state = await main(
        selected_analysts,
        max_debate_rounds,
        max_risk_discuss_rounds,
        online_tools,
        company_name,
        trade_date,
    )

    return await reflect_and_store(state, returns)

# {{/docs-fragment reflect_on_decisions}}

# {{docs-fragment execute_main}}
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
    run.wait()

    # run = flyte.run(reflect_on_decisions, "+3.2% gain over 5 days")
    # print(run.url)

# {{/docs-fragment execute_main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/trading_agents/main.py*

### Running the simulation

First, set up your OpenAI secret (from [openai.com](https://platform.openai.com/api-keys)) and Finnhub API key (from [finnhub.io](https://finnhub.io/)):

```
flyte create secret openai_api_key <YOUR_OPENAI_API_KEY>
flyte create secret finnhub_api_key <YOUR_FINNHUB_API_KEY>
```

Then [clone the repo](https://github.com/unionai/unionai-examples), navigate to the `tutorials-v2/trading_agents` directory, and run the following commands:

```
flyte create config --endpoint <FLYTE_OR_UNION_ENDPOINT> --project <PROJECT_NAME> --domain <DOMAIN_NAME> --builder remote
uv run main.py
```

If you'd like to run the `reflect_on_decisions` task instead, comment out the `main` function call and uncomment the `reflect_on_decisions` call in the `__main__` block:

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#     "flyte>=2.0.0b52",
#     "akshare==1.16.98",
#     "backtrader==1.9.78.123",
#     "boto3==1.39.9",
#     "chainlit==2.5.5",
#     "eodhd==1.0.32",
#     "feedparser==6.0.11",
#     "finnhub-python==2.4.23",
#     "langchain-experimental==0.3.4",
#     "langchain-openai==0.3.23",
#     "pandas==2.3.0",
#     "parsel==1.10.0",
#     "praw==7.8.1",
#     "pytz==2025.2",
#     "questionary==2.1.0",
#     "redis==6.2.0",
#     "requests==2.32.4",
#     "stockstats==0.6.5",
#     "tqdm==4.67.1",
#     "tushare==1.4.21",
#     "typing-extensions==4.14.0",
#     "yfinance==0.2.63",
# ]
# main = "main"
# params = ""
# ///
import asyncio
from copy import deepcopy

import agents
import agents.analysts
from agents.managers import create_research_manager, create_risk_manager
from agents.researchers import create_bear_researcher, create_bull_researcher
from agents.risk_debators import (
    create_neutral_debator,
    create_risky_debator,
    create_safe_debator,
)
from agents.trader import create_trader
from agents.utils.utils import AgentState
from flyte_env import DEEP_THINKING_LLM, QUICK_THINKING_LLM, env, flyte
from langchain_openai import ChatOpenAI
from reflection import (
    reflect_bear_researcher,
    reflect_bull_researcher,
    reflect_research_manager,
    reflect_risk_manager,
    reflect_trader,
)

@env.task
async def process_signal(full_signal: str, QUICK_THINKING_LLM: str) -> str:
    """Process a full trading signal to extract the core decision."""

    messages = [
        {
            "role": "system",
            "content": """You are an efficient assistant designed to analyze paragraphs or
financial reports provided by a group of analysts.
Your task is to extract the investment decision: SELL, BUY, or HOLD.
Provide only the extracted decision (SELL, BUY, or HOLD) as your output,
without adding any additional text or information.""",
        },
        {"role": "human", "content": full_signal},
    ]

    return ChatOpenAI(model=QUICK_THINKING_LLM).invoke(messages).content

async def run_analyst(analyst_name, state, online_tools):
    # Create a copy of the state for isolation
    run_fn = getattr(agents.analysts, f"create_{analyst_name}_analyst")

    # Run the analyst's chain
    result_state = await run_fn(QUICK_THINKING_LLM, state, online_tools)

    # Determine the report key
    report_key = (
        "sentiment_report"
        if analyst_name == "social_media"
        else f"{analyst_name}_report"
    )
    report_value = getattr(result_state, report_key)

    return result_state.messages[1:], report_key, report_value

# {{docs-fragment main}}
@env.task
async def main(
    selected_analysts: list[str] = [
        "market",
        "fundamentals",
        "news",
        "social_media",
    ],
    max_debate_rounds: int = 1,
    max_risk_discuss_rounds: int = 1,
    online_tools: bool = True,
    company_name: str = "NVDA",
    trade_date: str = "2024-05-12",
) -> tuple[str, AgentState]:
    if not selected_analysts:
        raise ValueError(
            "No analysts selected. Please select at least one analyst from market, fundamentals, news, or social_media."
        )

    state = AgentState(
        messages=[{"role": "human", "content": company_name}],
        company_of_interest=company_name,
        trade_date=str(trade_date),
    )

    # Run all analysts concurrently
    results = await asyncio.gather(
        *[
            run_analyst(analyst, deepcopy(state), online_tools)
            for analyst in selected_analysts
        ]
    )

    # Flatten and append all resulting messages into the shared state
    for messages, report_attr, report in results:
        state.messages.extend(messages)
        setattr(state, report_attr, report)

    # Bull/Bear debate loop
    state = await create_bull_researcher(QUICK_THINKING_LLM, state)  # Start with bull
    while state.investment_debate_state.count < 2 * max_debate_rounds:
        current = state.investment_debate_state.current_response
        if current.startswith("Bull"):
            state = await create_bear_researcher(QUICK_THINKING_LLM, state)
        else:
            state = await create_bull_researcher(QUICK_THINKING_LLM, state)

    state = await create_research_manager(DEEP_THINKING_LLM, state)
    state = await create_trader(QUICK_THINKING_LLM, state)

    # Risk debate loop
    state = await create_risky_debator(QUICK_THINKING_LLM, state)  # Start with risky
    while state.risk_debate_state.count < 3 * max_risk_discuss_rounds:
        speaker = state.risk_debate_state.latest_speaker
        if speaker == "Risky":
            state = await create_safe_debator(QUICK_THINKING_LLM, state)
        elif speaker == "Safe":
            state = await create_neutral_debator(QUICK_THINKING_LLM, state)
        else:
            state = await create_risky_debator(QUICK_THINKING_LLM, state)

    state = await create_risk_manager(DEEP_THINKING_LLM, state)
    decision = await process_signal(state.final_trade_decision, QUICK_THINKING_LLM)

    return decision, state

# {{/docs-fragment main}}

# {{docs-fragment reflect_on_decisions}}
@env.task
async def reflect_and_store(state: AgentState, returns: str) -> str:
    await asyncio.gather(
        reflect_bear_researcher(state, returns),
        reflect_bull_researcher(state, returns),
        reflect_trader(state, returns),
        reflect_risk_manager(state, returns),
        reflect_research_manager(state, returns),
    )

    return "Reflection completed."

# Run the reflection task after the main function
@env.task(cache="disable")
async def reflect_on_decisions(
    returns: str,
    selected_analysts: list[str] = [
        "market",
        "fundamentals",
        "news",
        "social_media",
    ],
    max_debate_rounds: int = 1,
    max_risk_discuss_rounds: int = 1,
    online_tools: bool = True,
    company_name: str = "NVDA",
    trade_date: str = "2024-05-12",
) -> str:
    _, state = await main(
        selected_analysts,
        max_debate_rounds,
        max_risk_discuss_rounds,
        online_tools,
        company_name,
        trade_date,
    )

    return await reflect_and_store(state, returns)

# {{/docs-fragment reflect_on_decisions}}

# {{docs-fragment execute_main}}
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
    run.wait()

    # run = flyte.run(reflect_on_decisions, "+3.2% gain over 5 days")
    # print(run.url)

# {{/docs-fragment execute_main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/trading_agents/main.py*

Then run:

```
uv run main.py
```

## Why Flyte? _(A quick note before you go)_

You might now be wondering: can't I just build all this with Python and LangChain?
Absolutely. But as your project grows, you'll likely run into these challenges:

1.  **Observability**: Agent workflows can feel opaque. You send a prompt, get a response, but what happened in between?

    - Were the right tools used?
    - Were correct arguments passed?
    - How did the LLM reason through intermediate steps?
    - Why did it fail?

    Flyte gives you a window into each of these stages.

2.  **Multi-agent coordination**: Real-world applications often require multiple agents with distinct roles and responsibilities. In such cases, you'll need:

    - Isolated state per agent,
    - Shared context where needed,
    - And coordination — sequential or parallel.

    Managing this manually gets fragile, fast. Flyte handles it for you.

3.  **Scalability**: Agents and tools might need to run in isolated or containerized environments. Whether you're scaling out to more agents or more powerful hardware, Flyte lets you scale without taxing your local machine or racking up unnecessary cloud bills.
4.  **Durability & recovery**: LLM-based workflows are often long-running and expensive. If something fails halfway:

    - Do you lose all progress?
    - Replay everything from scratch?

    With Flyte, you get built-in caching, checkpointing, and recovery, so you can resume where you left off.


=== PAGE: https://www.union.ai/docs/v2/union/tutorials/code-agent ===

# Run LLM-generated code

> [!NOTE]
> Code available [here](https://github.com/unionai/unionai-examples/tree/main/v2/tutorials/code_runner).

This example demonstrates how to run code generated by a large language model (LLM) using a `ContainerTask`.
The agent takes a user’s question, generates Flyte 2 code using the Flyte 2 documentation as context, and runs it in an isolated container.
If the execution fails, the agent reflects on the error and retries
up to a configurable limit until it succeeds.

Using `ContainerTask` ensures that all generated code runs in a secure environment.
This gives you full flexibility to execute arbitrary logic safely and reliably.

## What this example demonstrates

- How to combine LLM generation with programmatic execution.
- How to run untrusted or dynamically generated code securely.
- How to iteratively improve code using agent-like behavior.

## Setting up the agent environment

Let's start by importing the necessary libraries and setting up two environments: one for the container task and another for the agent task.
This example follows the `uv` script format to declare dependencies.

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b23",
#    "langchain-core==0.3.66",
#    "langchain-openai==0.3.24",
#    "langchain-community==0.3.26",
#    "beautifulsoup4==4.13.4",
#    "docker==7.1.0",
# ]
# ///
```

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "langchain-core==0.3.66",
#    "langchain-openai==0.3.24",
#    "langchain-community==0.3.26",
#    "beautifulsoup4==4.13.4",
#    "docker==7.1.0",
# ]
# main = "main"
# params = ""
# ///

# {{docs-fragment code_runner_task}}
import flyte
from flyte.extras import ContainerTask
from flyte.io import File

code_runner_task = ContainerTask(
    name="run_flyte_v2",
    image=flyte.Image.from_debian_base(),
    input_data_dir="/var/inputs",
    output_data_dir="/var/outputs",
    inputs={"script": File},
    outputs={"result": str, "exit_code": str},
    command=[
        "/bin/bash",
        "-c",
        (
            "set -o pipefail && "
            "uv run --script /var/inputs/script > /var/outputs/result 2>&1; "
            "echo $? > /var/outputs/exit_code"
        ),
    ],
    resources=flyte.Resources(cpu=1, memory="1Gi"),
)

# {{/docs-fragment code_runner_task}}

# {{docs-fragment env}}
import tempfile
from typing import Optional

from langchain_core.runnables import Runnable
from pydantic import BaseModel, Field

container_env = flyte.TaskEnvironment.from_task(
    "code-runner-container", code_runner_task
)

env = flyte.TaskEnvironment(
    name="code_runner",
    secrets=[flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY")],
    image=flyte.Image.from_uv_script(__file__, name="code-runner-agent"),
    resources=flyte.Resources(cpu=1),
    depends_on=[container_env],
)

# {{/docs-fragment env}}

# {{docs-fragment code_base_model}}
class Code(BaseModel):
    """Schema for code solutions to questions about Flyte v2."""

    prefix: str = Field(
        default="", description="Description of the problem and approach"
    )
    imports: str = Field(
        default="", description="Code block with just import statements"
    )
    code: str = Field(
        default="", description="Code block not including import statements"
    )

# {{/docs-fragment code_base_model}}

# {{docs-fragment agent_state}}
class AgentState(BaseModel):
    messages: list[dict[str, str]] = Field(default_factory=list)
    generation: Code = Field(default_factory=Code)
    iterations: int = 0
    error: str = "no"
    output: Optional[str] = None

# {{/docs-fragment agent_state}}

# {{docs-fragment generate_code_gen_chain}}
async def generate_code_gen_chain(debug: bool) -> Runnable:
    from langchain_core.prompts import ChatPromptTemplate
    from langchain_openai import ChatOpenAI

    # Grader prompt
    code_gen_prompt = ChatPromptTemplate.from_messages(
        [
            (
                "system",
                """
You are a coding assistant with expertise in Python.
You are able to execute the Flyte v2 code locally in a sandbox environment.

Use the following pattern to execute the code:

<code>
if __name__ == "__main__":
    flyte.init_from_config()
    print(flyte.run(...))
</code>

Your response will be shown to the user.
Here is a full set of documentation:

-------
{context}
-------

Answer the user question based on the above provided documentation.
Ensure any code you provide can be executed with all required imports and variables defined.
Structure your answer with a description of the code solution.
Then list the imports. And finally list the functioning code block.
Here is the user question:""",
            ),
            ("placeholder", "{messages}"),
        ]
    )

    expt_llm = "gpt-4o" if not debug else "gpt-4o-mini"
    llm = ChatOpenAI(temperature=0, model=expt_llm)

    code_gen_chain = code_gen_prompt | llm.with_structured_output(Code)
    return code_gen_chain

# {{/docs-fragment generate_code_gen_chain}}

# {{docs-fragment docs_retriever}}
@env.task
async def docs_retriever(url: str) -> str:
    from bs4 import BeautifulSoup
    from langchain_community.document_loaders.recursive_url_loader import (
        RecursiveUrlLoader,
    )

    loader = RecursiveUrlLoader(
        url=url, max_depth=20, extractor=lambda x: BeautifulSoup(x, "html.parser").text
    )
    docs = loader.load()

    # Sort the list based on the URLs and get the text
    d_sorted = sorted(docs, key=lambda x: x.metadata["source"])
    d_reversed = list(reversed(d_sorted))

    concatenated_content = "\n\n\n --- \n\n\n".join(
        [doc.page_content for doc in d_reversed]
    )
    return concatenated_content

# {{/docs-fragment docs_retriever}}

# {{docs-fragment generate}}
@env.task
async def generate(
    question: str, state: AgentState, concatenated_content: str, debug: bool
) -> AgentState:
    """
    Generate a code solution

    Args:
        question (str): The user question
        state (dict): The current graph state
        concatenated_content (str): The concatenated docs content
        debug (bool): Debug mode

    Returns:
        state (dict): New key added to state, generation
    """

    print("---GENERATING CODE SOLUTION---")

    messages = state.messages
    iterations = state.iterations
    error = state.error

    # We have been routed back to generation with an error
    if error == "yes":
        messages += [
            {
                "role": "user",
                "content": (
                    "Now, try again. Invoke the code tool to structure the output "
                    "with a prefix, imports, and code block:"
                ),
            }
        ]

    code_gen_chain = await generate_code_gen_chain(debug)

    # Solution
    code_solution = code_gen_chain.invoke(
        {
            "context": concatenated_content,
            "messages": (
                messages if messages else [{"role": "user", "content": question}]
            ),
        }
    )

    messages += [
        {
            "role": "assistant",
            "content": f"{code_solution.prefix} \n Imports: {code_solution.imports} \n Code: {code_solution.code}",
        }
    ]

    return AgentState(
        messages=messages,
        generation=code_solution,
        iterations=iterations + 1,
        error=error,
        output=state.output,
    )

# {{/docs-fragment generate}}

# {{docs-fragment code_check}}
@env.task
async def code_check(state: AgentState) -> AgentState:
    """
    Check code

    Args:
        state (dict): The current graph state

    Returns:
        state (dict): New key added to state, error
    """

    print("---CHECKING CODE---")

    # State
    messages = state.messages
    code_solution = state.generation
    iterations = state.iterations

    # Get solution components
    imports = code_solution.imports.strip()
    code = code_solution.code.strip()

    # Create temp file for imports
    with tempfile.NamedTemporaryFile(
        mode="w", suffix=".py", delete=False
    ) as imports_file:
        imports_file.write(imports + "\n")
        imports_path = imports_file.name

    # Create temp file for code body
    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as code_file:
        code_file.write(imports + "\n" + code + "\n")
        code_path = code_file.name

    # Check imports
    import_output, import_exit_code = await code_runner_task(
        script=await File.from_local(imports_path)
    )

    if import_exit_code.strip() != "0":
        print("---CODE IMPORT CHECK: FAILED---")
        error_message = [
            {
                "role": "user",
                "content": f"Your solution failed the import test: {import_output}",
            }
        ]
        messages += error_message
        return AgentState(
            generation=code_solution,
            messages=messages,
            iterations=iterations,
            error="yes",
            output=import_output,
        )
    else:
        print("---CODE IMPORT CHECK: PASSED---")

    # Check execution
    code_output, code_exit_code = await code_runner_task(
        script=await File.from_local(code_path)
    )

    if code_exit_code.strip() != "0":
        print("---CODE BLOCK CHECK: FAILED---")
        error_message = [
            {
                "role": "user",
                "content": f"Your solution failed the code execution test: {code_output}",
            }
        ]
        messages += error_message
        return AgentState(
            generation=code_solution,
            messages=messages,
            iterations=iterations,
            error="yes",
            output=code_output,
        )
    else:
        print("---CODE BLOCK CHECK: PASSED---")

    # No errors
    print("---NO CODE TEST FAILURES---")

    return AgentState(
        generation=code_solution,
        messages=messages,
        iterations=iterations,
        error="no",
        output=code_output,
    )

# {{/docs-fragment code_check}}

# {{docs-fragment reflect}}
@env.task
async def reflect(
    state: AgentState, concatenated_content: str, debug: bool
) -> AgentState:
    """
    Reflect on errors

    Args:
        state (dict): The current graph state
        concatenated_content (str): Concatenated docs content
        debug (bool): Debug mode

    Returns:
        state (dict): New key added to state, reflection
    """

    print("---REFLECTING---")

    # State
    messages = state.messages
    iterations = state.iterations
    code_solution = state.generation

    # Prompt reflection
    code_gen_chain = await generate_code_gen_chain(debug)

    # Add reflection
    reflections = code_gen_chain.invoke(
        {"context": concatenated_content, "messages": messages}
    )

    messages += [
        {
            "role": "assistant",
            "content": f"Here are reflections on the error: {reflections}",
        }
    ]

    return AgentState(
        generation=code_solution,
        messages=messages,
        iterations=iterations,
        error=state.error,
        output=state.output,
    )

# {{/docs-fragment reflect}}

# {{docs-fragment main}}
@env.task
async def main(
    question: str = (
        "Define a two-task pattern where the second catches OOM from the first and retries with more memory."
    ),
    url: str = "https://pre-release-v2.docs-builder.pages.dev/docs/byoc/user-guide/",
    max_iterations: int = 3,
    debug: bool = False,
) -> str:
    concatenated_content = await docs_retriever(url=url)

    state: AgentState = AgentState()
    iterations = 0

    while True:
        with flyte.group(f"code-generation-pass-{iterations + 1}"):
            state = await generate(question, state, concatenated_content, debug)
            state = await code_check(state)

            error = state.error
            iterations = state.iterations

            if error == "no" or iterations >= max_iterations:
                print("---DECISION: FINISH---")
                code_solution = state.generation

                prefix = code_solution.prefix
                imports = code_solution.imports
                code = code_solution.code

                code_output = state.output

                return f"""{prefix}

{imports}
{code}

Result of code execution:
{code_output}
"""
            else:
                print("---DECISION: RE-TRY SOLUTION---")
                state = await reflect(state, concatenated_content, debug)

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
    run.wait()

# {{/docs-fragment main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/code_runner/agent.py*

> [!NOTE]
> You can set up access to the OpenAI API using a Flyte secret.
>
> ```
> flyte create secret openai_api_key <YOUR_OPENAI_API_KEY>
> ```

We store the LLM-generated code in a structured format. This allows us to:

- Enforce consistent formatting
- Make debugging easier
- Log and analyze generations systematically

By capturing metadata alongside the raw code, we maintain transparency and make it easier to iterate or trace issues over time.

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "langchain-core==0.3.66",
#    "langchain-openai==0.3.24",
#    "langchain-community==0.3.26",
#    "beautifulsoup4==4.13.4",
#    "docker==7.1.0",
# ]
# main = "main"
# params = ""
# ///

# {{docs-fragment code_runner_task}}
import flyte
from flyte.extras import ContainerTask
from flyte.io import File

code_runner_task = ContainerTask(
    name="run_flyte_v2",
    image=flyte.Image.from_debian_base(),
    input_data_dir="/var/inputs",
    output_data_dir="/var/outputs",
    inputs={"script": File},
    outputs={"result": str, "exit_code": str},
    command=[
        "/bin/bash",
        "-c",
        (
            "set -o pipefail && "
            "uv run --script /var/inputs/script > /var/outputs/result 2>&1; "
            "echo $? > /var/outputs/exit_code"
        ),
    ],
    resources=flyte.Resources(cpu=1, memory="1Gi"),
)

# {{/docs-fragment code_runner_task}}

# {{docs-fragment env}}
import tempfile
from typing import Optional

from langchain_core.runnables import Runnable
from pydantic import BaseModel, Field

container_env = flyte.TaskEnvironment.from_task(
    "code-runner-container", code_runner_task
)

env = flyte.TaskEnvironment(
    name="code_runner",
    secrets=[flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY")],
    image=flyte.Image.from_uv_script(__file__, name="code-runner-agent"),
    resources=flyte.Resources(cpu=1),
    depends_on=[container_env],
)

# {{/docs-fragment env}}

# {{docs-fragment code_base_model}}
class Code(BaseModel):
    """Schema for code solutions to questions about Flyte v2."""

    prefix: str = Field(
        default="", description="Description of the problem and approach"
    )
    imports: str = Field(
        default="", description="Code block with just import statements"
    )
    code: str = Field(
        default="", description="Code block not including import statements"
    )

# {{/docs-fragment code_base_model}}

# {{docs-fragment agent_state}}
class AgentState(BaseModel):
    messages: list[dict[str, str]] = Field(default_factory=list)
    generation: Code = Field(default_factory=Code)
    iterations: int = 0
    error: str = "no"
    output: Optional[str] = None

# {{/docs-fragment agent_state}}

# {{docs-fragment generate_code_gen_chain}}
async def generate_code_gen_chain(debug: bool) -> Runnable:
    from langchain_core.prompts import ChatPromptTemplate
    from langchain_openai import ChatOpenAI

    # Grader prompt
    code_gen_prompt = ChatPromptTemplate.from_messages(
        [
            (
                "system",
                """
You are a coding assistant with expertise in Python.
You are able to execute the Flyte v2 code locally in a sandbox environment.

Use the following pattern to execute the code:

<code>
if __name__ == "__main__":
    flyte.init_from_config()
    print(flyte.run(...))
</code>

Your response will be shown to the user.
Here is a full set of documentation:

-------
{context}
-------

Answer the user question based on the above provided documentation.
Ensure any code you provide can be executed with all required imports and variables defined.
Structure your answer with a description of the code solution.
Then list the imports. And finally list the functioning code block.
Here is the user question:""",
            ),
            ("placeholder", "{messages}"),
        ]
    )

    expt_llm = "gpt-4o" if not debug else "gpt-4o-mini"
    llm = ChatOpenAI(temperature=0, model=expt_llm)

    code_gen_chain = code_gen_prompt | llm.with_structured_output(Code)
    return code_gen_chain

# {{/docs-fragment generate_code_gen_chain}}

# {{docs-fragment docs_retriever}}
@env.task
async def docs_retriever(url: str) -> str:
    from bs4 import BeautifulSoup
    from langchain_community.document_loaders.recursive_url_loader import (
        RecursiveUrlLoader,
    )

    loader = RecursiveUrlLoader(
        url=url, max_depth=20, extractor=lambda x: BeautifulSoup(x, "html.parser").text
    )
    docs = loader.load()

    # Sort the list based on the URLs and get the text
    d_sorted = sorted(docs, key=lambda x: x.metadata["source"])
    d_reversed = list(reversed(d_sorted))

    concatenated_content = "\n\n\n --- \n\n\n".join(
        [doc.page_content for doc in d_reversed]
    )
    return concatenated_content

# {{/docs-fragment docs_retriever}}

# {{docs-fragment generate}}
@env.task
async def generate(
    question: str, state: AgentState, concatenated_content: str, debug: bool
) -> AgentState:
    """
    Generate a code solution

    Args:
        question (str): The user question
        state (dict): The current graph state
        concatenated_content (str): The concatenated docs content
        debug (bool): Debug mode

    Returns:
        state (dict): New key added to state, generation
    """

    print("---GENERATING CODE SOLUTION---")

    messages = state.messages
    iterations = state.iterations
    error = state.error

    # We have been routed back to generation with an error
    if error == "yes":
        messages += [
            {
                "role": "user",
                "content": (
                    "Now, try again. Invoke the code tool to structure the output "
                    "with a prefix, imports, and code block:"
                ),
            }
        ]

    code_gen_chain = await generate_code_gen_chain(debug)

    # Solution
    code_solution = code_gen_chain.invoke(
        {
            "context": concatenated_content,
            "messages": (
                messages if messages else [{"role": "user", "content": question}]
            ),
        }
    )

    messages += [
        {
            "role": "assistant",
            "content": f"{code_solution.prefix} \n Imports: {code_solution.imports} \n Code: {code_solution.code}",
        }
    ]

    return AgentState(
        messages=messages,
        generation=code_solution,
        iterations=iterations + 1,
        error=error,
        output=state.output,
    )

# {{/docs-fragment generate}}

# {{docs-fragment code_check}}
@env.task
async def code_check(state: AgentState) -> AgentState:
    """
    Check code

    Args:
        state (dict): The current graph state

    Returns:
        state (dict): New key added to state, error
    """

    print("---CHECKING CODE---")

    # State
    messages = state.messages
    code_solution = state.generation
    iterations = state.iterations

    # Get solution components
    imports = code_solution.imports.strip()
    code = code_solution.code.strip()

    # Create temp file for imports
    with tempfile.NamedTemporaryFile(
        mode="w", suffix=".py", delete=False
    ) as imports_file:
        imports_file.write(imports + "\n")
        imports_path = imports_file.name

    # Create temp file for code body
    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as code_file:
        code_file.write(imports + "\n" + code + "\n")
        code_path = code_file.name

    # Check imports
    import_output, import_exit_code = await code_runner_task(
        script=await File.from_local(imports_path)
    )

    if import_exit_code.strip() != "0":
        print("---CODE IMPORT CHECK: FAILED---")
        error_message = [
            {
                "role": "user",
                "content": f"Your solution failed the import test: {import_output}",
            }
        ]
        messages += error_message
        return AgentState(
            generation=code_solution,
            messages=messages,
            iterations=iterations,
            error="yes",
            output=import_output,
        )
    else:
        print("---CODE IMPORT CHECK: PASSED---")

    # Check execution
    code_output, code_exit_code = await code_runner_task(
        script=await File.from_local(code_path)
    )

    if code_exit_code.strip() != "0":
        print("---CODE BLOCK CHECK: FAILED---")
        error_message = [
            {
                "role": "user",
                "content": f"Your solution failed the code execution test: {code_output}",
            }
        ]
        messages += error_message
        return AgentState(
            generation=code_solution,
            messages=messages,
            iterations=iterations,
            error="yes",
            output=code_output,
        )
    else:
        print("---CODE BLOCK CHECK: PASSED---")

    # No errors
    print("---NO CODE TEST FAILURES---")

    return AgentState(
        generation=code_solution,
        messages=messages,
        iterations=iterations,
        error="no",
        output=code_output,
    )

# {{/docs-fragment code_check}}

# {{docs-fragment reflect}}
@env.task
async def reflect(
    state: AgentState, concatenated_content: str, debug: bool
) -> AgentState:
    """
    Reflect on errors

    Args:
        state (dict): The current graph state
        concatenated_content (str): Concatenated docs content
        debug (bool): Debug mode

    Returns:
        state (dict): New key added to state, reflection
    """

    print("---REFLECTING---")

    # State
    messages = state.messages
    iterations = state.iterations
    code_solution = state.generation

    # Prompt reflection
    code_gen_chain = await generate_code_gen_chain(debug)

    # Add reflection
    reflections = code_gen_chain.invoke(
        {"context": concatenated_content, "messages": messages}
    )

    messages += [
        {
            "role": "assistant",
            "content": f"Here are reflections on the error: {reflections}",
        }
    ]

    return AgentState(
        generation=code_solution,
        messages=messages,
        iterations=iterations,
        error=state.error,
        output=state.output,
    )

# {{/docs-fragment reflect}}

# {{docs-fragment main}}
@env.task
async def main(
    question: str = (
        "Define a two-task pattern where the second catches OOM from the first and retries with more memory."
    ),
    url: str = "https://pre-release-v2.docs-builder.pages.dev/docs/byoc/user-guide/",
    max_iterations: int = 3,
    debug: bool = False,
) -> str:
    concatenated_content = await docs_retriever(url=url)

    state: AgentState = AgentState()
    iterations = 0

    while True:
        with flyte.group(f"code-generation-pass-{iterations + 1}"):
            state = await generate(question, state, concatenated_content, debug)
            state = await code_check(state)

            error = state.error
            iterations = state.iterations

            if error == "no" or iterations >= max_iterations:
                print("---DECISION: FINISH---")
                code_solution = state.generation

                prefix = code_solution.prefix
                imports = code_solution.imports
                code = code_solution.code

                code_output = state.output

                return f"""{prefix}

{imports}
{code}

Result of code execution:
{code_output}
"""
            else:
                print("---DECISION: RE-TRY SOLUTION---")
                state = await reflect(state, concatenated_content, debug)

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
    run.wait()

# {{/docs-fragment main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/code_runner/agent.py*

We then define a state model to persist the agent's history across iterations. This includes previous messages,
generated code, and any errors encountered.

Maintaining this history allows the agent to reflect on past attempts, avoid repeating mistakes,
and iteratively improve the generated code.

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "langchain-core==0.3.66",
#    "langchain-openai==0.3.24",
#    "langchain-community==0.3.26",
#    "beautifulsoup4==4.13.4",
#    "docker==7.1.0",
# ]
# main = "main"
# params = ""
# ///

# {{docs-fragment code_runner_task}}
import flyte
from flyte.extras import ContainerTask
from flyte.io import File

code_runner_task = ContainerTask(
    name="run_flyte_v2",
    image=flyte.Image.from_debian_base(),
    input_data_dir="/var/inputs",
    output_data_dir="/var/outputs",
    inputs={"script": File},
    outputs={"result": str, "exit_code": str},
    command=[
        "/bin/bash",
        "-c",
        (
            "set -o pipefail && "
            "uv run --script /var/inputs/script > /var/outputs/result 2>&1; "
            "echo $? > /var/outputs/exit_code"
        ),
    ],
    resources=flyte.Resources(cpu=1, memory="1Gi"),
)

# {{/docs-fragment code_runner_task}}

# {{docs-fragment env}}
import tempfile
from typing import Optional

from langchain_core.runnables import Runnable
from pydantic import BaseModel, Field

container_env = flyte.TaskEnvironment.from_task(
    "code-runner-container", code_runner_task
)

env = flyte.TaskEnvironment(
    name="code_runner",
    secrets=[flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY")],
    image=flyte.Image.from_uv_script(__file__, name="code-runner-agent"),
    resources=flyte.Resources(cpu=1),
    depends_on=[container_env],
)

# {{/docs-fragment env}}

# {{docs-fragment code_base_model}}
class Code(BaseModel):
    """Schema for code solutions to questions about Flyte v2."""

    prefix: str = Field(
        default="", description="Description of the problem and approach"
    )
    imports: str = Field(
        default="", description="Code block with just import statements"
    )
    code: str = Field(
        default="", description="Code block not including import statements"
    )

# {{/docs-fragment code_base_model}}

# {{docs-fragment agent_state}}
class AgentState(BaseModel):
    messages: list[dict[str, str]] = Field(default_factory=list)
    generation: Code = Field(default_factory=Code)
    iterations: int = 0
    error: str = "no"
    output: Optional[str] = None

# {{/docs-fragment agent_state}}

# {{docs-fragment generate_code_gen_chain}}
async def generate_code_gen_chain(debug: bool) -> Runnable:
    from langchain_core.prompts import ChatPromptTemplate
    from langchain_openai import ChatOpenAI

    # Grader prompt
    code_gen_prompt = ChatPromptTemplate.from_messages(
        [
            (
                "system",
                """
You are a coding assistant with expertise in Python.
You are able to execute the Flyte v2 code locally in a sandbox environment.

Use the following pattern to execute the code:

<code>
if __name__ == "__main__":
    flyte.init_from_config()
    print(flyte.run(...))
</code>

Your response will be shown to the user.
Here is a full set of documentation:

-------
{context}
-------

Answer the user question based on the above provided documentation.
Ensure any code you provide can be executed with all required imports and variables defined.
Structure your answer with a description of the code solution.
Then list the imports. And finally list the functioning code block.
Here is the user question:""",
            ),
            ("placeholder", "{messages}"),
        ]
    )

    expt_llm = "gpt-4o" if not debug else "gpt-4o-mini"
    llm = ChatOpenAI(temperature=0, model=expt_llm)

    code_gen_chain = code_gen_prompt | llm.with_structured_output(Code)
    return code_gen_chain

# {{/docs-fragment generate_code_gen_chain}}

# {{docs-fragment docs_retriever}}
@env.task
async def docs_retriever(url: str) -> str:
    from bs4 import BeautifulSoup
    from langchain_community.document_loaders.recursive_url_loader import (
        RecursiveUrlLoader,
    )

    loader = RecursiveUrlLoader(
        url=url, max_depth=20, extractor=lambda x: BeautifulSoup(x, "html.parser").text
    )
    docs = loader.load()

    # Sort the list based on the URLs and get the text
    d_sorted = sorted(docs, key=lambda x: x.metadata["source"])
    d_reversed = list(reversed(d_sorted))

    concatenated_content = "\n\n\n --- \n\n\n".join(
        [doc.page_content for doc in d_reversed]
    )
    return concatenated_content

# {{/docs-fragment docs_retriever}}

# {{docs-fragment generate}}
@env.task
async def generate(
    question: str, state: AgentState, concatenated_content: str, debug: bool
) -> AgentState:
    """
    Generate a code solution

    Args:
        question (str): The user question
        state (dict): The current graph state
        concatenated_content (str): The concatenated docs content
        debug (bool): Debug mode

    Returns:
        state (dict): New key added to state, generation
    """

    print("---GENERATING CODE SOLUTION---")

    messages = state.messages
    iterations = state.iterations
    error = state.error

    # We have been routed back to generation with an error
    if error == "yes":
        messages += [
            {
                "role": "user",
                "content": (
                    "Now, try again. Invoke the code tool to structure the output "
                    "with a prefix, imports, and code block:"
                ),
            }
        ]

    code_gen_chain = await generate_code_gen_chain(debug)

    # Solution
    code_solution = code_gen_chain.invoke(
        {
            "context": concatenated_content,
            "messages": (
                messages if messages else [{"role": "user", "content": question}]
            ),
        }
    )

    messages += [
        {
            "role": "assistant",
            "content": f"{code_solution.prefix} \n Imports: {code_solution.imports} \n Code: {code_solution.code}",
        }
    ]

    return AgentState(
        messages=messages,
        generation=code_solution,
        iterations=iterations + 1,
        error=error,
        output=state.output,
    )

# {{/docs-fragment generate}}

# {{docs-fragment code_check}}
@env.task
async def code_check(state: AgentState) -> AgentState:
    """
    Check code

    Args:
        state (dict): The current graph state

    Returns:
        state (dict): New key added to state, error
    """

    print("---CHECKING CODE---")

    # State
    messages = state.messages
    code_solution = state.generation
    iterations = state.iterations

    # Get solution components
    imports = code_solution.imports.strip()
    code = code_solution.code.strip()

    # Create temp file for imports
    with tempfile.NamedTemporaryFile(
        mode="w", suffix=".py", delete=False
    ) as imports_file:
        imports_file.write(imports + "\n")
        imports_path = imports_file.name

    # Create temp file for code body
    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as code_file:
        code_file.write(imports + "\n" + code + "\n")
        code_path = code_file.name

    # Check imports
    import_output, import_exit_code = await code_runner_task(
        script=await File.from_local(imports_path)
    )

    if import_exit_code.strip() != "0":
        print("---CODE IMPORT CHECK: FAILED---")
        error_message = [
            {
                "role": "user",
                "content": f"Your solution failed the import test: {import_output}",
            }
        ]
        messages += error_message
        return AgentState(
            generation=code_solution,
            messages=messages,
            iterations=iterations,
            error="yes",
            output=import_output,
        )
    else:
        print("---CODE IMPORT CHECK: PASSED---")

    # Check execution
    code_output, code_exit_code = await code_runner_task(
        script=await File.from_local(code_path)
    )

    if code_exit_code.strip() != "0":
        print("---CODE BLOCK CHECK: FAILED---")
        error_message = [
            {
                "role": "user",
                "content": f"Your solution failed the code execution test: {code_output}",
            }
        ]
        messages += error_message
        return AgentState(
            generation=code_solution,
            messages=messages,
            iterations=iterations,
            error="yes",
            output=code_output,
        )
    else:
        print("---CODE BLOCK CHECK: PASSED---")

    # No errors
    print("---NO CODE TEST FAILURES---")

    return AgentState(
        generation=code_solution,
        messages=messages,
        iterations=iterations,
        error="no",
        output=code_output,
    )

# {{/docs-fragment code_check}}

# {{docs-fragment reflect}}
@env.task
async def reflect(
    state: AgentState, concatenated_content: str, debug: bool
) -> AgentState:
    """
    Reflect on errors

    Args:
        state (dict): The current graph state
        concatenated_content (str): Concatenated docs content
        debug (bool): Debug mode

    Returns:
        state (dict): New key added to state, reflection
    """

    print("---REFLECTING---")

    # State
    messages = state.messages
    iterations = state.iterations
    code_solution = state.generation

    # Prompt reflection
    code_gen_chain = await generate_code_gen_chain(debug)

    # Add reflection
    reflections = code_gen_chain.invoke(
        {"context": concatenated_content, "messages": messages}
    )

    messages += [
        {
            "role": "assistant",
            "content": f"Here are reflections on the error: {reflections}",
        }
    ]

    return AgentState(
        generation=code_solution,
        messages=messages,
        iterations=iterations,
        error=state.error,
        output=state.output,
    )

# {{/docs-fragment reflect}}

# {{docs-fragment main}}
@env.task
async def main(
    question: str = (
        "Define a two-task pattern where the second catches OOM from the first and retries with more memory."
    ),
    url: str = "https://pre-release-v2.docs-builder.pages.dev/docs/byoc/user-guide/",
    max_iterations: int = 3,
    debug: bool = False,
) -> str:
    concatenated_content = await docs_retriever(url=url)

    state: AgentState = AgentState()
    iterations = 0

    while True:
        with flyte.group(f"code-generation-pass-{iterations + 1}"):
            state = await generate(question, state, concatenated_content, debug)
            state = await code_check(state)

            error = state.error
            iterations = state.iterations

            if error == "no" or iterations >= max_iterations:
                print("---DECISION: FINISH---")
                code_solution = state.generation

                prefix = code_solution.prefix
                imports = code_solution.imports
                code = code_solution.code

                code_output = state.output

                return f"""{prefix}

{imports}
{code}

Result of code execution:
{code_output}
"""
            else:
                print("---DECISION: RE-TRY SOLUTION---")
                state = await reflect(state, concatenated_content, debug)

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
    run.wait()

# {{/docs-fragment main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/code_runner/agent.py*

## Retrieve docs

We define a task to load documents from a given URL and concatenate them into a single string.
This string is then used as part of the LLM prompt.

We set `max_depth = 20` to avoid loading an excessive number of documents.
However, even with this limit, the resulting context can still be quite large.
To handle this, we use an LLM (GPT-4 in this case) that supports extended context windows.

> [!NOTE]
> Appending all documents into a single string can result in extremely large contexts, potentially exceeding the LLM’s token limit.
> If your dataset grows beyond what a single prompt can handle, there are a couple of strategies you can use.
> One option is to apply Retrieval-Augmented Generation (RAG), where you chunk the documents, embed them using a model,
> store the vectors in a vector database, and retrieve only the most relevant pieces at inference time.
>
> An alternative approach is to pass references to full files into the prompt, allowing the LLM to decide which files are most relevant based
> on natural-language search over file paths, summaries, or even contents. This method assumes that only a subset of files
> will be necessary for a given task, and the LLM is responsible for navigating the structure and identifying what to read.
> While this can be a lighter-weight solution for smaller datasets, its effectiveness depends on how well the LLM can
> reason over file references and the reliability of its internal search heuristics.

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "langchain-core==0.3.66",
#    "langchain-openai==0.3.24",
#    "langchain-community==0.3.26",
#    "beautifulsoup4==4.13.4",
#    "docker==7.1.0",
# ]
# main = "main"
# params = ""
# ///

# {{docs-fragment code_runner_task}}
import flyte
from flyte.extras import ContainerTask
from flyte.io import File

code_runner_task = ContainerTask(
    name="run_flyte_v2",
    image=flyte.Image.from_debian_base(),
    input_data_dir="/var/inputs",
    output_data_dir="/var/outputs",
    inputs={"script": File},
    outputs={"result": str, "exit_code": str},
    command=[
        "/bin/bash",
        "-c",
        (
            "set -o pipefail && "
            "uv run --script /var/inputs/script > /var/outputs/result 2>&1; "
            "echo $? > /var/outputs/exit_code"
        ),
    ],
    resources=flyte.Resources(cpu=1, memory="1Gi"),
)

# {{/docs-fragment code_runner_task}}

# {{docs-fragment env}}
import tempfile
from typing import Optional

from langchain_core.runnables import Runnable
from pydantic import BaseModel, Field

container_env = flyte.TaskEnvironment.from_task(
    "code-runner-container", code_runner_task
)

env = flyte.TaskEnvironment(
    name="code_runner",
    secrets=[flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY")],
    image=flyte.Image.from_uv_script(__file__, name="code-runner-agent"),
    resources=flyte.Resources(cpu=1),
    depends_on=[container_env],
)

# {{/docs-fragment env}}

# {{docs-fragment code_base_model}}
class Code(BaseModel):
    """Schema for code solutions to questions about Flyte v2."""

    prefix: str = Field(
        default="", description="Description of the problem and approach"
    )
    imports: str = Field(
        default="", description="Code block with just import statements"
    )
    code: str = Field(
        default="", description="Code block not including import statements"
    )

# {{/docs-fragment code_base_model}}

# {{docs-fragment agent_state}}
class AgentState(BaseModel):
    messages: list[dict[str, str]] = Field(default_factory=list)
    generation: Code = Field(default_factory=Code)
    iterations: int = 0
    error: str = "no"
    output: Optional[str] = None

# {{/docs-fragment agent_state}}

# {{docs-fragment generate_code_gen_chain}}
async def generate_code_gen_chain(debug: bool) -> Runnable:
    from langchain_core.prompts import ChatPromptTemplate
    from langchain_openai import ChatOpenAI

    # Grader prompt
    code_gen_prompt = ChatPromptTemplate.from_messages(
        [
            (
                "system",
                """
You are a coding assistant with expertise in Python.
You are able to execute the Flyte v2 code locally in a sandbox environment.

Use the following pattern to execute the code:

<code>
if __name__ == "__main__":
    flyte.init_from_config()
    print(flyte.run(...))
</code>

Your response will be shown to the user.
Here is a full set of documentation:

-------
{context}
-------

Answer the user question based on the above provided documentation.
Ensure any code you provide can be executed with all required imports and variables defined.
Structure your answer with a description of the code solution.
Then list the imports. And finally list the functioning code block.
Here is the user question:""",
            ),
            ("placeholder", "{messages}"),
        ]
    )

    expt_llm = "gpt-4o" if not debug else "gpt-4o-mini"
    llm = ChatOpenAI(temperature=0, model=expt_llm)

    code_gen_chain = code_gen_prompt | llm.with_structured_output(Code)
    return code_gen_chain

# {{/docs-fragment generate_code_gen_chain}}

# {{docs-fragment docs_retriever}}
@env.task
async def docs_retriever(url: str) -> str:
    from bs4 import BeautifulSoup
    from langchain_community.document_loaders.recursive_url_loader import (
        RecursiveUrlLoader,
    )

    loader = RecursiveUrlLoader(
        url=url, max_depth=20, extractor=lambda x: BeautifulSoup(x, "html.parser").text
    )
    docs = loader.load()

    # Sort the list based on the URLs and get the text
    d_sorted = sorted(docs, key=lambda x: x.metadata["source"])
    d_reversed = list(reversed(d_sorted))

    concatenated_content = "\n\n\n --- \n\n\n".join(
        [doc.page_content for doc in d_reversed]
    )
    return concatenated_content

# {{/docs-fragment docs_retriever}}

# {{docs-fragment generate}}
@env.task
async def generate(
    question: str, state: AgentState, concatenated_content: str, debug: bool
) -> AgentState:
    """
    Generate a code solution

    Args:
        question (str): The user question
        state (dict): The current graph state
        concatenated_content (str): The concatenated docs content
        debug (bool): Debug mode

    Returns:
        state (dict): New key added to state, generation
    """

    print("---GENERATING CODE SOLUTION---")

    messages = state.messages
    iterations = state.iterations
    error = state.error

    # We have been routed back to generation with an error
    if error == "yes":
        messages += [
            {
                "role": "user",
                "content": (
                    "Now, try again. Invoke the code tool to structure the output "
                    "with a prefix, imports, and code block:"
                ),
            }
        ]

    code_gen_chain = await generate_code_gen_chain(debug)

    # Solution
    code_solution = code_gen_chain.invoke(
        {
            "context": concatenated_content,
            "messages": (
                messages if messages else [{"role": "user", "content": question}]
            ),
        }
    )

    messages += [
        {
            "role": "assistant",
            "content": f"{code_solution.prefix} \n Imports: {code_solution.imports} \n Code: {code_solution.code}",
        }
    ]

    return AgentState(
        messages=messages,
        generation=code_solution,
        iterations=iterations + 1,
        error=error,
        output=state.output,
    )

# {{/docs-fragment generate}}

# {{docs-fragment code_check}}
@env.task
async def code_check(state: AgentState) -> AgentState:
    """
    Check code

    Args:
        state (dict): The current graph state

    Returns:
        state (dict): New key added to state, error
    """

    print("---CHECKING CODE---")

    # State
    messages = state.messages
    code_solution = state.generation
    iterations = state.iterations

    # Get solution components
    imports = code_solution.imports.strip()
    code = code_solution.code.strip()

    # Create temp file for imports
    with tempfile.NamedTemporaryFile(
        mode="w", suffix=".py", delete=False
    ) as imports_file:
        imports_file.write(imports + "\n")
        imports_path = imports_file.name

    # Create temp file for code body
    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as code_file:
        code_file.write(imports + "\n" + code + "\n")
        code_path = code_file.name

    # Check imports
    import_output, import_exit_code = await code_runner_task(
        script=await File.from_local(imports_path)
    )

    if import_exit_code.strip() != "0":
        print("---CODE IMPORT CHECK: FAILED---")
        error_message = [
            {
                "role": "user",
                "content": f"Your solution failed the import test: {import_output}",
            }
        ]
        messages += error_message
        return AgentState(
            generation=code_solution,
            messages=messages,
            iterations=iterations,
            error="yes",
            output=import_output,
        )
    else:
        print("---CODE IMPORT CHECK: PASSED---")

    # Check execution
    code_output, code_exit_code = await code_runner_task(
        script=await File.from_local(code_path)
    )

    if code_exit_code.strip() != "0":
        print("---CODE BLOCK CHECK: FAILED---")
        error_message = [
            {
                "role": "user",
                "content": f"Your solution failed the code execution test: {code_output}",
            }
        ]
        messages += error_message
        return AgentState(
            generation=code_solution,
            messages=messages,
            iterations=iterations,
            error="yes",
            output=code_output,
        )
    else:
        print("---CODE BLOCK CHECK: PASSED---")

    # No errors
    print("---NO CODE TEST FAILURES---")

    return AgentState(
        generation=code_solution,
        messages=messages,
        iterations=iterations,
        error="no",
        output=code_output,
    )

# {{/docs-fragment code_check}}

# {{docs-fragment reflect}}
@env.task
async def reflect(
    state: AgentState, concatenated_content: str, debug: bool
) -> AgentState:
    """
    Reflect on errors

    Args:
        state (dict): The current graph state
        concatenated_content (str): Concatenated docs content
        debug (bool): Debug mode

    Returns:
        state (dict): New key added to state, reflection
    """

    print("---REFLECTING---")

    # State
    messages = state.messages
    iterations = state.iterations
    code_solution = state.generation

    # Prompt reflection
    code_gen_chain = await generate_code_gen_chain(debug)

    # Add reflection
    reflections = code_gen_chain.invoke(
        {"context": concatenated_content, "messages": messages}
    )

    messages += [
        {
            "role": "assistant",
            "content": f"Here are reflections on the error: {reflections}",
        }
    ]

    return AgentState(
        generation=code_solution,
        messages=messages,
        iterations=iterations,
        error=state.error,
        output=state.output,
    )

# {{/docs-fragment reflect}}

# {{docs-fragment main}}
@env.task
async def main(
    question: str = (
        "Define a two-task pattern where the second catches OOM from the first and retries with more memory."
    ),
    url: str = "https://pre-release-v2.docs-builder.pages.dev/docs/byoc/user-guide/",
    max_iterations: int = 3,
    debug: bool = False,
) -> str:
    concatenated_content = await docs_retriever(url=url)

    state: AgentState = AgentState()
    iterations = 0

    while True:
        with flyte.group(f"code-generation-pass-{iterations + 1}"):
            state = await generate(question, state, concatenated_content, debug)
            state = await code_check(state)

            error = state.error
            iterations = state.iterations

            if error == "no" or iterations >= max_iterations:
                print("---DECISION: FINISH---")
                code_solution = state.generation

                prefix = code_solution.prefix
                imports = code_solution.imports
                code = code_solution.code

                code_output = state.output

                return f"""{prefix}

{imports}
{code}

Result of code execution:
{code_output}
"""
            else:
                print("---DECISION: RE-TRY SOLUTION---")
                state = await reflect(state, concatenated_content, debug)

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
    run.wait()

# {{/docs-fragment main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/code_runner/agent.py*

## Code generation

Next, we define a utility function to construct the LLM chain responsible for generating Python code from user input. This chain leverages
a LangChain `PromptTemplate` to structure the input and an OpenAI chat model to generate well-formed, Flyte 2-compatible Python scripts.

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "langchain-core==0.3.66",
#    "langchain-openai==0.3.24",
#    "langchain-community==0.3.26",
#    "beautifulsoup4==4.13.4",
#    "docker==7.1.0",
# ]
# main = "main"
# params = ""
# ///

# {{docs-fragment code_runner_task}}
import flyte
from flyte.extras import ContainerTask
from flyte.io import File

code_runner_task = ContainerTask(
    name="run_flyte_v2",
    image=flyte.Image.from_debian_base(),
    input_data_dir="/var/inputs",
    output_data_dir="/var/outputs",
    inputs={"script": File},
    outputs={"result": str, "exit_code": str},
    command=[
        "/bin/bash",
        "-c",
        (
            "set -o pipefail && "
            "uv run --script /var/inputs/script > /var/outputs/result 2>&1; "
            "echo $? > /var/outputs/exit_code"
        ),
    ],
    resources=flyte.Resources(cpu=1, memory="1Gi"),
)

# {{/docs-fragment code_runner_task}}

# {{docs-fragment env}}
import tempfile
from typing import Optional

from langchain_core.runnables import Runnable
from pydantic import BaseModel, Field

container_env = flyte.TaskEnvironment.from_task(
    "code-runner-container", code_runner_task
)

env = flyte.TaskEnvironment(
    name="code_runner",
    secrets=[flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY")],
    image=flyte.Image.from_uv_script(__file__, name="code-runner-agent"),
    resources=flyte.Resources(cpu=1),
    depends_on=[container_env],
)

# {{/docs-fragment env}}

# {{docs-fragment code_base_model}}
class Code(BaseModel):
    """Schema for code solutions to questions about Flyte v2."""

    prefix: str = Field(
        default="", description="Description of the problem and approach"
    )
    imports: str = Field(
        default="", description="Code block with just import statements"
    )
    code: str = Field(
        default="", description="Code block not including import statements"
    )

# {{/docs-fragment code_base_model}}

# {{docs-fragment agent_state}}
class AgentState(BaseModel):
    messages: list[dict[str, str]] = Field(default_factory=list)
    generation: Code = Field(default_factory=Code)
    iterations: int = 0
    error: str = "no"
    output: Optional[str] = None

# {{/docs-fragment agent_state}}

# {{docs-fragment generate_code_gen_chain}}
async def generate_code_gen_chain(debug: bool) -> Runnable:
    from langchain_core.prompts import ChatPromptTemplate
    from langchain_openai import ChatOpenAI

    # Grader prompt
    code_gen_prompt = ChatPromptTemplate.from_messages(
        [
            (
                "system",
                """
You are a coding assistant with expertise in Python.
You are able to execute the Flyte v2 code locally in a sandbox environment.

Use the following pattern to execute the code:

<code>
if __name__ == "__main__":
    flyte.init_from_config()
    print(flyte.run(...))
</code>

Your response will be shown to the user.
Here is a full set of documentation:

-------
{context}
-------

Answer the user question based on the above provided documentation.
Ensure any code you provide can be executed with all required imports and variables defined.
Structure your answer with a description of the code solution.
Then list the imports. And finally list the functioning code block.
Here is the user question:""",
            ),
            ("placeholder", "{messages}"),
        ]
    )

    expt_llm = "gpt-4o" if not debug else "gpt-4o-mini"
    llm = ChatOpenAI(temperature=0, model=expt_llm)

    code_gen_chain = code_gen_prompt | llm.with_structured_output(Code)
    return code_gen_chain

# {{/docs-fragment generate_code_gen_chain}}

# {{docs-fragment docs_retriever}}
@env.task
async def docs_retriever(url: str) -> str:
    from bs4 import BeautifulSoup
    from langchain_community.document_loaders.recursive_url_loader import (
        RecursiveUrlLoader,
    )

    loader = RecursiveUrlLoader(
        url=url, max_depth=20, extractor=lambda x: BeautifulSoup(x, "html.parser").text
    )
    docs = loader.load()

    # Sort the list based on the URLs and get the text
    d_sorted = sorted(docs, key=lambda x: x.metadata["source"])
    d_reversed = list(reversed(d_sorted))

    concatenated_content = "\n\n\n --- \n\n\n".join(
        [doc.page_content for doc in d_reversed]
    )
    return concatenated_content

# {{/docs-fragment docs_retriever}}

# {{docs-fragment generate}}
@env.task
async def generate(
    question: str, state: AgentState, concatenated_content: str, debug: bool
) -> AgentState:
    """
    Generate a code solution

    Args:
        question (str): The user question
        state (dict): The current graph state
        concatenated_content (str): The concatenated docs content
        debug (bool): Debug mode

    Returns:
        state (dict): New key added to state, generation
    """

    print("---GENERATING CODE SOLUTION---")

    messages = state.messages
    iterations = state.iterations
    error = state.error

    # We have been routed back to generation with an error
    if error == "yes":
        messages += [
            {
                "role": "user",
                "content": (
                    "Now, try again. Invoke the code tool to structure the output "
                    "with a prefix, imports, and code block:"
                ),
            }
        ]

    code_gen_chain = await generate_code_gen_chain(debug)

    # Solution
    code_solution = code_gen_chain.invoke(
        {
            "context": concatenated_content,
            "messages": (
                messages if messages else [{"role": "user", "content": question}]
            ),
        }
    )

    messages += [
        {
            "role": "assistant",
            "content": f"{code_solution.prefix} \n Imports: {code_solution.imports} \n Code: {code_solution.code}",
        }
    ]

    return AgentState(
        messages=messages,
        generation=code_solution,
        iterations=iterations + 1,
        error=error,
        output=state.output,
    )

# {{/docs-fragment generate}}

# {{docs-fragment code_check}}
@env.task
async def code_check(state: AgentState) -> AgentState:
    """
    Check code

    Args:
        state (dict): The current graph state

    Returns:
        state (dict): New key added to state, error
    """

    print("---CHECKING CODE---")

    # State
    messages = state.messages
    code_solution = state.generation
    iterations = state.iterations

    # Get solution components
    imports = code_solution.imports.strip()
    code = code_solution.code.strip()

    # Create temp file for imports
    with tempfile.NamedTemporaryFile(
        mode="w", suffix=".py", delete=False
    ) as imports_file:
        imports_file.write(imports + "\n")
        imports_path = imports_file.name

    # Create temp file for code body
    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as code_file:
        code_file.write(imports + "\n" + code + "\n")
        code_path = code_file.name

    # Check imports
    import_output, import_exit_code = await code_runner_task(
        script=await File.from_local(imports_path)
    )

    if import_exit_code.strip() != "0":
        print("---CODE IMPORT CHECK: FAILED---")
        error_message = [
            {
                "role": "user",
                "content": f"Your solution failed the import test: {import_output}",
            }
        ]
        messages += error_message
        return AgentState(
            generation=code_solution,
            messages=messages,
            iterations=iterations,
            error="yes",
            output=import_output,
        )
    else:
        print("---CODE IMPORT CHECK: PASSED---")

    # Check execution
    code_output, code_exit_code = await code_runner_task(
        script=await File.from_local(code_path)
    )

    if code_exit_code.strip() != "0":
        print("---CODE BLOCK CHECK: FAILED---")
        error_message = [
            {
                "role": "user",
                "content": f"Your solution failed the code execution test: {code_output}",
            }
        ]
        messages += error_message
        return AgentState(
            generation=code_solution,
            messages=messages,
            iterations=iterations,
            error="yes",
            output=code_output,
        )
    else:
        print("---CODE BLOCK CHECK: PASSED---")

    # No errors
    print("---NO CODE TEST FAILURES---")

    return AgentState(
        generation=code_solution,
        messages=messages,
        iterations=iterations,
        error="no",
        output=code_output,
    )

# {{/docs-fragment code_check}}

# {{docs-fragment reflect}}
@env.task
async def reflect(
    state: AgentState, concatenated_content: str, debug: bool
) -> AgentState:
    """
    Reflect on errors

    Args:
        state (dict): The current graph state
        concatenated_content (str): Concatenated docs content
        debug (bool): Debug mode

    Returns:
        state (dict): New key added to state, reflection
    """

    print("---REFLECTING---")

    # State
    messages = state.messages
    iterations = state.iterations
    code_solution = state.generation

    # Prompt reflection
    code_gen_chain = await generate_code_gen_chain(debug)

    # Add reflection
    reflections = code_gen_chain.invoke(
        {"context": concatenated_content, "messages": messages}
    )

    messages += [
        {
            "role": "assistant",
            "content": f"Here are reflections on the error: {reflections}",
        }
    ]

    return AgentState(
        generation=code_solution,
        messages=messages,
        iterations=iterations,
        error=state.error,
        output=state.output,
    )

# {{/docs-fragment reflect}}

# {{docs-fragment main}}
@env.task
async def main(
    question: str = (
        "Define a two-task pattern where the second catches OOM from the first and retries with more memory."
    ),
    url: str = "https://pre-release-v2.docs-builder.pages.dev/docs/byoc/user-guide/",
    max_iterations: int = 3,
    debug: bool = False,
) -> str:
    concatenated_content = await docs_retriever(url=url)

    state: AgentState = AgentState()
    iterations = 0

    while True:
        with flyte.group(f"code-generation-pass-{iterations + 1}"):
            state = await generate(question, state, concatenated_content, debug)
            state = await code_check(state)

            error = state.error
            iterations = state.iterations

            if error == "no" or iterations >= max_iterations:
                print("---DECISION: FINISH---")
                code_solution = state.generation

                prefix = code_solution.prefix
                imports = code_solution.imports
                code = code_solution.code

                code_output = state.output

                return f"""{prefix}

{imports}
{code}

Result of code execution:
{code_output}
"""
            else:
                print("---DECISION: RE-TRY SOLUTION---")
                state = await reflect(state, concatenated_content, debug)

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
    run.wait()

# {{/docs-fragment main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/code_runner/agent.py*

We then define a `generate` task responsible for producing the code solution.
To improve clarity and testability, the output is structured in three parts:
a short summary of the generated solution, a list of necessary imports,
and the main body of executable code.

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "langchain-core==0.3.66",
#    "langchain-openai==0.3.24",
#    "langchain-community==0.3.26",
#    "beautifulsoup4==4.13.4",
#    "docker==7.1.0",
# ]
# main = "main"
# params = ""
# ///

# {{docs-fragment code_runner_task}}
import flyte
from flyte.extras import ContainerTask
from flyte.io import File

code_runner_task = ContainerTask(
    name="run_flyte_v2",
    image=flyte.Image.from_debian_base(),
    input_data_dir="/var/inputs",
    output_data_dir="/var/outputs",
    inputs={"script": File},
    outputs={"result": str, "exit_code": str},
    command=[
        "/bin/bash",
        "-c",
        (
            "set -o pipefail && "
            "uv run --script /var/inputs/script > /var/outputs/result 2>&1; "
            "echo $? > /var/outputs/exit_code"
        ),
    ],
    resources=flyte.Resources(cpu=1, memory="1Gi"),
)

# {{/docs-fragment code_runner_task}}

# {{docs-fragment env}}
import tempfile
from typing import Optional

from langchain_core.runnables import Runnable
from pydantic import BaseModel, Field

container_env = flyte.TaskEnvironment.from_task(
    "code-runner-container", code_runner_task
)

env = flyte.TaskEnvironment(
    name="code_runner",
    secrets=[flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY")],
    image=flyte.Image.from_uv_script(__file__, name="code-runner-agent"),
    resources=flyte.Resources(cpu=1),
    depends_on=[container_env],
)

# {{/docs-fragment env}}

# {{docs-fragment code_base_model}}
class Code(BaseModel):
    """Schema for code solutions to questions about Flyte v2."""

    prefix: str = Field(
        default="", description="Description of the problem and approach"
    )
    imports: str = Field(
        default="", description="Code block with just import statements"
    )
    code: str = Field(
        default="", description="Code block not including import statements"
    )

# {{/docs-fragment code_base_model}}

# {{docs-fragment agent_state}}
class AgentState(BaseModel):
    messages: list[dict[str, str]] = Field(default_factory=list)
    generation: Code = Field(default_factory=Code)
    iterations: int = 0
    error: str = "no"
    output: Optional[str] = None

# {{/docs-fragment agent_state}}

# {{docs-fragment generate_code_gen_chain}}
async def generate_code_gen_chain(debug: bool) -> Runnable:
    from langchain_core.prompts import ChatPromptTemplate
    from langchain_openai import ChatOpenAI

    # Grader prompt
    code_gen_prompt = ChatPromptTemplate.from_messages(
        [
            (
                "system",
                """
You are a coding assistant with expertise in Python.
You are able to execute the Flyte v2 code locally in a sandbox environment.

Use the following pattern to execute the code:

<code>
if __name__ == "__main__":
    flyte.init_from_config()
    print(flyte.run(...))
</code>

Your response will be shown to the user.
Here is a full set of documentation:

-------
{context}
-------

Answer the user question based on the above provided documentation.
Ensure any code you provide can be executed with all required imports and variables defined.
Structure your answer with a description of the code solution.
Then list the imports. And finally list the functioning code block.
Here is the user question:""",
            ),
            ("placeholder", "{messages}"),
        ]
    )

    expt_llm = "gpt-4o" if not debug else "gpt-4o-mini"
    llm = ChatOpenAI(temperature=0, model=expt_llm)

    code_gen_chain = code_gen_prompt | llm.with_structured_output(Code)
    return code_gen_chain

# {{/docs-fragment generate_code_gen_chain}}

# {{docs-fragment docs_retriever}}
@env.task
async def docs_retriever(url: str) -> str:
    from bs4 import BeautifulSoup
    from langchain_community.document_loaders.recursive_url_loader import (
        RecursiveUrlLoader,
    )

    loader = RecursiveUrlLoader(
        url=url, max_depth=20, extractor=lambda x: BeautifulSoup(x, "html.parser").text
    )
    docs = loader.load()

    # Sort the list based on the URLs and get the text
    d_sorted = sorted(docs, key=lambda x: x.metadata["source"])
    d_reversed = list(reversed(d_sorted))

    concatenated_content = "\n\n\n --- \n\n\n".join(
        [doc.page_content for doc in d_reversed]
    )
    return concatenated_content

# {{/docs-fragment docs_retriever}}

# {{docs-fragment generate}}
@env.task
async def generate(
    question: str, state: AgentState, concatenated_content: str, debug: bool
) -> AgentState:
    """
    Generate a code solution

    Args:
        question (str): The user question
        state (dict): The current graph state
        concatenated_content (str): The concatenated docs content
        debug (bool): Debug mode

    Returns:
        state (dict): New key added to state, generation
    """

    print("---GENERATING CODE SOLUTION---")

    messages = state.messages
    iterations = state.iterations
    error = state.error

    # We have been routed back to generation with an error
    if error == "yes":
        messages += [
            {
                "role": "user",
                "content": (
                    "Now, try again. Invoke the code tool to structure the output "
                    "with a prefix, imports, and code block:"
                ),
            }
        ]

    code_gen_chain = await generate_code_gen_chain(debug)

    # Solution
    code_solution = code_gen_chain.invoke(
        {
            "context": concatenated_content,
            "messages": (
                messages if messages else [{"role": "user", "content": question}]
            ),
        }
    )

    messages += [
        {
            "role": "assistant",
            "content": f"{code_solution.prefix} \n Imports: {code_solution.imports} \n Code: {code_solution.code}",
        }
    ]

    return AgentState(
        messages=messages,
        generation=code_solution,
        iterations=iterations + 1,
        error=error,
        output=state.output,
    )

# {{/docs-fragment generate}}

# {{docs-fragment code_check}}
@env.task
async def code_check(state: AgentState) -> AgentState:
    """
    Check code

    Args:
        state (dict): The current graph state

    Returns:
        state (dict): New key added to state, error
    """

    print("---CHECKING CODE---")

    # State
    messages = state.messages
    code_solution = state.generation
    iterations = state.iterations

    # Get solution components
    imports = code_solution.imports.strip()
    code = code_solution.code.strip()

    # Create temp file for imports
    with tempfile.NamedTemporaryFile(
        mode="w", suffix=".py", delete=False
    ) as imports_file:
        imports_file.write(imports + "\n")
        imports_path = imports_file.name

    # Create temp file for code body
    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as code_file:
        code_file.write(imports + "\n" + code + "\n")
        code_path = code_file.name

    # Check imports
    import_output, import_exit_code = await code_runner_task(
        script=await File.from_local(imports_path)
    )

    if import_exit_code.strip() != "0":
        print("---CODE IMPORT CHECK: FAILED---")
        error_message = [
            {
                "role": "user",
                "content": f"Your solution failed the import test: {import_output}",
            }
        ]
        messages += error_message
        return AgentState(
            generation=code_solution,
            messages=messages,
            iterations=iterations,
            error="yes",
            output=import_output,
        )
    else:
        print("---CODE IMPORT CHECK: PASSED---")

    # Check execution
    code_output, code_exit_code = await code_runner_task(
        script=await File.from_local(code_path)
    )

    if code_exit_code.strip() != "0":
        print("---CODE BLOCK CHECK: FAILED---")
        error_message = [
            {
                "role": "user",
                "content": f"Your solution failed the code execution test: {code_output}",
            }
        ]
        messages += error_message
        return AgentState(
            generation=code_solution,
            messages=messages,
            iterations=iterations,
            error="yes",
            output=code_output,
        )
    else:
        print("---CODE BLOCK CHECK: PASSED---")

    # No errors
    print("---NO CODE TEST FAILURES---")

    return AgentState(
        generation=code_solution,
        messages=messages,
        iterations=iterations,
        error="no",
        output=code_output,
    )

# {{/docs-fragment code_check}}

# {{docs-fragment reflect}}
@env.task
async def reflect(
    state: AgentState, concatenated_content: str, debug: bool
) -> AgentState:
    """
    Reflect on errors

    Args:
        state (dict): The current graph state
        concatenated_content (str): Concatenated docs content
        debug (bool): Debug mode

    Returns:
        state (dict): New key added to state, reflection
    """

    print("---REFLECTING---")

    # State
    messages = state.messages
    iterations = state.iterations
    code_solution = state.generation

    # Prompt reflection
    code_gen_chain = await generate_code_gen_chain(debug)

    # Add reflection
    reflections = code_gen_chain.invoke(
        {"context": concatenated_content, "messages": messages}
    )

    messages += [
        {
            "role": "assistant",
            "content": f"Here are reflections on the error: {reflections}",
        }
    ]

    return AgentState(
        generation=code_solution,
        messages=messages,
        iterations=iterations,
        error=state.error,
        output=state.output,
    )

# {{/docs-fragment reflect}}

# {{docs-fragment main}}
@env.task
async def main(
    question: str = (
        "Define a two-task pattern where the second catches OOM from the first and retries with more memory."
    ),
    url: str = "https://pre-release-v2.docs-builder.pages.dev/docs/byoc/user-guide/",
    max_iterations: int = 3,
    debug: bool = False,
) -> str:
    concatenated_content = await docs_retriever(url=url)

    state: AgentState = AgentState()
    iterations = 0

    while True:
        with flyte.group(f"code-generation-pass-{iterations + 1}"):
            state = await generate(question, state, concatenated_content, debug)
            state = await code_check(state)

            error = state.error
            iterations = state.iterations

            if error == "no" or iterations >= max_iterations:
                print("---DECISION: FINISH---")
                code_solution = state.generation

                prefix = code_solution.prefix
                imports = code_solution.imports
                code = code_solution.code

                code_output = state.output

                return f"""{prefix}

{imports}
{code}

Result of code execution:
{code_output}
"""
            else:
                print("---DECISION: RE-TRY SOLUTION---")
                state = await reflect(state, concatenated_content, debug)

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
    run.wait()

# {{/docs-fragment main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/code_runner/agent.py*

A `ContainerTask` then executes this code in an isolated container environment.
It takes the code as input, runs it safely, and returns the program’s output and exit code.

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "langchain-core==0.3.66",
#    "langchain-openai==0.3.24",
#    "langchain-community==0.3.26",
#    "beautifulsoup4==4.13.4",
#    "docker==7.1.0",
# ]
# main = "main"
# params = ""
# ///

# {{docs-fragment code_runner_task}}
import flyte
from flyte.extras import ContainerTask
from flyte.io import File

code_runner_task = ContainerTask(
    name="run_flyte_v2",
    image=flyte.Image.from_debian_base(),
    input_data_dir="/var/inputs",
    output_data_dir="/var/outputs",
    inputs={"script": File},
    outputs={"result": str, "exit_code": str},
    command=[
        "/bin/bash",
        "-c",
        (
            "set -o pipefail && "
            "uv run --script /var/inputs/script > /var/outputs/result 2>&1; "
            "echo $? > /var/outputs/exit_code"
        ),
    ],
    resources=flyte.Resources(cpu=1, memory="1Gi"),
)

# {{/docs-fragment code_runner_task}}

# {{docs-fragment env}}
import tempfile
from typing import Optional

from langchain_core.runnables import Runnable
from pydantic import BaseModel, Field

container_env = flyte.TaskEnvironment.from_task(
    "code-runner-container", code_runner_task
)

env = flyte.TaskEnvironment(
    name="code_runner",
    secrets=[flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY")],
    image=flyte.Image.from_uv_script(__file__, name="code-runner-agent"),
    resources=flyte.Resources(cpu=1),
    depends_on=[container_env],
)

# {{/docs-fragment env}}

# {{docs-fragment code_base_model}}
class Code(BaseModel):
    """Schema for code solutions to questions about Flyte v2."""

    prefix: str = Field(
        default="", description="Description of the problem and approach"
    )
    imports: str = Field(
        default="", description="Code block with just import statements"
    )
    code: str = Field(
        default="", description="Code block not including import statements"
    )

# {{/docs-fragment code_base_model}}

# {{docs-fragment agent_state}}
class AgentState(BaseModel):
    messages: list[dict[str, str]] = Field(default_factory=list)
    generation: Code = Field(default_factory=Code)
    iterations: int = 0
    error: str = "no"
    output: Optional[str] = None

# {{/docs-fragment agent_state}}

# {{docs-fragment generate_code_gen_chain}}
async def generate_code_gen_chain(debug: bool) -> Runnable:
    from langchain_core.prompts import ChatPromptTemplate
    from langchain_openai import ChatOpenAI

    # Grader prompt
    code_gen_prompt = ChatPromptTemplate.from_messages(
        [
            (
                "system",
                """
You are a coding assistant with expertise in Python.
You are able to execute the Flyte v2 code locally in a sandbox environment.

Use the following pattern to execute the code:

<code>
if __name__ == "__main__":
    flyte.init_from_config()
    print(flyte.run(...))
</code>

Your response will be shown to the user.
Here is a full set of documentation:

-------
{context}
-------

Answer the user question based on the above provided documentation.
Ensure any code you provide can be executed with all required imports and variables defined.
Structure your answer with a description of the code solution.
Then list the imports. And finally list the functioning code block.
Here is the user question:""",
            ),
            ("placeholder", "{messages}"),
        ]
    )

    expt_llm = "gpt-4o" if not debug else "gpt-4o-mini"
    llm = ChatOpenAI(temperature=0, model=expt_llm)

    code_gen_chain = code_gen_prompt | llm.with_structured_output(Code)
    return code_gen_chain

# {{/docs-fragment generate_code_gen_chain}}

# {{docs-fragment docs_retriever}}
@env.task
async def docs_retriever(url: str) -> str:
    from bs4 import BeautifulSoup
    from langchain_community.document_loaders.recursive_url_loader import (
        RecursiveUrlLoader,
    )

    loader = RecursiveUrlLoader(
        url=url, max_depth=20, extractor=lambda x: BeautifulSoup(x, "html.parser").text
    )
    docs = loader.load()

    # Sort the list based on the URLs and get the text
    d_sorted = sorted(docs, key=lambda x: x.metadata["source"])
    d_reversed = list(reversed(d_sorted))

    concatenated_content = "\n\n\n --- \n\n\n".join(
        [doc.page_content for doc in d_reversed]
    )
    return concatenated_content

# {{/docs-fragment docs_retriever}}

# {{docs-fragment generate}}
@env.task
async def generate(
    question: str, state: AgentState, concatenated_content: str, debug: bool
) -> AgentState:
    """
    Generate a code solution

    Args:
        question (str): The user question
        state (dict): The current graph state
        concatenated_content (str): The concatenated docs content
        debug (bool): Debug mode

    Returns:
        state (dict): New key added to state, generation
    """

    print("---GENERATING CODE SOLUTION---")

    messages = state.messages
    iterations = state.iterations
    error = state.error

    # We have been routed back to generation with an error
    if error == "yes":
        messages += [
            {
                "role": "user",
                "content": (
                    "Now, try again. Invoke the code tool to structure the output "
                    "with a prefix, imports, and code block:"
                ),
            }
        ]

    code_gen_chain = await generate_code_gen_chain(debug)

    # Solution
    code_solution = code_gen_chain.invoke(
        {
            "context": concatenated_content,
            "messages": (
                messages if messages else [{"role": "user", "content": question}]
            ),
        }
    )

    messages += [
        {
            "role": "assistant",
            "content": f"{code_solution.prefix} \n Imports: {code_solution.imports} \n Code: {code_solution.code}",
        }
    ]

    return AgentState(
        messages=messages,
        generation=code_solution,
        iterations=iterations + 1,
        error=error,
        output=state.output,
    )

# {{/docs-fragment generate}}

# {{docs-fragment code_check}}
@env.task
async def code_check(state: AgentState) -> AgentState:
    """
    Check code

    Args:
        state (dict): The current graph state

    Returns:
        state (dict): New key added to state, error
    """

    print("---CHECKING CODE---")

    # State
    messages = state.messages
    code_solution = state.generation
    iterations = state.iterations

    # Get solution components
    imports = code_solution.imports.strip()
    code = code_solution.code.strip()

    # Create temp file for imports
    with tempfile.NamedTemporaryFile(
        mode="w", suffix=".py", delete=False
    ) as imports_file:
        imports_file.write(imports + "\n")
        imports_path = imports_file.name

    # Create temp file for code body
    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as code_file:
        code_file.write(imports + "\n" + code + "\n")
        code_path = code_file.name

    # Check imports
    import_output, import_exit_code = await code_runner_task(
        script=await File.from_local(imports_path)
    )

    if import_exit_code.strip() != "0":
        print("---CODE IMPORT CHECK: FAILED---")
        error_message = [
            {
                "role": "user",
                "content": f"Your solution failed the import test: {import_output}",
            }
        ]
        messages += error_message
        return AgentState(
            generation=code_solution,
            messages=messages,
            iterations=iterations,
            error="yes",
            output=import_output,
        )
    else:
        print("---CODE IMPORT CHECK: PASSED---")

    # Check execution
    code_output, code_exit_code = await code_runner_task(
        script=await File.from_local(code_path)
    )

    if code_exit_code.strip() != "0":
        print("---CODE BLOCK CHECK: FAILED---")
        error_message = [
            {
                "role": "user",
                "content": f"Your solution failed the code execution test: {code_output}",
            }
        ]
        messages += error_message
        return AgentState(
            generation=code_solution,
            messages=messages,
            iterations=iterations,
            error="yes",
            output=code_output,
        )
    else:
        print("---CODE BLOCK CHECK: PASSED---")

    # No errors
    print("---NO CODE TEST FAILURES---")

    return AgentState(
        generation=code_solution,
        messages=messages,
        iterations=iterations,
        error="no",
        output=code_output,
    )

# {{/docs-fragment code_check}}

# {{docs-fragment reflect}}
@env.task
async def reflect(
    state: AgentState, concatenated_content: str, debug: bool
) -> AgentState:
    """
    Reflect on errors

    Args:
        state (dict): The current graph state
        concatenated_content (str): Concatenated docs content
        debug (bool): Debug mode

    Returns:
        state (dict): New key added to state, reflection
    """

    print("---REFLECTING---")

    # State
    messages = state.messages
    iterations = state.iterations
    code_solution = state.generation

    # Prompt reflection
    code_gen_chain = await generate_code_gen_chain(debug)

    # Add reflection
    reflections = code_gen_chain.invoke(
        {"context": concatenated_content, "messages": messages}
    )

    messages += [
        {
            "role": "assistant",
            "content": f"Here are reflections on the error: {reflections}",
        }
    ]

    return AgentState(
        generation=code_solution,
        messages=messages,
        iterations=iterations,
        error=state.error,
        output=state.output,
    )

# {{/docs-fragment reflect}}

# {{docs-fragment main}}
@env.task
async def main(
    question: str = (
        "Define a two-task pattern where the second catches OOM from the first and retries with more memory."
    ),
    url: str = "https://pre-release-v2.docs-builder.pages.dev/docs/byoc/user-guide/",
    max_iterations: int = 3,
    debug: bool = False,
) -> str:
    concatenated_content = await docs_retriever(url=url)

    state: AgentState = AgentState()
    iterations = 0

    while True:
        with flyte.group(f"code-generation-pass-{iterations + 1}"):
            state = await generate(question, state, concatenated_content, debug)
            state = await code_check(state)

            error = state.error
            iterations = state.iterations

            if error == "no" or iterations >= max_iterations:
                print("---DECISION: FINISH---")
                code_solution = state.generation

                prefix = code_solution.prefix
                imports = code_solution.imports
                code = code_solution.code

                code_output = state.output

                return f"""{prefix}

{imports}
{code}

Result of code execution:
{code_output}
"""
            else:
                print("---DECISION: RE-TRY SOLUTION---")
                state = await reflect(state, concatenated_content, debug)

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
    run.wait()

# {{/docs-fragment main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/code_runner/agent.py*

This task verifies that the generated code runs as expected.
It tests the import statements first, then executes the full code.
It records the output and any error messages in the agent state for further analysis.

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "langchain-core==0.3.66",
#    "langchain-openai==0.3.24",
#    "langchain-community==0.3.26",
#    "beautifulsoup4==4.13.4",
#    "docker==7.1.0",
# ]
# main = "main"
# params = ""
# ///

# {{docs-fragment code_runner_task}}
import flyte
from flyte.extras import ContainerTask
from flyte.io import File

code_runner_task = ContainerTask(
    name="run_flyte_v2",
    image=flyte.Image.from_debian_base(),
    input_data_dir="/var/inputs",
    output_data_dir="/var/outputs",
    inputs={"script": File},
    outputs={"result": str, "exit_code": str},
    command=[
        "/bin/bash",
        "-c",
        (
            "set -o pipefail && "
            "uv run --script /var/inputs/script > /var/outputs/result 2>&1; "
            "echo $? > /var/outputs/exit_code"
        ),
    ],
    resources=flyte.Resources(cpu=1, memory="1Gi"),
)

# {{/docs-fragment code_runner_task}}

# {{docs-fragment env}}
import tempfile
from typing import Optional

from langchain_core.runnables import Runnable
from pydantic import BaseModel, Field

container_env = flyte.TaskEnvironment.from_task(
    "code-runner-container", code_runner_task
)

env = flyte.TaskEnvironment(
    name="code_runner",
    secrets=[flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY")],
    image=flyte.Image.from_uv_script(__file__, name="code-runner-agent"),
    resources=flyte.Resources(cpu=1),
    depends_on=[container_env],
)

# {{/docs-fragment env}}

# {{docs-fragment code_base_model}}
class Code(BaseModel):
    """Schema for code solutions to questions about Flyte v2."""

    prefix: str = Field(
        default="", description="Description of the problem and approach"
    )
    imports: str = Field(
        default="", description="Code block with just import statements"
    )
    code: str = Field(
        default="", description="Code block not including import statements"
    )

# {{/docs-fragment code_base_model}}

# {{docs-fragment agent_state}}
class AgentState(BaseModel):
    messages: list[dict[str, str]] = Field(default_factory=list)
    generation: Code = Field(default_factory=Code)
    iterations: int = 0
    error: str = "no"
    output: Optional[str] = None

# {{/docs-fragment agent_state}}

# {{docs-fragment generate_code_gen_chain}}
async def generate_code_gen_chain(debug: bool) -> Runnable:
    from langchain_core.prompts import ChatPromptTemplate
    from langchain_openai import ChatOpenAI

    # Grader prompt
    code_gen_prompt = ChatPromptTemplate.from_messages(
        [
            (
                "system",
                """
You are a coding assistant with expertise in Python.
You are able to execute the Flyte v2 code locally in a sandbox environment.

Use the following pattern to execute the code:

<code>
if __name__ == "__main__":
    flyte.init_from_config()
    print(flyte.run(...))
</code>

Your response will be shown to the user.
Here is a full set of documentation:

-------
{context}
-------

Answer the user question based on the above provided documentation.
Ensure any code you provide can be executed with all required imports and variables defined.
Structure your answer with a description of the code solution.
Then list the imports. And finally list the functioning code block.
Here is the user question:""",
            ),
            ("placeholder", "{messages}"),
        ]
    )

    expt_llm = "gpt-4o" if not debug else "gpt-4o-mini"
    llm = ChatOpenAI(temperature=0, model=expt_llm)

    code_gen_chain = code_gen_prompt | llm.with_structured_output(Code)
    return code_gen_chain

# {{/docs-fragment generate_code_gen_chain}}

# {{docs-fragment docs_retriever}}
@env.task
async def docs_retriever(url: str) -> str:
    from bs4 import BeautifulSoup
    from langchain_community.document_loaders.recursive_url_loader import (
        RecursiveUrlLoader,
    )

    loader = RecursiveUrlLoader(
        url=url, max_depth=20, extractor=lambda x: BeautifulSoup(x, "html.parser").text
    )
    docs = loader.load()

    # Sort the list based on the URLs and get the text
    d_sorted = sorted(docs, key=lambda x: x.metadata["source"])
    d_reversed = list(reversed(d_sorted))

    concatenated_content = "\n\n\n --- \n\n\n".join(
        [doc.page_content for doc in d_reversed]
    )
    return concatenated_content

# {{/docs-fragment docs_retriever}}

# {{docs-fragment generate}}
@env.task
async def generate(
    question: str, state: AgentState, concatenated_content: str, debug: bool
) -> AgentState:
    """
    Generate a code solution

    Args:
        question (str): The user question
        state (dict): The current graph state
        concatenated_content (str): The concatenated docs content
        debug (bool): Debug mode

    Returns:
        state (dict): New key added to state, generation
    """

    print("---GENERATING CODE SOLUTION---")

    messages = state.messages
    iterations = state.iterations
    error = state.error

    # We have been routed back to generation with an error
    if error == "yes":
        messages += [
            {
                "role": "user",
                "content": (
                    "Now, try again. Invoke the code tool to structure the output "
                    "with a prefix, imports, and code block:"
                ),
            }
        ]

    code_gen_chain = await generate_code_gen_chain(debug)

    # Solution
    code_solution = code_gen_chain.invoke(
        {
            "context": concatenated_content,
            "messages": (
                messages if messages else [{"role": "user", "content": question}]
            ),
        }
    )

    messages += [
        {
            "role": "assistant",
            "content": f"{code_solution.prefix} \n Imports: {code_solution.imports} \n Code: {code_solution.code}",
        }
    ]

    return AgentState(
        messages=messages,
        generation=code_solution,
        iterations=iterations + 1,
        error=error,
        output=state.output,
    )

# {{/docs-fragment generate}}

# {{docs-fragment code_check}}
@env.task
async def code_check(state: AgentState) -> AgentState:
    """
    Check code

    Args:
        state (dict): The current graph state

    Returns:
        state (dict): New key added to state, error
    """

    print("---CHECKING CODE---")

    # State
    messages = state.messages
    code_solution = state.generation
    iterations = state.iterations

    # Get solution components
    imports = code_solution.imports.strip()
    code = code_solution.code.strip()

    # Create temp file for imports
    with tempfile.NamedTemporaryFile(
        mode="w", suffix=".py", delete=False
    ) as imports_file:
        imports_file.write(imports + "\n")
        imports_path = imports_file.name

    # Create temp file for code body
    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as code_file:
        code_file.write(imports + "\n" + code + "\n")
        code_path = code_file.name

    # Check imports
    import_output, import_exit_code = await code_runner_task(
        script=await File.from_local(imports_path)
    )

    if import_exit_code.strip() != "0":
        print("---CODE IMPORT CHECK: FAILED---")
        error_message = [
            {
                "role": "user",
                "content": f"Your solution failed the import test: {import_output}",
            }
        ]
        messages += error_message
        return AgentState(
            generation=code_solution,
            messages=messages,
            iterations=iterations,
            error="yes",
            output=import_output,
        )
    else:
        print("---CODE IMPORT CHECK: PASSED---")

    # Check execution
    code_output, code_exit_code = await code_runner_task(
        script=await File.from_local(code_path)
    )

    if code_exit_code.strip() != "0":
        print("---CODE BLOCK CHECK: FAILED---")
        error_message = [
            {
                "role": "user",
                "content": f"Your solution failed the code execution test: {code_output}",
            }
        ]
        messages += error_message
        return AgentState(
            generation=code_solution,
            messages=messages,
            iterations=iterations,
            error="yes",
            output=code_output,
        )
    else:
        print("---CODE BLOCK CHECK: PASSED---")

    # No errors
    print("---NO CODE TEST FAILURES---")

    return AgentState(
        generation=code_solution,
        messages=messages,
        iterations=iterations,
        error="no",
        output=code_output,
    )

# {{/docs-fragment code_check}}

# {{docs-fragment reflect}}
@env.task
async def reflect(
    state: AgentState, concatenated_content: str, debug: bool
) -> AgentState:
    """
    Reflect on errors

    Args:
        state (dict): The current graph state
        concatenated_content (str): Concatenated docs content
        debug (bool): Debug mode

    Returns:
        state (dict): New key added to state, reflection
    """

    print("---REFLECTING---")

    # State
    messages = state.messages
    iterations = state.iterations
    code_solution = state.generation

    # Prompt reflection
    code_gen_chain = await generate_code_gen_chain(debug)

    # Add reflection
    reflections = code_gen_chain.invoke(
        {"context": concatenated_content, "messages": messages}
    )

    messages += [
        {
            "role": "assistant",
            "content": f"Here are reflections on the error: {reflections}",
        }
    ]

    return AgentState(
        generation=code_solution,
        messages=messages,
        iterations=iterations,
        error=state.error,
        output=state.output,
    )

# {{/docs-fragment reflect}}

# {{docs-fragment main}}
@env.task
async def main(
    question: str = (
        "Define a two-task pattern where the second catches OOM from the first and retries with more memory."
    ),
    url: str = "https://pre-release-v2.docs-builder.pages.dev/docs/byoc/user-guide/",
    max_iterations: int = 3,
    debug: bool = False,
) -> str:
    concatenated_content = await docs_retriever(url=url)

    state: AgentState = AgentState()
    iterations = 0

    while True:
        with flyte.group(f"code-generation-pass-{iterations + 1}"):
            state = await generate(question, state, concatenated_content, debug)
            state = await code_check(state)

            error = state.error
            iterations = state.iterations

            if error == "no" or iterations >= max_iterations:
                print("---DECISION: FINISH---")
                code_solution = state.generation

                prefix = code_solution.prefix
                imports = code_solution.imports
                code = code_solution.code

                code_output = state.output

                return f"""{prefix}

{imports}
{code}

Result of code execution:
{code_output}
"""
            else:
                print("---DECISION: RE-TRY SOLUTION---")
                state = await reflect(state, concatenated_content, debug)

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
    run.wait()

# {{/docs-fragment main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/code_runner/agent.py*

If an error occurs, a separate task reflects on the failure and generates a response.
This reflection is added to the agent state to guide future iterations.

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "langchain-core==0.3.66",
#    "langchain-openai==0.3.24",
#    "langchain-community==0.3.26",
#    "beautifulsoup4==4.13.4",
#    "docker==7.1.0",
# ]
# main = "main"
# params = ""
# ///

# {{docs-fragment code_runner_task}}
import flyte
from flyte.extras import ContainerTask
from flyte.io import File

code_runner_task = ContainerTask(
    name="run_flyte_v2",
    image=flyte.Image.from_debian_base(),
    input_data_dir="/var/inputs",
    output_data_dir="/var/outputs",
    inputs={"script": File},
    outputs={"result": str, "exit_code": str},
    command=[
        "/bin/bash",
        "-c",
        (
            "set -o pipefail && "
            "uv run --script /var/inputs/script > /var/outputs/result 2>&1; "
            "echo $? > /var/outputs/exit_code"
        ),
    ],
    resources=flyte.Resources(cpu=1, memory="1Gi"),
)

# {{/docs-fragment code_runner_task}}

# {{docs-fragment env}}
import tempfile
from typing import Optional

from langchain_core.runnables import Runnable
from pydantic import BaseModel, Field

container_env = flyte.TaskEnvironment.from_task(
    "code-runner-container", code_runner_task
)

env = flyte.TaskEnvironment(
    name="code_runner",
    secrets=[flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY")],
    image=flyte.Image.from_uv_script(__file__, name="code-runner-agent"),
    resources=flyte.Resources(cpu=1),
    depends_on=[container_env],
)

# {{/docs-fragment env}}

# {{docs-fragment code_base_model}}
class Code(BaseModel):
    """Schema for code solutions to questions about Flyte v2."""

    prefix: str = Field(
        default="", description="Description of the problem and approach"
    )
    imports: str = Field(
        default="", description="Code block with just import statements"
    )
    code: str = Field(
        default="", description="Code block not including import statements"
    )

# {{/docs-fragment code_base_model}}

# {{docs-fragment agent_state}}
class AgentState(BaseModel):
    messages: list[dict[str, str]] = Field(default_factory=list)
    generation: Code = Field(default_factory=Code)
    iterations: int = 0
    error: str = "no"
    output: Optional[str] = None

# {{/docs-fragment agent_state}}

# {{docs-fragment generate_code_gen_chain}}
async def generate_code_gen_chain(debug: bool) -> Runnable:
    from langchain_core.prompts import ChatPromptTemplate
    from langchain_openai import ChatOpenAI

    # Grader prompt
    code_gen_prompt = ChatPromptTemplate.from_messages(
        [
            (
                "system",
                """
You are a coding assistant with expertise in Python.
You are able to execute the Flyte v2 code locally in a sandbox environment.

Use the following pattern to execute the code:

<code>
if __name__ == "__main__":
    flyte.init_from_config()
    print(flyte.run(...))
</code>

Your response will be shown to the user.
Here is a full set of documentation:

-------
{context}
-------

Answer the user question based on the above provided documentation.
Ensure any code you provide can be executed with all required imports and variables defined.
Structure your answer with a description of the code solution.
Then list the imports. And finally list the functioning code block.
Here is the user question:""",
            ),
            ("placeholder", "{messages}"),
        ]
    )

    expt_llm = "gpt-4o" if not debug else "gpt-4o-mini"
    llm = ChatOpenAI(temperature=0, model=expt_llm)

    code_gen_chain = code_gen_prompt | llm.with_structured_output(Code)
    return code_gen_chain

# {{/docs-fragment generate_code_gen_chain}}

# {{docs-fragment docs_retriever}}
@env.task
async def docs_retriever(url: str) -> str:
    from bs4 import BeautifulSoup
    from langchain_community.document_loaders.recursive_url_loader import (
        RecursiveUrlLoader,
    )

    loader = RecursiveUrlLoader(
        url=url, max_depth=20, extractor=lambda x: BeautifulSoup(x, "html.parser").text
    )
    docs = loader.load()

    # Sort the list based on the URLs and get the text
    d_sorted = sorted(docs, key=lambda x: x.metadata["source"])
    d_reversed = list(reversed(d_sorted))

    concatenated_content = "\n\n\n --- \n\n\n".join(
        [doc.page_content for doc in d_reversed]
    )
    return concatenated_content

# {{/docs-fragment docs_retriever}}

# {{docs-fragment generate}}
@env.task
async def generate(
    question: str, state: AgentState, concatenated_content: str, debug: bool
) -> AgentState:
    """
    Generate a code solution

    Args:
        question (str): The user question
        state (dict): The current graph state
        concatenated_content (str): The concatenated docs content
        debug (bool): Debug mode

    Returns:
        state (dict): New key added to state, generation
    """

    print("---GENERATING CODE SOLUTION---")

    messages = state.messages
    iterations = state.iterations
    error = state.error

    # We have been routed back to generation with an error
    if error == "yes":
        messages += [
            {
                "role": "user",
                "content": (
                    "Now, try again. Invoke the code tool to structure the output "
                    "with a prefix, imports, and code block:"
                ),
            }
        ]

    code_gen_chain = await generate_code_gen_chain(debug)

    # Solution
    code_solution = code_gen_chain.invoke(
        {
            "context": concatenated_content,
            "messages": (
                messages if messages else [{"role": "user", "content": question}]
            ),
        }
    )

    messages += [
        {
            "role": "assistant",
            "content": f"{code_solution.prefix} \n Imports: {code_solution.imports} \n Code: {code_solution.code}",
        }
    ]

    return AgentState(
        messages=messages,
        generation=code_solution,
        iterations=iterations + 1,
        error=error,
        output=state.output,
    )

# {{/docs-fragment generate}}

# {{docs-fragment code_check}}
@env.task
async def code_check(state: AgentState) -> AgentState:
    """
    Check code

    Args:
        state (dict): The current graph state

    Returns:
        state (dict): New key added to state, error
    """

    print("---CHECKING CODE---")

    # State
    messages = state.messages
    code_solution = state.generation
    iterations = state.iterations

    # Get solution components
    imports = code_solution.imports.strip()
    code = code_solution.code.strip()

    # Create temp file for imports
    with tempfile.NamedTemporaryFile(
        mode="w", suffix=".py", delete=False
    ) as imports_file:
        imports_file.write(imports + "\n")
        imports_path = imports_file.name

    # Create temp file for code body
    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as code_file:
        code_file.write(imports + "\n" + code + "\n")
        code_path = code_file.name

    # Check imports
    import_output, import_exit_code = await code_runner_task(
        script=await File.from_local(imports_path)
    )

    if import_exit_code.strip() != "0":
        print("---CODE IMPORT CHECK: FAILED---")
        error_message = [
            {
                "role": "user",
                "content": f"Your solution failed the import test: {import_output}",
            }
        ]
        messages += error_message
        return AgentState(
            generation=code_solution,
            messages=messages,
            iterations=iterations,
            error="yes",
            output=import_output,
        )
    else:
        print("---CODE IMPORT CHECK: PASSED---")

    # Check execution
    code_output, code_exit_code = await code_runner_task(
        script=await File.from_local(code_path)
    )

    if code_exit_code.strip() != "0":
        print("---CODE BLOCK CHECK: FAILED---")
        error_message = [
            {
                "role": "user",
                "content": f"Your solution failed the code execution test: {code_output}",
            }
        ]
        messages += error_message
        return AgentState(
            generation=code_solution,
            messages=messages,
            iterations=iterations,
            error="yes",
            output=code_output,
        )
    else:
        print("---CODE BLOCK CHECK: PASSED---")

    # No errors
    print("---NO CODE TEST FAILURES---")

    return AgentState(
        generation=code_solution,
        messages=messages,
        iterations=iterations,
        error="no",
        output=code_output,
    )

# {{/docs-fragment code_check}}

# {{docs-fragment reflect}}
@env.task
async def reflect(
    state: AgentState, concatenated_content: str, debug: bool
) -> AgentState:
    """
    Reflect on errors

    Args:
        state (dict): The current graph state
        concatenated_content (str): Concatenated docs content
        debug (bool): Debug mode

    Returns:
        state (dict): New key added to state, reflection
    """

    print("---REFLECTING---")

    # State
    messages = state.messages
    iterations = state.iterations
    code_solution = state.generation

    # Prompt reflection
    code_gen_chain = await generate_code_gen_chain(debug)

    # Add reflection
    reflections = code_gen_chain.invoke(
        {"context": concatenated_content, "messages": messages}
    )

    messages += [
        {
            "role": "assistant",
            "content": f"Here are reflections on the error: {reflections}",
        }
    ]

    return AgentState(
        generation=code_solution,
        messages=messages,
        iterations=iterations,
        error=state.error,
        output=state.output,
    )

# {{/docs-fragment reflect}}

# {{docs-fragment main}}
@env.task
async def main(
    question: str = (
        "Define a two-task pattern where the second catches OOM from the first and retries with more memory."
    ),
    url: str = "https://pre-release-v2.docs-builder.pages.dev/docs/byoc/user-guide/",
    max_iterations: int = 3,
    debug: bool = False,
) -> str:
    concatenated_content = await docs_retriever(url=url)

    state: AgentState = AgentState()
    iterations = 0

    while True:
        with flyte.group(f"code-generation-pass-{iterations + 1}"):
            state = await generate(question, state, concatenated_content, debug)
            state = await code_check(state)

            error = state.error
            iterations = state.iterations

            if error == "no" or iterations >= max_iterations:
                print("---DECISION: FINISH---")
                code_solution = state.generation

                prefix = code_solution.prefix
                imports = code_solution.imports
                code = code_solution.code

                code_output = state.output

                return f"""{prefix}

{imports}
{code}

Result of code execution:
{code_output}
"""
            else:
                print("---DECISION: RE-TRY SOLUTION---")
                state = await reflect(state, concatenated_content, debug)

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
    run.wait()

# {{/docs-fragment main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/code_runner/agent.py*

Finally, we define a `main` task that runs the code agent and orchestrates the steps above.
If the code execution fails, we reflect on the error and retry until we reach the maximum number of iterations.

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "langchain-core==0.3.66",
#    "langchain-openai==0.3.24",
#    "langchain-community==0.3.26",
#    "beautifulsoup4==4.13.4",
#    "docker==7.1.0",
# ]
# main = "main"
# params = ""
# ///

# {{docs-fragment code_runner_task}}
import flyte
from flyte.extras import ContainerTask
from flyte.io import File

code_runner_task = ContainerTask(
    name="run_flyte_v2",
    image=flyte.Image.from_debian_base(),
    input_data_dir="/var/inputs",
    output_data_dir="/var/outputs",
    inputs={"script": File},
    outputs={"result": str, "exit_code": str},
    command=[
        "/bin/bash",
        "-c",
        (
            "set -o pipefail && "
            "uv run --script /var/inputs/script > /var/outputs/result 2>&1; "
            "echo $? > /var/outputs/exit_code"
        ),
    ],
    resources=flyte.Resources(cpu=1, memory="1Gi"),
)

# {{/docs-fragment code_runner_task}}

# {{docs-fragment env}}
import tempfile
from typing import Optional

from langchain_core.runnables import Runnable
from pydantic import BaseModel, Field

container_env = flyte.TaskEnvironment.from_task(
    "code-runner-container", code_runner_task
)

env = flyte.TaskEnvironment(
    name="code_runner",
    secrets=[flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY")],
    image=flyte.Image.from_uv_script(__file__, name="code-runner-agent"),
    resources=flyte.Resources(cpu=1),
    depends_on=[container_env],
)

# {{/docs-fragment env}}

# {{docs-fragment code_base_model}}
class Code(BaseModel):
    """Schema for code solutions to questions about Flyte v2."""

    prefix: str = Field(
        default="", description="Description of the problem and approach"
    )
    imports: str = Field(
        default="", description="Code block with just import statements"
    )
    code: str = Field(
        default="", description="Code block not including import statements"
    )

# {{/docs-fragment code_base_model}}

# {{docs-fragment agent_state}}
class AgentState(BaseModel):
    messages: list[dict[str, str]] = Field(default_factory=list)
    generation: Code = Field(default_factory=Code)
    iterations: int = 0
    error: str = "no"
    output: Optional[str] = None

# {{/docs-fragment agent_state}}

# {{docs-fragment generate_code_gen_chain}}
async def generate_code_gen_chain(debug: bool) -> Runnable:
    from langchain_core.prompts import ChatPromptTemplate
    from langchain_openai import ChatOpenAI

    # Grader prompt
    code_gen_prompt = ChatPromptTemplate.from_messages(
        [
            (
                "system",
                """
You are a coding assistant with expertise in Python.
You are able to execute the Flyte v2 code locally in a sandbox environment.

Use the following pattern to execute the code:

<code>
if __name__ == "__main__":
    flyte.init_from_config()
    print(flyte.run(...))
</code>

Your response will be shown to the user.
Here is a full set of documentation:

-------
{context}
-------

Answer the user question based on the above provided documentation.
Ensure any code you provide can be executed with all required imports and variables defined.
Structure your answer with a description of the code solution.
Then list the imports. And finally list the functioning code block.
Here is the user question:""",
            ),
            ("placeholder", "{messages}"),
        ]
    )

    expt_llm = "gpt-4o" if not debug else "gpt-4o-mini"
    llm = ChatOpenAI(temperature=0, model=expt_llm)

    code_gen_chain = code_gen_prompt | llm.with_structured_output(Code)
    return code_gen_chain

# {{/docs-fragment generate_code_gen_chain}}

# {{docs-fragment docs_retriever}}
@env.task
async def docs_retriever(url: str) -> str:
    from bs4 import BeautifulSoup
    from langchain_community.document_loaders.recursive_url_loader import (
        RecursiveUrlLoader,
    )

    loader = RecursiveUrlLoader(
        url=url, max_depth=20, extractor=lambda x: BeautifulSoup(x, "html.parser").text
    )
    docs = loader.load()

    # Sort the list based on the URLs and get the text
    d_sorted = sorted(docs, key=lambda x: x.metadata["source"])
    d_reversed = list(reversed(d_sorted))

    concatenated_content = "\n\n\n --- \n\n\n".join(
        [doc.page_content for doc in d_reversed]
    )
    return concatenated_content

# {{/docs-fragment docs_retriever}}

# {{docs-fragment generate}}
@env.task
async def generate(
    question: str, state: AgentState, concatenated_content: str, debug: bool
) -> AgentState:
    """
    Generate a code solution

    Args:
        question (str): The user question
        state (dict): The current graph state
        concatenated_content (str): The concatenated docs content
        debug (bool): Debug mode

    Returns:
        state (dict): New key added to state, generation
    """

    print("---GENERATING CODE SOLUTION---")

    messages = state.messages
    iterations = state.iterations
    error = state.error

    # We have been routed back to generation with an error
    if error == "yes":
        messages += [
            {
                "role": "user",
                "content": (
                    "Now, try again. Invoke the code tool to structure the output "
                    "with a prefix, imports, and code block:"
                ),
            }
        ]

    code_gen_chain = await generate_code_gen_chain(debug)

    # Solution
    code_solution = code_gen_chain.invoke(
        {
            "context": concatenated_content,
            "messages": (
                messages if messages else [{"role": "user", "content": question}]
            ),
        }
    )

    messages += [
        {
            "role": "assistant",
            "content": f"{code_solution.prefix} \n Imports: {code_solution.imports} \n Code: {code_solution.code}",
        }
    ]

    return AgentState(
        messages=messages,
        generation=code_solution,
        iterations=iterations + 1,
        error=error,
        output=state.output,
    )

# {{/docs-fragment generate}}

# {{docs-fragment code_check}}
@env.task
async def code_check(state: AgentState) -> AgentState:
    """
    Check code

    Args:
        state (dict): The current graph state

    Returns:
        state (dict): New key added to state, error
    """

    print("---CHECKING CODE---")

    # State
    messages = state.messages
    code_solution = state.generation
    iterations = state.iterations

    # Get solution components
    imports = code_solution.imports.strip()
    code = code_solution.code.strip()

    # Create temp file for imports
    with tempfile.NamedTemporaryFile(
        mode="w", suffix=".py", delete=False
    ) as imports_file:
        imports_file.write(imports + "\n")
        imports_path = imports_file.name

    # Create temp file for code body
    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as code_file:
        code_file.write(imports + "\n" + code + "\n")
        code_path = code_file.name

    # Check imports
    import_output, import_exit_code = await code_runner_task(
        script=await File.from_local(imports_path)
    )

    if import_exit_code.strip() != "0":
        print("---CODE IMPORT CHECK: FAILED---")
        error_message = [
            {
                "role": "user",
                "content": f"Your solution failed the import test: {import_output}",
            }
        ]
        messages += error_message
        return AgentState(
            generation=code_solution,
            messages=messages,
            iterations=iterations,
            error="yes",
            output=import_output,
        )
    else:
        print("---CODE IMPORT CHECK: PASSED---")

    # Check execution
    code_output, code_exit_code = await code_runner_task(
        script=await File.from_local(code_path)
    )

    if code_exit_code.strip() != "0":
        print("---CODE BLOCK CHECK: FAILED---")
        error_message = [
            {
                "role": "user",
                "content": f"Your solution failed the code execution test: {code_output}",
            }
        ]
        messages += error_message
        return AgentState(
            generation=code_solution,
            messages=messages,
            iterations=iterations,
            error="yes",
            output=code_output,
        )
    else:
        print("---CODE BLOCK CHECK: PASSED---")

    # No errors
    print("---NO CODE TEST FAILURES---")

    return AgentState(
        generation=code_solution,
        messages=messages,
        iterations=iterations,
        error="no",
        output=code_output,
    )

# {{/docs-fragment code_check}}

# {{docs-fragment reflect}}
@env.task
async def reflect(
    state: AgentState, concatenated_content: str, debug: bool
) -> AgentState:
    """
    Reflect on errors

    Args:
        state (dict): The current graph state
        concatenated_content (str): Concatenated docs content
        debug (bool): Debug mode

    Returns:
        state (dict): New key added to state, reflection
    """

    print("---REFLECTING---")

    # State
    messages = state.messages
    iterations = state.iterations
    code_solution = state.generation

    # Prompt reflection
    code_gen_chain = await generate_code_gen_chain(debug)

    # Add reflection
    reflections = code_gen_chain.invoke(
        {"context": concatenated_content, "messages": messages}
    )

    messages += [
        {
            "role": "assistant",
            "content": f"Here are reflections on the error: {reflections}",
        }
    ]

    return AgentState(
        generation=code_solution,
        messages=messages,
        iterations=iterations,
        error=state.error,
        output=state.output,
    )

# {{/docs-fragment reflect}}

# {{docs-fragment main}}
@env.task
async def main(
    question: str = (
        "Define a two-task pattern where the second catches OOM from the first and retries with more memory."
    ),
    url: str = "https://pre-release-v2.docs-builder.pages.dev/docs/byoc/user-guide/",
    max_iterations: int = 3,
    debug: bool = False,
) -> str:
    concatenated_content = await docs_retriever(url=url)

    state: AgentState = AgentState()
    iterations = 0

    while True:
        with flyte.group(f"code-generation-pass-{iterations + 1}"):
            state = await generate(question, state, concatenated_content, debug)
            state = await code_check(state)

            error = state.error
            iterations = state.iterations

            if error == "no" or iterations >= max_iterations:
                print("---DECISION: FINISH---")
                code_solution = state.generation

                prefix = code_solution.prefix
                imports = code_solution.imports
                code = code_solution.code

                code_output = state.output

                return f"""{prefix}

{imports}
{code}

Result of code execution:
{code_output}
"""
            else:
                print("---DECISION: RE-TRY SOLUTION---")
                state = await reflect(state, concatenated_content, debug)

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
    run.wait()

# {{/docs-fragment main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/code_runner/agent.py*

## Running the code agent

If things are working properly, you should see output similar to the following:

```
---GENERATING CODE SOLUTION---
---CHECKING CODE---
---CODE BLOCK CHECK: PASSED---
---NO CODE TEST FAILURES---
---DECISION: FINISH---
In this solution, we define two tasks using Flyte v2.
The first task, `oomer`, is designed to simulate an out-of-memory (OOM) error by attempting to allocate a large list.
The second task, `failure_recovery`, attempts to execute `oomer` and catches any OOM errors.
If an OOM error is caught, it retries the `oomer` task with increased memory resources.
This pattern demonstrates how to handle resource-related exceptions and dynamically adjust task configurations in Flyte workflows.

import asyncio
import flyte
import flyte.errors
env = flyte.TaskEnvironment(name="oom_example", resources=flyte.Resources(cpu=1, memory="250Mi"))

@env.task
async def oomer(x: int):
    large_list = [0] * 100000000  # Simulate OOM
    print(len(large_list))

@env.task
async def always_succeeds() -> int:
    await asyncio.sleep(1)
    return 42

...
CODE12
uv run agent.py
```


=== PAGE: https://www.union.ai/docs/v2/union/tutorials/text_to_sql ===

# Text-to-SQL

> [!NOTE]
> Code available [here](https://github.com/unionai/unionai-examples/tree/main/v2/tutorials/text_to_sql); based on work by [LlamaIndex](https://docs.llamaindex.ai/en/stable/examples/workflow/advanced_text_to_sql/).

Data analytics drives modern decision-making, but SQL often creates a bottleneck. Writing queries requires technical expertise, so non-technical stakeholders must rely on data teams. That translation layer slows everyone down.

Text-to-SQL narrows this gap by turning natural language into executable SQL queries. It lowers the barrier to structured data and makes databases accessible to more people.

In this tutorial, we build a Text-to-SQL workflow using LlamaIndex and evaluate it on the [WikiTableQuestions dataset](https://ppasupat.github.io/WikiTableQuestions/) (a benchmark of natural language questions over semi-structured tables). We then explore prompt optimization to see whether it improves accuracy and show how to track prompts and results over time. Along the way, we'll see what worked, what didn't, and what we learned about building durable evaluation pipelines. The pattern here can be adapted to your own datasets and workflows.

![Evaluation](https://raw.githubusercontent.com/unionai/unionai-docs-static/main/images/tutorials/text-to-sql/evaluation.png)

## Ingesting data

We start by ingesting the WikiTableQuestions dataset, which comes as CSV files, into a SQLite database. This database serves as the source of truth for our Text-to-SQL pipeline.

```
import asyncio
import fnmatch
import os
import re
import zipfile

import flyte
import pandas as pd
import requests
from flyte.io import Dir, File
from llama_index.core.llms import ChatMessage
from llama_index.core.prompts import ChatPromptTemplate
from llama_index.llms.openai import OpenAI
from pydantic import BaseModel, Field
from sqlalchemy import Column, Integer, MetaData, String, Table, create_engine
from utils import env

# {{docs-fragment table_info}}
class TableInfo(BaseModel):
    """Information regarding a structured table."""

    table_name: str = Field(..., description="table name (underscores only, no spaces)")
    table_summary: str = Field(
        ..., description="short, concise summary/caption of the table"
    )

# {{/docs-fragment table_info}}

@env.task
async def download_and_extract(zip_path: str, search_glob: str) -> Dir:
    """Download and extract the dataset zip file if not already available."""
    output_zip = "data.zip"
    extract_dir = "wiki_table_questions"

    if not os.path.exists(zip_path):
        response = requests.get(zip_path, stream=True)
        with open(output_zip, "wb") as f:
            for chunk in response.iter_content(chunk_size=8192):
                f.write(chunk)
    else:
        output_zip = zip_path
        print(f"Using existing file {output_zip}")

    os.makedirs(extract_dir, exist_ok=True)
    with zipfile.ZipFile(output_zip, "r") as zip_ref:
        for member in zip_ref.namelist():
            if fnmatch.fnmatch(member, search_glob):
                zip_ref.extract(member, extract_dir)

    remote_dir = await Dir.from_local(extract_dir)
    return remote_dir

async def read_csv_file(
    csv_file: File, nrows: int | None = None
) -> pd.DataFrame | None:
    """Safely download and parse a CSV file into a DataFrame."""
    try:
        local_csv_file = await csv_file.download()
        return pd.read_csv(local_csv_file, nrows=nrows)
    except Exception as e:
        print(f"Error parsing {csv_file.path}: {e}")
        return None

def sanitize_column_name(col_name: str) -> str:
    """Sanitize column names by replacing spaces/special chars with underscores."""
    return re.sub(r"\W+", "_", col_name)

async def create_table_from_dataframe(
    df: pd.DataFrame, table_name: str, engine, metadata_obj
):
    """Create a SQL table from a Pandas DataFrame."""
    # Sanitize column names
    sanitized_columns = {col: sanitize_column_name(col) for col in df.columns}
    df = df.rename(columns=sanitized_columns)

    # Define table columns based on DataFrame dtypes
    columns = [
        Column(col, String if dtype == "object" else Integer)
        for col, dtype in zip(df.columns, df.dtypes)
    ]

    table = Table(table_name, metadata_obj, *columns)

    # Create table in database
    metadata_obj.create_all(engine)

    # Insert data into table
    with engine.begin() as conn:
        for _, row in df.iterrows():
            conn.execute(table.insert().values(**row.to_dict()))

@flyte.trace
async def create_table(
    csv_file: File, table_info: TableInfo, database_path: str
) -> str:
    """Safely create a table from CSV if parsing succeeds."""
    df = await read_csv_file(csv_file)
    if df is None:
        return "false"

    print(f"Creating table: {table_info.table_name}")

    engine = create_engine(f"sqlite:///{database_path}")
    metadata_obj = MetaData()

    await create_table_from_dataframe(df, table_info.table_name, engine, metadata_obj)
    return "true"

@flyte.trace
async def llm_structured_predict(
    df_str: str,
    table_names: list[str],
    prompt_tmpl: ChatPromptTemplate,
    feedback: str,
    llm: OpenAI,
) -> TableInfo:
    return llm.structured_predict(
        TableInfo,
        prompt_tmpl,
        feedback=feedback,
        table_str=df_str,
        exclude_table_name_list=str(list(table_names)),
    )

async def generate_unique_table_info(
    df_str: str,
    table_names: list[str],
    prompt_tmpl: ChatPromptTemplate,
    llm: OpenAI,
    tablename_lock: asyncio.Lock,
    retries: int = 3,
) -> TableInfo | None:
    """Process a single CSV file to generate a unique TableInfo."""
    last_table_name = None
    for attempt in range(retries):
        feedback = ""
        if attempt > 0:
            feedback = f"Note: '{last_table_name}' already exists. Please pick a new name not in {table_names}."

        table_info = await llm_structured_predict(
            df_str, table_names, prompt_tmpl, feedback, llm
        )
        last_table_name = table_info.table_name

        async with tablename_lock:
            if table_info.table_name not in table_names:
                table_names.append(table_info.table_name)
                return table_info

        print(f"Table name {table_info.table_name} already exists, retrying...")

    return None

async def process_csv_file(
    csv_file: File,
    table_names: list[str],
    semaphore: asyncio.Semaphore,
    tablename_lock: asyncio.Lock,
    llm: OpenAI,
    prompt_tmpl: ChatPromptTemplate,
) -> TableInfo | None:
    """Process a single CSV file to generate a unique TableInfo."""
    async with semaphore:
        df = await read_csv_file(csv_file, nrows=10)
        if df is None:
            return None
        return await generate_unique_table_info(
            df.to_csv(), table_names, prompt_tmpl, llm, tablename_lock
        )

@env.task
async def extract_table_info(
    data_dir: Dir, model: str, concurrency: int
) -> list[TableInfo | None]:
    """Extract structured table information from CSV files."""
    table_names: list[str] = []
    semaphore = asyncio.Semaphore(concurrency)
    tablename_lock = asyncio.Lock()
    llm = OpenAI(model=model)

    prompt_str = """\
    Provide a JSON object with the following fields:

    - `table_name`: must be unique and descriptive (underscores only, no generic names).
    - `table_summary`: short and concise summary of the table.

    Do NOT use any of these table names: {exclude_table_name_list}

    Table:
    {table_str}

    {feedback}
    """
    prompt_tmpl = ChatPromptTemplate(
        message_templates=[ChatMessage.from_str(prompt_str, role="user")]
    )

    tasks = [
        process_csv_file(
            csv_file, table_names, semaphore, tablename_lock, llm, prompt_tmpl
        )
        async for csv_file in data_dir.walk()
    ]

    return await asyncio.gather(*tasks)

# {{docs-fragment data_ingestion}}
@env.task
async def data_ingestion(
    csv_zip_path: str = "https://github.com/ppasupat/WikiTableQuestions/releases/download/v1.0.2/WikiTableQuestions-1.0.2-compact.zip",
    search_glob: str = "WikiTableQuestions/csv/200-csv/*.csv",
    concurrency: int = 5,
    model: str = "gpt-4o-mini",
) -> tuple[File, list[TableInfo | None]]:
    """Main data ingestion pipeline: download → extract → analyze → create DB."""
    data_dir = await download_and_extract(csv_zip_path, search_glob)
    table_infos = await extract_table_info(data_dir, model, concurrency)

    database_path = "wiki_table_questions.db"

    i = 0
    async for csv_file in data_dir.walk():
        table_info = table_infos[i]
        if table_info:
            ok = await create_table(csv_file, table_info, database_path)
            if ok == "false":
                table_infos[i] = None
        else:
            print(f"Skipping table creation for {csv_file} due to missing TableInfo.")
        i += 1

    db_file = await File.from_local(database_path)
    return db_file, table_infos

# {{/docs-fragment data_ingestion}}
CODE0
import asyncio
import fnmatch
import os
import re
import zipfile

import flyte
import pandas as pd
import requests
from flyte.io import Dir, File
from llama_index.core.llms import ChatMessage
from llama_index.core.prompts import ChatPromptTemplate
from llama_index.llms.openai import OpenAI
from pydantic import BaseModel, Field
from sqlalchemy import Column, Integer, MetaData, String, Table, create_engine
from utils import env

# {{docs-fragment table_info}}
class TableInfo(BaseModel):
    """Information regarding a structured table."""

    table_name: str = Field(..., description="table name (underscores only, no spaces)")
    table_summary: str = Field(
        ..., description="short, concise summary/caption of the table"
    )

# {{/docs-fragment table_info}}

@env.task
async def download_and_extract(zip_path: str, search_glob: str) -> Dir:
    """Download and extract the dataset zip file if not already available."""
    output_zip = "data.zip"
    extract_dir = "wiki_table_questions"

    if not os.path.exists(zip_path):
        response = requests.get(zip_path, stream=True)
        with open(output_zip, "wb") as f:
            for chunk in response.iter_content(chunk_size=8192):
                f.write(chunk)
    else:
        output_zip = zip_path
        print(f"Using existing file {output_zip}")

    os.makedirs(extract_dir, exist_ok=True)
    with zipfile.ZipFile(output_zip, "r") as zip_ref:
        for member in zip_ref.namelist():
            if fnmatch.fnmatch(member, search_glob):
                zip_ref.extract(member, extract_dir)

    remote_dir = await Dir.from_local(extract_dir)
    return remote_dir

async def read_csv_file(
    csv_file: File, nrows: int | None = None
) -> pd.DataFrame | None:
    """Safely download and parse a CSV file into a DataFrame."""
    try:
        local_csv_file = await csv_file.download()
        return pd.read_csv(local_csv_file, nrows=nrows)
    except Exception as e:
        print(f"Error parsing {csv_file.path}: {e}")
        return None

def sanitize_column_name(col_name: str) -> str:
    """Sanitize column names by replacing spaces/special chars with underscores."""
    return re.sub(r"\W+", "_", col_name)

async def create_table_from_dataframe(
    df: pd.DataFrame, table_name: str, engine, metadata_obj
):
    """Create a SQL table from a Pandas DataFrame."""
    # Sanitize column names
    sanitized_columns = {col: sanitize_column_name(col) for col in df.columns}
    df = df.rename(columns=sanitized_columns)

    # Define table columns based on DataFrame dtypes
    columns = [
        Column(col, String if dtype == "object" else Integer)
        for col, dtype in zip(df.columns, df.dtypes)
    ]

    table = Table(table_name, metadata_obj, *columns)

    # Create table in database
    metadata_obj.create_all(engine)

    # Insert data into table
    with engine.begin() as conn:
        for _, row in df.iterrows():
            conn.execute(table.insert().values(**row.to_dict()))

@flyte.trace
async def create_table(
    csv_file: File, table_info: TableInfo, database_path: str
) -> str:
    """Safely create a table from CSV if parsing succeeds."""
    df = await read_csv_file(csv_file)
    if df is None:
        return "false"

    print(f"Creating table: {table_info.table_name}")

    engine = create_engine(f"sqlite:///{database_path}")
    metadata_obj = MetaData()

    await create_table_from_dataframe(df, table_info.table_name, engine, metadata_obj)
    return "true"

@flyte.trace
async def llm_structured_predict(
    df_str: str,
    table_names: list[str],
    prompt_tmpl: ChatPromptTemplate,
    feedback: str,
    llm: OpenAI,
) -> TableInfo:
    return llm.structured_predict(
        TableInfo,
        prompt_tmpl,
        feedback=feedback,
        table_str=df_str,
        exclude_table_name_list=str(list(table_names)),
    )

async def generate_unique_table_info(
    df_str: str,
    table_names: list[str],
    prompt_tmpl: ChatPromptTemplate,
    llm: OpenAI,
    tablename_lock: asyncio.Lock,
    retries: int = 3,
) -> TableInfo | None:
    """Process a single CSV file to generate a unique TableInfo."""
    last_table_name = None
    for attempt in range(retries):
        feedback = ""
        if attempt > 0:
            feedback = f"Note: '{last_table_name}' already exists. Please pick a new name not in {table_names}."

        table_info = await llm_structured_predict(
            df_str, table_names, prompt_tmpl, feedback, llm
        )
        last_table_name = table_info.table_name

        async with tablename_lock:
            if table_info.table_name not in table_names:
                table_names.append(table_info.table_name)
                return table_info

        print(f"Table name {table_info.table_name} already exists, retrying...")

    return None

async def process_csv_file(
    csv_file: File,
    table_names: list[str],
    semaphore: asyncio.Semaphore,
    tablename_lock: asyncio.Lock,
    llm: OpenAI,
    prompt_tmpl: ChatPromptTemplate,
) -> TableInfo | None:
    """Process a single CSV file to generate a unique TableInfo."""
    async with semaphore:
        df = await read_csv_file(csv_file, nrows=10)
        if df is None:
            return None
        return await generate_unique_table_info(
            df.to_csv(), table_names, prompt_tmpl, llm, tablename_lock
        )

@env.task
async def extract_table_info(
    data_dir: Dir, model: str, concurrency: int
) -> list[TableInfo | None]:
    """Extract structured table information from CSV files."""
    table_names: list[str] = []
    semaphore = asyncio.Semaphore(concurrency)
    tablename_lock = asyncio.Lock()
    llm = OpenAI(model=model)

    prompt_str = """\
    Provide a JSON object with the following fields:

    - `table_name`: must be unique and descriptive (underscores only, no generic names).
    - `table_summary`: short and concise summary of the table.

    Do NOT use any of these table names: {exclude_table_name_list}

    Table:
    {table_str}

    {feedback}
    """
    prompt_tmpl = ChatPromptTemplate(
        message_templates=[ChatMessage.from_str(prompt_str, role="user")]
    )

    tasks = [
        process_csv_file(
            csv_file, table_names, semaphore, tablename_lock, llm, prompt_tmpl
        )
        async for csv_file in data_dir.walk()
    ]

    return await asyncio.gather(*tasks)

# {{docs-fragment data_ingestion}}
@env.task
async def data_ingestion(
    csv_zip_path: str = "https://github.com/ppasupat/WikiTableQuestions/releases/download/v1.0.2/WikiTableQuestions-1.0.2-compact.zip",
    search_glob: str = "WikiTableQuestions/csv/200-csv/*.csv",
    concurrency: int = 5,
    model: str = "gpt-4o-mini",
) -> tuple[File, list[TableInfo | None]]:
    """Main data ingestion pipeline: download → extract → analyze → create DB."""
    data_dir = await download_and_extract(csv_zip_path, search_glob)
    table_infos = await extract_table_info(data_dir, model, concurrency)

    database_path = "wiki_table_questions.db"

    i = 0
    async for csv_file in data_dir.walk():
        table_info = table_infos[i]
        if table_info:
            ok = await create_table(csv_file, table_info, database_path)
            if ok == "false":
                table_infos[i] = None
        else:
            print(f"Skipping table creation for {csv_file} due to missing TableInfo.")
        i += 1

    db_file = await File.from_local(database_path)
    return db_file, table_infos

# {{/docs-fragment data_ingestion}}
CODE1
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "llama-index-core>=0.11.0",
#    "llama-index-llms-openai>=0.2.0",
#    "sqlalchemy>=2.0.0",
#    "pandas>=2.0.0",
#    "requests>=2.25.0",
#    "pydantic>=2.0.0",
# ]
# main = "text_to_sql"
# params = ""
# ///

import asyncio
from pathlib import Path

import flyte
from data_ingestion import TableInfo, data_ingestion
from flyte.io import Dir, File
from llama_index.core import (
    PromptTemplate,
    SQLDatabase,
    StorageContext,
    VectorStoreIndex,
    load_index_from_storage,
)
from llama_index.core.llms import ChatResponse
from llama_index.core.objects import ObjectIndex, SQLTableNodeMapping, SQLTableSchema
from llama_index.core.prompts.prompt_type import PromptType
from llama_index.core.retrievers import SQLRetriever
from llama_index.core.schema import TextNode
from llama_index.llms.openai import OpenAI
from sqlalchemy import create_engine, text
from utils import env

# {{docs-fragment index_tables}}
@flyte.trace
async def index_table(table_name: str, table_index_dir: str, database_uri: str) -> str:
    """Index a single table into vector store."""
    path = f"{table_index_dir}/{table_name}"
    engine = create_engine(database_uri)

    def _fetch_rows():
        with engine.connect() as conn:
            cursor = conn.execute(text(f'SELECT * FROM "{table_name}"'))
            return cursor.fetchall()

    result = await asyncio.to_thread(_fetch_rows)
    nodes = [TextNode(text=str(tuple(row))) for row in result]
    index = VectorStoreIndex(nodes)
    index.set_index_id("vector_index")
    index.storage_context.persist(path)

    return path

@env.task
async def index_all_tables(db_file: File) -> Dir:
    """Index all tables concurrently."""
    table_index_dir = "table_indices"
    Path(table_index_dir).mkdir(exist_ok=True)

    await db_file.download(local_path="local_db.sqlite")
    engine = create_engine("sqlite:///local_db.sqlite")
    sql_database = SQLDatabase(engine)

    tasks = [
        index_table(t, table_index_dir, "sqlite:///local_db.sqlite")
        for t in sql_database.get_usable_table_names()
    ]
    await asyncio.gather(*tasks)

    remote_dir = await Dir.from_local(table_index_dir)
    return remote_dir

# {{/docs-fragment index_tables}}

@flyte.trace
async def get_table_schema_context(
    table_schema_obj: SQLTableSchema,
    database_uri: str,
) -> str:
    """Retrieve schema + optional description context for a single table."""
    engine = create_engine(database_uri)
    sql_database = SQLDatabase(engine)

    table_info = sql_database.get_single_table_info(table_schema_obj.table_name)

    if table_schema_obj.context_str:
        table_info += f" The table description is: {table_schema_obj.context_str}"

    return table_info

@flyte.trace
async def get_table_row_context(
    table_schema_obj: SQLTableSchema,
    local_vector_index_dir: str,
    query: str,
) -> str:
    """Retrieve row-level context examples using vector search."""
    storage_context = StorageContext.from_defaults(
        persist_dir=str(f"{local_vector_index_dir}/{table_schema_obj.table_name}")
    )
    vector_index = load_index_from_storage(storage_context, index_id="vector_index")
    vector_retriever = vector_index.as_retriever(similarity_top_k=2)
    relevant_nodes = vector_retriever.retrieve(query)

    if not relevant_nodes:
        return ""

    row_context = "\nHere are some relevant example rows (values in the same order as columns above)\n"
    for node in relevant_nodes:
        row_context += str(node.get_content()) + "\n"

    return row_context

async def process_table(
    table_schema_obj: SQLTableSchema,
    database_uri: str,
    local_vector_index_dir: str,
    query: str,
) -> str:
    """Combine schema + row context for one table."""
    table_info = await get_table_schema_context(table_schema_obj, database_uri)
    row_context = await get_table_row_context(
        table_schema_obj, local_vector_index_dir, query
    )

    full_context = table_info
    if row_context:
        full_context += "\n" + row_context

    print(f"Table Info: {full_context}")
    return full_context

async def get_table_context_and_rows_str(
    query: str,
    database_uri: str,
    table_schema_objs: list[SQLTableSchema],
    vector_index_dir: Dir,
):
    """Get combined schema + row context for all tables."""
    local_vector_index_dir = await vector_index_dir.download()

    # run per-table work concurrently
    context_strs = await asyncio.gather(
        *[
            process_table(t, database_uri, local_vector_index_dir, query)
            for t in table_schema_objs
        ]
    )

    return "\n\n".join(context_strs)

# {{docs-fragment retrieve_tables}}
@env.task
async def retrieve_tables(
    query: str,
    table_infos: list[TableInfo | None],
    db_file: File,
    vector_index_dir: Dir,
) -> str:
    """Retrieve relevant tables and return schema context string."""
    await db_file.download(local_path="local_db.sqlite")
    engine = create_engine("sqlite:///local_db.sqlite")
    sql_database = SQLDatabase(engine)

    table_node_mapping = SQLTableNodeMapping(sql_database)
    table_schema_objs = [
        SQLTableSchema(table_name=t.table_name, context_str=t.table_summary)
        for t in table_infos
        if t is not None
    ]

    obj_index = ObjectIndex.from_objects(
        table_schema_objs,
        table_node_mapping,
        VectorStoreIndex,
    )
    obj_retriever = obj_index.as_retriever(similarity_top_k=3)

    retrieved_schemas = obj_retriever.retrieve(query)
    return await get_table_context_and_rows_str(
        query, "sqlite:///local_db.sqlite", retrieved_schemas, vector_index_dir
    )

# {{/docs-fragment retrieve_tables}}

def parse_response_to_sql(chat_response: ChatResponse) -> str:
    """Extract SQL query from LLM response."""
    response = chat_response.message.content
    sql_query_start = response.find("SQLQuery:")
    if sql_query_start != -1:
        response = response[sql_query_start:]
        if response.startswith("SQLQuery:"):
            response = response[len("SQLQuery:") :]
    sql_result_start = response.find("SQLResult:")
    if sql_result_start != -1:
        response = response[:sql_result_start]
    return response.strip().strip("CODE2

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/text_to_sql/text_to_sql.py*

The main `text_to_sql` task orchestrates the pipeline:

- Ingest data
- Build vector indices for each table
- Retrieve relevant tables and rows
- Generate SQL queries with an LLM
- Execute queries and synthesize answers

We use OpenAI GPT models with carefully structured prompts to maximize SQL correctness.

### Vector indexing

We index each table's rows semantically so the model can retrieve relevant examples during SQL generation.

CODE3").strip()

# {{docs-fragment sql_and_response}}
@env.task
async def generate_sql(query: str, table_context: str, model: str, prompt: str) -> str:
    """Generate SQL query from natural language question and table context."""
    llm = OpenAI(model=model)

    fmt_messages = (
        PromptTemplate(
            prompt,
            prompt_type=PromptType.TEXT_TO_SQL,
        )
        .partial_format(dialect="sqlite")
        .format_messages(query_str=query, schema=table_context)
    )

    chat_response = await llm.achat(fmt_messages)
    return parse_response_to_sql(chat_response)

@env.task
async def generate_response(query: str, sql: str, db_file: File, model: str) -> str:
    """Run SQL query on database and synthesize final response."""
    await db_file.download(local_path="local_db.sqlite")

    engine = create_engine("sqlite:///local_db.sqlite")
    sql_database = SQLDatabase(engine)
    sql_retriever = SQLRetriever(sql_database)

    retrieved_rows = sql_retriever.retrieve(sql)

    response_synthesis_prompt = PromptTemplate(
        "Given an input question, synthesize a response from the query results.\n"
        "Query: {query_str}\n"
        "SQL: {sql_query}\n"
        "SQL Response: {context_str}\n"
        "Response: "
    )

    llm = OpenAI(model=model)
    fmt_messages = response_synthesis_prompt.format_messages(
        sql_query=sql,
        context_str=str(retrieved_rows),
        query_str=query,
    )
    chat_response = await llm.achat(fmt_messages)
    return chat_response.message.content

# {{/docs-fragment sql_and_response}}

# {{docs-fragment text_to_sql}}
@env.task
async def text_to_sql(
    system_prompt: str = (
        "Given an input question, first create a syntactically correct {dialect} "
        "query to run, then look at the results of the query and return the answer. "
        "You can order the results by a relevant column to return the most "
        "interesting examples in the database.\n\n"
        "Never query for all the columns from a specific table, only ask for a "
        "few relevant columns given the question.\n\n"
        "Pay attention to use only the column names that you can see in the schema "
        "description. "
        "Be careful to not query for columns that do not exist. "
        "Pay attention to which column is in which table. "
        "Also, qualify column names with the table name when needed. "
        "You are required to use the following format, each taking one line:\n\n"
        "Question: Question here\n"
        "SQLQuery: SQL Query to run\n"
        "SQLResult: Result of the SQLQuery\n"
        "Answer: Final answer here\n\n"
        "Only use tables listed below.\n"
        "{schema}\n\n"
        "Question: {query_str}\n"
        "SQLQuery: "
    ),
    query: str = "What was the year that The Notorious BIG was signed to Bad Boy?",
    model: str = "gpt-4o-mini",
) -> str:
    db_file, table_infos = await data_ingestion()
    vector_index_dir = await index_all_tables(db_file)
    table_context = await retrieve_tables(query, table_infos, db_file, vector_index_dir)
    sql = await generate_sql(query, table_context, model, system_prompt)
    return await generate_response(query, sql, db_file, model)

# {{/docs-fragment text_to_sql}}

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(text_to_sql)
    print(run.url)
    run.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/text_to_sql/text_to_sql.py*

Each row becomes a text node stored in LlamaIndex’s `VectorStoreIndex`. This lets the system pull semantically similar rows when handling queries.

### Table retrieval and context building

We then retrieve the most relevant tables for a given query and build rich context that combines schema information with sample rows.

CODE4").strip()

# {{docs-fragment sql_and_response}}
@env.task
async def generate_sql(query: str, table_context: str, model: str, prompt: str) -> str:
    """Generate SQL query from natural language question and table context."""
    llm = OpenAI(model=model)

    fmt_messages = (
        PromptTemplate(
            prompt,
            prompt_type=PromptType.TEXT_TO_SQL,
        )
        .partial_format(dialect="sqlite")
        .format_messages(query_str=query, schema=table_context)
    )

    chat_response = await llm.achat(fmt_messages)
    return parse_response_to_sql(chat_response)

@env.task
async def generate_response(query: str, sql: str, db_file: File, model: str) -> str:
    """Run SQL query on database and synthesize final response."""
    await db_file.download(local_path="local_db.sqlite")

    engine = create_engine("sqlite:///local_db.sqlite")
    sql_database = SQLDatabase(engine)
    sql_retriever = SQLRetriever(sql_database)

    retrieved_rows = sql_retriever.retrieve(sql)

    response_synthesis_prompt = PromptTemplate(
        "Given an input question, synthesize a response from the query results.\n"
        "Query: {query_str}\n"
        "SQL: {sql_query}\n"
        "SQL Response: {context_str}\n"
        "Response: "
    )

    llm = OpenAI(model=model)
    fmt_messages = response_synthesis_prompt.format_messages(
        sql_query=sql,
        context_str=str(retrieved_rows),
        query_str=query,
    )
    chat_response = await llm.achat(fmt_messages)
    return chat_response.message.content

# {{/docs-fragment sql_and_response}}

# {{docs-fragment text_to_sql}}
@env.task
async def text_to_sql(
    system_prompt: str = (
        "Given an input question, first create a syntactically correct {dialect} "
        "query to run, then look at the results of the query and return the answer. "
        "You can order the results by a relevant column to return the most "
        "interesting examples in the database.\n\n"
        "Never query for all the columns from a specific table, only ask for a "
        "few relevant columns given the question.\n\n"
        "Pay attention to use only the column names that you can see in the schema "
        "description. "
        "Be careful to not query for columns that do not exist. "
        "Pay attention to which column is in which table. "
        "Also, qualify column names with the table name when needed. "
        "You are required to use the following format, each taking one line:\n\n"
        "Question: Question here\n"
        "SQLQuery: SQL Query to run\n"
        "SQLResult: Result of the SQLQuery\n"
        "Answer: Final answer here\n\n"
        "Only use tables listed below.\n"
        "{schema}\n\n"
        "Question: {query_str}\n"
        "SQLQuery: "
    ),
    query: str = "What was the year that The Notorious BIG was signed to Bad Boy?",
    model: str = "gpt-4o-mini",
) -> str:
    db_file, table_infos = await data_ingestion()
    vector_index_dir = await index_all_tables(db_file)
    table_context = await retrieve_tables(query, table_infos, db_file, vector_index_dir)
    sql = await generate_sql(query, table_context, model, system_prompt)
    return await generate_response(query, sql, db_file, model)

# {{/docs-fragment text_to_sql}}

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(text_to_sql)
    print(run.url)
    run.wait()
CODE5
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "llama-index-core>=0.11.0",
#    "llama-index-llms-openai>=0.2.0",
#    "sqlalchemy>=2.0.0",
#    "pandas>=2.0.0",
#    "requests>=2.25.0",
#    "pydantic>=2.0.0",
# ]
# main = "text_to_sql"
# params = ""
# ///

import asyncio
from pathlib import Path

import flyte
from data_ingestion import TableInfo, data_ingestion
from flyte.io import Dir, File
from llama_index.core import (
    PromptTemplate,
    SQLDatabase,
    StorageContext,
    VectorStoreIndex,
    load_index_from_storage,
)
from llama_index.core.llms import ChatResponse
from llama_index.core.objects import ObjectIndex, SQLTableNodeMapping, SQLTableSchema
from llama_index.core.prompts.prompt_type import PromptType
from llama_index.core.retrievers import SQLRetriever
from llama_index.core.schema import TextNode
from llama_index.llms.openai import OpenAI
from sqlalchemy import create_engine, text
from utils import env

# {{docs-fragment index_tables}}
@flyte.trace
async def index_table(table_name: str, table_index_dir: str, database_uri: str) -> str:
    """Index a single table into vector store."""
    path = f"{table_index_dir}/{table_name}"
    engine = create_engine(database_uri)

    def _fetch_rows():
        with engine.connect() as conn:
            cursor = conn.execute(text(f'SELECT * FROM "{table_name}"'))
            return cursor.fetchall()

    result = await asyncio.to_thread(_fetch_rows)
    nodes = [TextNode(text=str(tuple(row))) for row in result]
    index = VectorStoreIndex(nodes)
    index.set_index_id("vector_index")
    index.storage_context.persist(path)

    return path

@env.task
async def index_all_tables(db_file: File) -> Dir:
    """Index all tables concurrently."""
    table_index_dir = "table_indices"
    Path(table_index_dir).mkdir(exist_ok=True)

    await db_file.download(local_path="local_db.sqlite")
    engine = create_engine("sqlite:///local_db.sqlite")
    sql_database = SQLDatabase(engine)

    tasks = [
        index_table(t, table_index_dir, "sqlite:///local_db.sqlite")
        for t in sql_database.get_usable_table_names()
    ]
    await asyncio.gather(*tasks)

    remote_dir = await Dir.from_local(table_index_dir)
    return remote_dir

# {{/docs-fragment index_tables}}

@flyte.trace
async def get_table_schema_context(
    table_schema_obj: SQLTableSchema,
    database_uri: str,
) -> str:
    """Retrieve schema + optional description context for a single table."""
    engine = create_engine(database_uri)
    sql_database = SQLDatabase(engine)

    table_info = sql_database.get_single_table_info(table_schema_obj.table_name)

    if table_schema_obj.context_str:
        table_info += f" The table description is: {table_schema_obj.context_str}"

    return table_info

@flyte.trace
async def get_table_row_context(
    table_schema_obj: SQLTableSchema,
    local_vector_index_dir: str,
    query: str,
) -> str:
    """Retrieve row-level context examples using vector search."""
    storage_context = StorageContext.from_defaults(
        persist_dir=str(f"{local_vector_index_dir}/{table_schema_obj.table_name}")
    )
    vector_index = load_index_from_storage(storage_context, index_id="vector_index")
    vector_retriever = vector_index.as_retriever(similarity_top_k=2)
    relevant_nodes = vector_retriever.retrieve(query)

    if not relevant_nodes:
        return ""

    row_context = "\nHere are some relevant example rows (values in the same order as columns above)\n"
    for node in relevant_nodes:
        row_context += str(node.get_content()) + "\n"

    return row_context

async def process_table(
    table_schema_obj: SQLTableSchema,
    database_uri: str,
    local_vector_index_dir: str,
    query: str,
) -> str:
    """Combine schema + row context for one table."""
    table_info = await get_table_schema_context(table_schema_obj, database_uri)
    row_context = await get_table_row_context(
        table_schema_obj, local_vector_index_dir, query
    )

    full_context = table_info
    if row_context:
        full_context += "\n" + row_context

    print(f"Table Info: {full_context}")
    return full_context

async def get_table_context_and_rows_str(
    query: str,
    database_uri: str,
    table_schema_objs: list[SQLTableSchema],
    vector_index_dir: Dir,
):
    """Get combined schema + row context for all tables."""
    local_vector_index_dir = await vector_index_dir.download()

    # run per-table work concurrently
    context_strs = await asyncio.gather(
        *[
            process_table(t, database_uri, local_vector_index_dir, query)
            for t in table_schema_objs
        ]
    )

    return "\n\n".join(context_strs)

# {{docs-fragment retrieve_tables}}
@env.task
async def retrieve_tables(
    query: str,
    table_infos: list[TableInfo | None],
    db_file: File,
    vector_index_dir: Dir,
) -> str:
    """Retrieve relevant tables and return schema context string."""
    await db_file.download(local_path="local_db.sqlite")
    engine = create_engine("sqlite:///local_db.sqlite")
    sql_database = SQLDatabase(engine)

    table_node_mapping = SQLTableNodeMapping(sql_database)
    table_schema_objs = [
        SQLTableSchema(table_name=t.table_name, context_str=t.table_summary)
        for t in table_infos
        if t is not None
    ]

    obj_index = ObjectIndex.from_objects(
        table_schema_objs,
        table_node_mapping,
        VectorStoreIndex,
    )
    obj_retriever = obj_index.as_retriever(similarity_top_k=3)

    retrieved_schemas = obj_retriever.retrieve(query)
    return await get_table_context_and_rows_str(
        query, "sqlite:///local_db.sqlite", retrieved_schemas, vector_index_dir
    )

# {{/docs-fragment retrieve_tables}}

def parse_response_to_sql(chat_response: ChatResponse) -> str:
    """Extract SQL query from LLM response."""
    response = chat_response.message.content
    sql_query_start = response.find("SQLQuery:")
    if sql_query_start != -1:
        response = response[sql_query_start:]
        if response.startswith("SQLQuery:"):
            response = response[len("SQLQuery:") :]
    sql_result_start = response.find("SQLResult:")
    if sql_result_start != -1:
        response = response[:sql_result_start]
    return response.strip().strip("CODE6

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/text_to_sql/text_to_sql.py*

The SQL generation prompt includes schema, example rows, and formatting rules. After execution, the system returns a final answer.

At this point, we have an end-to-end Text-to-SQL pipeline: natural language questions go in, SQL queries run, and answers come back. To make this workflow production-ready, we leveraged several Flyte 2 capabilities. Caching ensures that repeated steps, like table ingestion or vector indexing, don’t need to rerun unnecessarily, saving time and compute. Containerization provides consistent, reproducible execution across environments, making it easier to scale and deploy. Observability features let us track every step of the pipeline, monitor performance, and debug issues quickly.

While the pipeline works end-to-end, to get a pulse on how it performs across multiple prompts and to gradually improve performance, we can start experimenting with prompt tuning.

Two things help make this process meaningful:

- **A clean evaluation dataset** - so we can measure accuracy against trusted ground truth.
- **A systematic evaluation loop** - so we can see whether prompt changes or other adjustments actually help.

With these in place, the next step is to build a "golden" QA dataset that will guide iterative prompt optimization.

## Building the QA dataset

> [!NOTE]
> The WikiTableQuestions dataset already includes question–answer pairs, available in its [GitHub repository](https://github.com/ppasupat/WikiTableQuestions/tree/master/data). To use them for this workflow, you'll need to adapt the data into the required format, but the raw material is there for you to build on.

We generate a dataset of natural language questions paired with executable SQL queries. This dataset acts as the benchmark for prompt tuning and evaluation.

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "pandas>=2.0.0",
#    "llama-index-core>=0.11.0",
#    "llama-index-llms-openai>=0.2.0",
#    "pydantic>=2.0.0",
# ]
# main = "build_eval_dataset"
# params = ""
# ///

import sqlite3

import flyte
import pandas as pd
from data_ingestion import data_ingestion
from flyte.io import File
from llama_index.core import PromptTemplate
from llama_index.llms.openai import OpenAI
from utils import env
from pydantic import BaseModel

class QAItem(BaseModel):
    question: str
    sql: str

class QAList(BaseModel):
    items: list[QAItem]

# {{docs-fragment get_and_split_schema}}
@env.task
async def get_and_split_schema(db_file: File, tables_per_chunk: int) -> list[str]:
    """
    Download the SQLite DB, extract schema info (columns + sample rows),
    then split it into chunks with up to `tables_per_chunk` tables each.
    """
    await db_file.download(local_path="local_db.sqlite")
    conn = sqlite3.connect("local_db.sqlite")
    cursor = conn.cursor()

    tables = cursor.execute(
        "SELECT name FROM sqlite_master WHERE type='table';"
    ).fetchall()

    schema_blocks = []
    for table in tables:
        table_name = table[0]

        # columns
        cursor.execute(f"PRAGMA table_info({table_name});")
        columns = [col[1] for col in cursor.fetchall()]
        block = f"Table: {table_name}({', '.join(columns)})"

        # sample rows
        cursor.execute(f"SELECT * FROM {table_name} LIMIT 10;")
        rows = cursor.fetchall()
        if rows:
            block += "\nSample rows:\n"
            for row in rows:
                block += f"{row}\n"

        schema_blocks.append(block)

    conn.close()

    chunks = []
    current_chunk = []
    for block in schema_blocks:
        current_chunk.append(block)
        if len(current_chunk) >= tables_per_chunk:
            chunks.append("\n".join(current_chunk))
            current_chunk = []
    if current_chunk:
        chunks.append("\n".join(current_chunk))

    return chunks

# {{/docs-fragment get_and_split_schema}}

# {{docs-fragment generate_questions_and_sql}}
@flyte.trace
async def generate_questions_and_sql(
    schema: str, num_samples: int, batch_size: int
) -> QAList:
    llm = OpenAI(model="gpt-4.1")

    prompt_tmpl = PromptTemplate(
        """Prompt: You are helping build a Text-to-SQL dataset.

Here is the database schema:
{schema}

Generate {num} natural language questions a user might ask about this database.
For each question, also provide the correct SQL query.

Reasoning process (you must follow this internally):

- Given an input question, first create a syntactically correct {dialect} SQL query.
- Never use SELECT *; only include the relevant columns.
- Use only columns/tables from the schema. Qualify column names when ambiguous.
- You may order results by a meaningful column to make the query more useful.
- Be careful not to add unnecessary columns.
- Use filters, aggregations, joins, grouping, and subqueries when relevant.

Final Output:
Return only a JSON object with one field:

- "items": a list of {num} objects, each with:
    - "question": the natural language question
    - "sql": the corresponding SQL query
"""
    )

    all_items: list[QAItem] = []

    # batch generation
    for start in range(0, num_samples, batch_size):
        current_num = min(batch_size, num_samples - start)
        response = llm.structured_predict(
            QAList,
            prompt_tmpl,
            schema=schema,
            num=current_num,
        )
        all_items.extend(response.items)

    # deduplicate
    seen = set()
    unique_items: list[QAItem] = []
    for item in all_items:
        key = (item.question.strip().lower(), item.sql.strip().lower())
        if key not in seen:
            seen.add(key)
            unique_items.append(item)

    return QAList(items=unique_items[:num_samples])

# {{/docs-fragment generate_questions_and_sql}}

@flyte.trace
async def llm_validate_batch(pairs: list[dict[str, str]]) -> list[str]:
    """Validate a batch of question/sql/result dicts using one LLM call."""
    batch_prompt = """You are validating the correctness of SQL query results against the question.
For each example, answer only "True" (correct) or "False" (incorrect).
Output one answer per line, in the same order as the examples.
---
"""

    for i, pair in enumerate(pairs, start=1):
        batch_prompt += f"""
Example {i}:
Question:
{pair['question']}

SQL:
{pair['sql']}

Result:
{pair['rows']}
---
"""

    llm = OpenAI(model="gpt-4.1")
    resp = await llm.acomplete(batch_prompt)

    # Expect exactly one True/False per example
    results = [
        line.strip()
        for line in resp.text.splitlines()
        if line.strip() in ("True", "False")
    ]
    return results

# {{docs-fragment validate_sql}}
@env.task
async def validate_sql(
    db_file: File, question_sql_pairs: QAList, batch_size: int
) -> list[dict[str, str]]:
    await db_file.download(local_path="local_db.sqlite")
    conn = sqlite3.connect("local_db.sqlite")
    cursor = conn.cursor()

    qa_data = []
    batch = []

    for pair in question_sql_pairs.items:
        q, sql = pair.question, pair.sql
        try:
            cursor.execute(sql)
            rows = cursor.fetchall()
            batch.append({"question": q, "sql": sql, "rows": str(rows)})

            # process when batch is full
            if len(batch) == batch_size:
                results = await llm_validate_batch(batch)
                for pair, is_valid in zip(batch, results):
                    if is_valid == "True":
                        qa_data.append(
                            {
                                "input": pair["question"],
                                "sql": pair["sql"],
                                "target": pair["rows"],
                            }
                        )
                    else:
                        print(f"Filtered out incorrect result for: {pair['question']}")
                batch = []
        except Exception as e:
            print(f"Skipping invalid SQL: {sql} ({e})")

    # process leftover batch
    if batch:
        results = await llm_validate_batch(batch)
        for pair, is_valid in zip(batch, results):
            if is_valid == "True":
                qa_data.append(
                    {
                        "input": pair["question"],
                        "sql": pair["sql"],
                        "target": pair["rows"],
                    }
                )
            else:
                print(f"Filtered out incorrect result for: {pair['question']}")

    conn.close()
    return qa_data

# {{/docs-fragment validate_sql}}

@flyte.trace
async def save_to_csv(qa_data: list[dict]) -> File:
    df = pd.DataFrame(qa_data, columns=["input", "target", "sql"])

    csv_file = "qa_dataset.csv"
    df.to_csv(csv_file, index=False)

    return await File.from_local(csv_file)

# {{docs-fragment build_eval_dataset}}
@env.task
async def build_eval_dataset(
    num_samples: int = 300, batch_size: int = 30, tables_per_chunk: int = 3
) -> File:
    db_file, _ = await data_ingestion()
    schema_chunks = await get_and_split_schema(db_file, tables_per_chunk)

    per_chunk_samples = max(1, num_samples // len(schema_chunks))
    final_qa_data = []

    for chunk in schema_chunks:
        qa_list = await generate_questions_and_sql(
            schema=chunk,
            num_samples=per_chunk_samples,
            batch_size=batch_size,
        )
        qa_data = await validate_sql(db_file, qa_list, batch_size)
        final_qa_data.extend(qa_data)

    csv_file = await save_to_csv(final_qa_data)
    return csv_file

# {{/docs-fragment build_eval_dataset}}

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(build_eval_dataset)
    print(run.url)
    run.wait()
CODE7
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "pandas>=2.0.0",
#    "llama-index-core>=0.11.0",
#    "llama-index-llms-openai>=0.2.0",
#    "pydantic>=2.0.0",
# ]
# main = "build_eval_dataset"
# params = ""
# ///

import sqlite3

import flyte
import pandas as pd
from data_ingestion import data_ingestion
from flyte.io import File
from llama_index.core import PromptTemplate
from llama_index.llms.openai import OpenAI
from utils import env
from pydantic import BaseModel

class QAItem(BaseModel):
    question: str
    sql: str

class QAList(BaseModel):
    items: list[QAItem]

# {{docs-fragment get_and_split_schema}}
@env.task
async def get_and_split_schema(db_file: File, tables_per_chunk: int) -> list[str]:
    """
    Download the SQLite DB, extract schema info (columns + sample rows),
    then split it into chunks with up to `tables_per_chunk` tables each.
    """
    await db_file.download(local_path="local_db.sqlite")
    conn = sqlite3.connect("local_db.sqlite")
    cursor = conn.cursor()

    tables = cursor.execute(
        "SELECT name FROM sqlite_master WHERE type='table';"
    ).fetchall()

    schema_blocks = []
    for table in tables:
        table_name = table[0]

        # columns
        cursor.execute(f"PRAGMA table_info({table_name});")
        columns = [col[1] for col in cursor.fetchall()]
        block = f"Table: {table_name}({', '.join(columns)})"

        # sample rows
        cursor.execute(f"SELECT * FROM {table_name} LIMIT 10;")
        rows = cursor.fetchall()
        if rows:
            block += "\nSample rows:\n"
            for row in rows:
                block += f"{row}\n"

        schema_blocks.append(block)

    conn.close()

    chunks = []
    current_chunk = []
    for block in schema_blocks:
        current_chunk.append(block)
        if len(current_chunk) >= tables_per_chunk:
            chunks.append("\n".join(current_chunk))
            current_chunk = []
    if current_chunk:
        chunks.append("\n".join(current_chunk))

    return chunks

# {{/docs-fragment get_and_split_schema}}

# {{docs-fragment generate_questions_and_sql}}
@flyte.trace
async def generate_questions_and_sql(
    schema: str, num_samples: int, batch_size: int
) -> QAList:
    llm = OpenAI(model="gpt-4.1")

    prompt_tmpl = PromptTemplate(
        """Prompt: You are helping build a Text-to-SQL dataset.

Here is the database schema:
{schema}

Generate {num} natural language questions a user might ask about this database.
For each question, also provide the correct SQL query.

Reasoning process (you must follow this internally):

- Given an input question, first create a syntactically correct {dialect} SQL query.
- Never use SELECT *; only include the relevant columns.
- Use only columns/tables from the schema. Qualify column names when ambiguous.
- You may order results by a meaningful column to make the query more useful.
- Be careful not to add unnecessary columns.
- Use filters, aggregations, joins, grouping, and subqueries when relevant.

Final Output:
Return only a JSON object with one field:

- "items": a list of {num} objects, each with:
    - "question": the natural language question
    - "sql": the corresponding SQL query
"""
    )

    all_items: list[QAItem] = []

    # batch generation
    for start in range(0, num_samples, batch_size):
        current_num = min(batch_size, num_samples - start)
        response = llm.structured_predict(
            QAList,
            prompt_tmpl,
            schema=schema,
            num=current_num,
        )
        all_items.extend(response.items)

    # deduplicate
    seen = set()
    unique_items: list[QAItem] = []
    for item in all_items:
        key = (item.question.strip().lower(), item.sql.strip().lower())
        if key not in seen:
            seen.add(key)
            unique_items.append(item)

    return QAList(items=unique_items[:num_samples])

# {{/docs-fragment generate_questions_and_sql}}

@flyte.trace
async def llm_validate_batch(pairs: list[dict[str, str]]) -> list[str]:
    """Validate a batch of question/sql/result dicts using one LLM call."""
    batch_prompt = """You are validating the correctness of SQL query results against the question.
For each example, answer only "True" (correct) or "False" (incorrect).
Output one answer per line, in the same order as the examples.
---
"""

    for i, pair in enumerate(pairs, start=1):
        batch_prompt += f"""
Example {i}:
Question:
{pair['question']}

SQL:
{pair['sql']}

Result:
{pair['rows']}
---
"""

    llm = OpenAI(model="gpt-4.1")
    resp = await llm.acomplete(batch_prompt)

    # Expect exactly one True/False per example
    results = [
        line.strip()
        for line in resp.text.splitlines()
        if line.strip() in ("True", "False")
    ]
    return results

# {{docs-fragment validate_sql}}
@env.task
async def validate_sql(
    db_file: File, question_sql_pairs: QAList, batch_size: int
) -> list[dict[str, str]]:
    await db_file.download(local_path="local_db.sqlite")
    conn = sqlite3.connect("local_db.sqlite")
    cursor = conn.cursor()

    qa_data = []
    batch = []

    for pair in question_sql_pairs.items:
        q, sql = pair.question, pair.sql
        try:
            cursor.execute(sql)
            rows = cursor.fetchall()
            batch.append({"question": q, "sql": sql, "rows": str(rows)})

            # process when batch is full
            if len(batch) == batch_size:
                results = await llm_validate_batch(batch)
                for pair, is_valid in zip(batch, results):
                    if is_valid == "True":
                        qa_data.append(
                            {
                                "input": pair["question"],
                                "sql": pair["sql"],
                                "target": pair["rows"],
                            }
                        )
                    else:
                        print(f"Filtered out incorrect result for: {pair['question']}")
                batch = []
        except Exception as e:
            print(f"Skipping invalid SQL: {sql} ({e})")

    # process leftover batch
    if batch:
        results = await llm_validate_batch(batch)
        for pair, is_valid in zip(batch, results):
            if is_valid == "True":
                qa_data.append(
                    {
                        "input": pair["question"],
                        "sql": pair["sql"],
                        "target": pair["rows"],
                    }
                )
            else:
                print(f"Filtered out incorrect result for: {pair['question']}")

    conn.close()
    return qa_data

# {{/docs-fragment validate_sql}}

@flyte.trace
async def save_to_csv(qa_data: list[dict]) -> File:
    df = pd.DataFrame(qa_data, columns=["input", "target", "sql"])

    csv_file = "qa_dataset.csv"
    df.to_csv(csv_file, index=False)

    return await File.from_local(csv_file)

# {{docs-fragment build_eval_dataset}}
@env.task
async def build_eval_dataset(
    num_samples: int = 300, batch_size: int = 30, tables_per_chunk: int = 3
) -> File:
    db_file, _ = await data_ingestion()
    schema_chunks = await get_and_split_schema(db_file, tables_per_chunk)

    per_chunk_samples = max(1, num_samples // len(schema_chunks))
    final_qa_data = []

    for chunk in schema_chunks:
        qa_list = await generate_questions_and_sql(
            schema=chunk,
            num_samples=per_chunk_samples,
            batch_size=batch_size,
        )
        qa_data = await validate_sql(db_file, qa_list, batch_size)
        final_qa_data.extend(qa_data)

    csv_file = await save_to_csv(final_qa_data)
    return csv_file

# {{/docs-fragment build_eval_dataset}}

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(build_eval_dataset)
    print(run.url)
    run.wait()
CODE8
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "pandas>=2.0.0",
#    "llama-index-core>=0.11.0",
#    "llama-index-llms-openai>=0.2.0",
#    "pydantic>=2.0.0",
# ]
# main = "build_eval_dataset"
# params = ""
# ///

import sqlite3

import flyte
import pandas as pd
from data_ingestion import data_ingestion
from flyte.io import File
from llama_index.core import PromptTemplate
from llama_index.llms.openai import OpenAI
from utils import env
from pydantic import BaseModel

class QAItem(BaseModel):
    question: str
    sql: str

class QAList(BaseModel):
    items: list[QAItem]

# {{docs-fragment get_and_split_schema}}
@env.task
async def get_and_split_schema(db_file: File, tables_per_chunk: int) -> list[str]:
    """
    Download the SQLite DB, extract schema info (columns + sample rows),
    then split it into chunks with up to `tables_per_chunk` tables each.
    """
    await db_file.download(local_path="local_db.sqlite")
    conn = sqlite3.connect("local_db.sqlite")
    cursor = conn.cursor()

    tables = cursor.execute(
        "SELECT name FROM sqlite_master WHERE type='table';"
    ).fetchall()

    schema_blocks = []
    for table in tables:
        table_name = table[0]

        # columns
        cursor.execute(f"PRAGMA table_info({table_name});")
        columns = [col[1] for col in cursor.fetchall()]
        block = f"Table: {table_name}({', '.join(columns)})"

        # sample rows
        cursor.execute(f"SELECT * FROM {table_name} LIMIT 10;")
        rows = cursor.fetchall()
        if rows:
            block += "\nSample rows:\n"
            for row in rows:
                block += f"{row}\n"

        schema_blocks.append(block)

    conn.close()

    chunks = []
    current_chunk = []
    for block in schema_blocks:
        current_chunk.append(block)
        if len(current_chunk) >= tables_per_chunk:
            chunks.append("\n".join(current_chunk))
            current_chunk = []
    if current_chunk:
        chunks.append("\n".join(current_chunk))

    return chunks

# {{/docs-fragment get_and_split_schema}}

# {{docs-fragment generate_questions_and_sql}}
@flyte.trace
async def generate_questions_and_sql(
    schema: str, num_samples: int, batch_size: int
) -> QAList:
    llm = OpenAI(model="gpt-4.1")

    prompt_tmpl = PromptTemplate(
        """Prompt: You are helping build a Text-to-SQL dataset.

Here is the database schema:
{schema}

Generate {num} natural language questions a user might ask about this database.
For each question, also provide the correct SQL query.

Reasoning process (you must follow this internally):

- Given an input question, first create a syntactically correct {dialect} SQL query.
- Never use SELECT *; only include the relevant columns.
- Use only columns/tables from the schema. Qualify column names when ambiguous.
- You may order results by a meaningful column to make the query more useful.
- Be careful not to add unnecessary columns.
- Use filters, aggregations, joins, grouping, and subqueries when relevant.

Final Output:
Return only a JSON object with one field:

- "items": a list of {num} objects, each with:
    - "question": the natural language question
    - "sql": the corresponding SQL query
"""
    )

    all_items: list[QAItem] = []

    # batch generation
    for start in range(0, num_samples, batch_size):
        current_num = min(batch_size, num_samples - start)
        response = llm.structured_predict(
            QAList,
            prompt_tmpl,
            schema=schema,
            num=current_num,
        )
        all_items.extend(response.items)

    # deduplicate
    seen = set()
    unique_items: list[QAItem] = []
    for item in all_items:
        key = (item.question.strip().lower(), item.sql.strip().lower())
        if key not in seen:
            seen.add(key)
            unique_items.append(item)

    return QAList(items=unique_items[:num_samples])

# {{/docs-fragment generate_questions_and_sql}}

@flyte.trace
async def llm_validate_batch(pairs: list[dict[str, str]]) -> list[str]:
    """Validate a batch of question/sql/result dicts using one LLM call."""
    batch_prompt = """You are validating the correctness of SQL query results against the question.
For each example, answer only "True" (correct) or "False" (incorrect).
Output one answer per line, in the same order as the examples.
---
"""

    for i, pair in enumerate(pairs, start=1):
        batch_prompt += f"""
Example {i}:
Question:
{pair['question']}

SQL:
{pair['sql']}

Result:
{pair['rows']}
---
"""

    llm = OpenAI(model="gpt-4.1")
    resp = await llm.acomplete(batch_prompt)

    # Expect exactly one True/False per example
    results = [
        line.strip()
        for line in resp.text.splitlines()
        if line.strip() in ("True", "False")
    ]
    return results

# {{docs-fragment validate_sql}}
@env.task
async def validate_sql(
    db_file: File, question_sql_pairs: QAList, batch_size: int
) -> list[dict[str, str]]:
    await db_file.download(local_path="local_db.sqlite")
    conn = sqlite3.connect("local_db.sqlite")
    cursor = conn.cursor()

    qa_data = []
    batch = []

    for pair in question_sql_pairs.items:
        q, sql = pair.question, pair.sql
        try:
            cursor.execute(sql)
            rows = cursor.fetchall()
            batch.append({"question": q, "sql": sql, "rows": str(rows)})

            # process when batch is full
            if len(batch) == batch_size:
                results = await llm_validate_batch(batch)
                for pair, is_valid in zip(batch, results):
                    if is_valid == "True":
                        qa_data.append(
                            {
                                "input": pair["question"],
                                "sql": pair["sql"],
                                "target": pair["rows"],
                            }
                        )
                    else:
                        print(f"Filtered out incorrect result for: {pair['question']}")
                batch = []
        except Exception as e:
            print(f"Skipping invalid SQL: {sql} ({e})")

    # process leftover batch
    if batch:
        results = await llm_validate_batch(batch)
        for pair, is_valid in zip(batch, results):
            if is_valid == "True":
                qa_data.append(
                    {
                        "input": pair["question"],
                        "sql": pair["sql"],
                        "target": pair["rows"],
                    }
                )
            else:
                print(f"Filtered out incorrect result for: {pair['question']}")

    conn.close()
    return qa_data

# {{/docs-fragment validate_sql}}

@flyte.trace
async def save_to_csv(qa_data: list[dict]) -> File:
    df = pd.DataFrame(qa_data, columns=["input", "target", "sql"])

    csv_file = "qa_dataset.csv"
    df.to_csv(csv_file, index=False)

    return await File.from_local(csv_file)

# {{docs-fragment build_eval_dataset}}
@env.task
async def build_eval_dataset(
    num_samples: int = 300, batch_size: int = 30, tables_per_chunk: int = 3
) -> File:
    db_file, _ = await data_ingestion()
    schema_chunks = await get_and_split_schema(db_file, tables_per_chunk)

    per_chunk_samples = max(1, num_samples // len(schema_chunks))
    final_qa_data = []

    for chunk in schema_chunks:
        qa_list = await generate_questions_and_sql(
            schema=chunk,
            num_samples=per_chunk_samples,
            batch_size=batch_size,
        )
        qa_data = await validate_sql(db_file, qa_list, batch_size)
        final_qa_data.extend(qa_data)

    csv_file = await save_to_csv(final_qa_data)
    return csv_file

# {{/docs-fragment build_eval_dataset}}

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(build_eval_dataset)
    print(run.url)
    run.wait()
CODE9
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "pandas>=2.0.0",
#    "llama-index-core>=0.11.0",
#    "llama-index-llms-openai>=0.2.0",
#    "pydantic>=2.0.0",
# ]
# main = "build_eval_dataset"
# params = ""
# ///

import sqlite3

import flyte
import pandas as pd
from data_ingestion import data_ingestion
from flyte.io import File
from llama_index.core import PromptTemplate
from llama_index.llms.openai import OpenAI
from utils import env
from pydantic import BaseModel

class QAItem(BaseModel):
    question: str
    sql: str

class QAList(BaseModel):
    items: list[QAItem]

# {{docs-fragment get_and_split_schema}}
@env.task
async def get_and_split_schema(db_file: File, tables_per_chunk: int) -> list[str]:
    """
    Download the SQLite DB, extract schema info (columns + sample rows),
    then split it into chunks with up to `tables_per_chunk` tables each.
    """
    await db_file.download(local_path="local_db.sqlite")
    conn = sqlite3.connect("local_db.sqlite")
    cursor = conn.cursor()

    tables = cursor.execute(
        "SELECT name FROM sqlite_master WHERE type='table';"
    ).fetchall()

    schema_blocks = []
    for table in tables:
        table_name = table[0]

        # columns
        cursor.execute(f"PRAGMA table_info({table_name});")
        columns = [col[1] for col in cursor.fetchall()]
        block = f"Table: {table_name}({', '.join(columns)})"

        # sample rows
        cursor.execute(f"SELECT * FROM {table_name} LIMIT 10;")
        rows = cursor.fetchall()
        if rows:
            block += "\nSample rows:\n"
            for row in rows:
                block += f"{row}\n"

        schema_blocks.append(block)

    conn.close()

    chunks = []
    current_chunk = []
    for block in schema_blocks:
        current_chunk.append(block)
        if len(current_chunk) >= tables_per_chunk:
            chunks.append("\n".join(current_chunk))
            current_chunk = []
    if current_chunk:
        chunks.append("\n".join(current_chunk))

    return chunks

# {{/docs-fragment get_and_split_schema}}

# {{docs-fragment generate_questions_and_sql}}
@flyte.trace
async def generate_questions_and_sql(
    schema: str, num_samples: int, batch_size: int
) -> QAList:
    llm = OpenAI(model="gpt-4.1")

    prompt_tmpl = PromptTemplate(
        """Prompt: You are helping build a Text-to-SQL dataset.

Here is the database schema:
{schema}

Generate {num} natural language questions a user might ask about this database.
For each question, also provide the correct SQL query.

Reasoning process (you must follow this internally):

- Given an input question, first create a syntactically correct {dialect} SQL query.
- Never use SELECT *; only include the relevant columns.
- Use only columns/tables from the schema. Qualify column names when ambiguous.
- You may order results by a meaningful column to make the query more useful.
- Be careful not to add unnecessary columns.
- Use filters, aggregations, joins, grouping, and subqueries when relevant.

Final Output:
Return only a JSON object with one field:

- "items": a list of {num} objects, each with:
    - "question": the natural language question
    - "sql": the corresponding SQL query
"""
    )

    all_items: list[QAItem] = []

    # batch generation
    for start in range(0, num_samples, batch_size):
        current_num = min(batch_size, num_samples - start)
        response = llm.structured_predict(
            QAList,
            prompt_tmpl,
            schema=schema,
            num=current_num,
        )
        all_items.extend(response.items)

    # deduplicate
    seen = set()
    unique_items: list[QAItem] = []
    for item in all_items:
        key = (item.question.strip().lower(), item.sql.strip().lower())
        if key not in seen:
            seen.add(key)
            unique_items.append(item)

    return QAList(items=unique_items[:num_samples])

# {{/docs-fragment generate_questions_and_sql}}

@flyte.trace
async def llm_validate_batch(pairs: list[dict[str, str]]) -> list[str]:
    """Validate a batch of question/sql/result dicts using one LLM call."""
    batch_prompt = """You are validating the correctness of SQL query results against the question.
For each example, answer only "True" (correct) or "False" (incorrect).
Output one answer per line, in the same order as the examples.
---
"""

    for i, pair in enumerate(pairs, start=1):
        batch_prompt += f"""
Example {i}:
Question:
{pair['question']}

SQL:
{pair['sql']}

Result:
{pair['rows']}
---
"""

    llm = OpenAI(model="gpt-4.1")
    resp = await llm.acomplete(batch_prompt)

    # Expect exactly one True/False per example
    results = [
        line.strip()
        for line in resp.text.splitlines()
        if line.strip() in ("True", "False")
    ]
    return results

# {{docs-fragment validate_sql}}
@env.task
async def validate_sql(
    db_file: File, question_sql_pairs: QAList, batch_size: int
) -> list[dict[str, str]]:
    await db_file.download(local_path="local_db.sqlite")
    conn = sqlite3.connect("local_db.sqlite")
    cursor = conn.cursor()

    qa_data = []
    batch = []

    for pair in question_sql_pairs.items:
        q, sql = pair.question, pair.sql
        try:
            cursor.execute(sql)
            rows = cursor.fetchall()
            batch.append({"question": q, "sql": sql, "rows": str(rows)})

            # process when batch is full
            if len(batch) == batch_size:
                results = await llm_validate_batch(batch)
                for pair, is_valid in zip(batch, results):
                    if is_valid == "True":
                        qa_data.append(
                            {
                                "input": pair["question"],
                                "sql": pair["sql"],
                                "target": pair["rows"],
                            }
                        )
                    else:
                        print(f"Filtered out incorrect result for: {pair['question']}")
                batch = []
        except Exception as e:
            print(f"Skipping invalid SQL: {sql} ({e})")

    # process leftover batch
    if batch:
        results = await llm_validate_batch(batch)
        for pair, is_valid in zip(batch, results):
            if is_valid == "True":
                qa_data.append(
                    {
                        "input": pair["question"],
                        "sql": pair["sql"],
                        "target": pair["rows"],
                    }
                )
            else:
                print(f"Filtered out incorrect result for: {pair['question']}")

    conn.close()
    return qa_data

# {{/docs-fragment validate_sql}}

@flyte.trace
async def save_to_csv(qa_data: list[dict]) -> File:
    df = pd.DataFrame(qa_data, columns=["input", "target", "sql"])

    csv_file = "qa_dataset.csv"
    df.to_csv(csv_file, index=False)

    return await File.from_local(csv_file)

# {{docs-fragment build_eval_dataset}}
@env.task
async def build_eval_dataset(
    num_samples: int = 300, batch_size: int = 30, tables_per_chunk: int = 3
) -> File:
    db_file, _ = await data_ingestion()
    schema_chunks = await get_and_split_schema(db_file, tables_per_chunk)

    per_chunk_samples = max(1, num_samples // len(schema_chunks))
    final_qa_data = []

    for chunk in schema_chunks:
        qa_list = await generate_questions_and_sql(
            schema=chunk,
            num_samples=per_chunk_samples,
            batch_size=batch_size,
        )
        qa_data = await validate_sql(db_file, qa_list, batch_size)
        final_qa_data.extend(qa_data)

    csv_file = await save_to_csv(final_qa_data)
    return csv_file

# {{/docs-fragment build_eval_dataset}}

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(build_eval_dataset)
    print(run.url)
    run.wait()
CODE10
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "pandas>=2.0.0",
#    "sqlalchemy>=2.0.0",
#    "llama-index-core>=0.11.0",
#    "llama-index-llms-openai>=0.2.0",
# ]
# main = "auto_prompt_engineering"
# params = ""
# ///

import asyncio
import html
import os
import re
from dataclasses import dataclass
from typing import Optional, Union

import flyte
import flyte.report
import pandas as pd
from data_ingestion import TableInfo
from flyte.io import Dir, File
from llama_index.core import SQLDatabase
from llama_index.core.retrievers import SQLRetriever
from sqlalchemy import create_engine
from text_to_sql import data_ingestion, generate_sql, index_all_tables, retrieve_tables
from utils import env

CSS = """
<style>
    body {
        font-family: 'Segoe UI', Roboto, Arial, sans-serif;
    }
    .results-table {
        border-collapse: collapse;
        width: 100%;
        box-shadow: 0 2px 5px rgba(0,0,0,0.1);
        font-size: 14px;
    }
    .results-table th {
        background: linear-gradient(135deg, #4CAF50, #2E7D32);
        color: white;
        padding: 10px;
        text-align: left;
    }
    .results-table td {
        border: 1px solid #ddd;
        padding: 8px;
        vertical-align: top;
    }
    .results-table tr:nth-child(even) {background-color: #f9f9f9;}
    .results-table tr:hover {background-color: #f1f1f1;}
    .correct {color: #2E7D32; font-weight: bold;}
    .incorrect {color: #C62828; font-weight: bold;}
    .summary-card {
        background: #f9fbfd;
        padding: 14px 18px;
        border-radius: 8px;
        box-shadow: 0 1px 4px rgba(0,0,0,0.05);
        max-width: 800px;
        margin-top: 12px;
    }
    .summary-card h3 {
        margin-top: 0;
        color: #1e88e5;
        font-size: 16px;
    }
</style>
"""

@env.task
async def data_prep(csv_file: File | str) -> tuple[pd.DataFrame, pd.DataFrame]:
    """
    Load Q&A data from a public Google Sheet CSV export URL and split into val/test DataFrames.
    The sheet should have columns: 'input' and 'target'.
    """
    df = pd.read_csv(
        await csv_file.download() if isinstance(csv_file, File) else csv_file
    )

    if "input" not in df.columns or "target" not in df.columns:
        raise ValueError("Sheet must contain 'input' and 'target' columns.")

    # Shuffle rows
    df = df.sample(frac=1, random_state=1234).reset_index(drop=True)

    # Val/Test split
    df_renamed = df.rename(columns={"input": "question", "target": "answer"})

    n = len(df_renamed)
    split = n // 2

    df_val = df_renamed.iloc[:split]
    df_test = df_renamed.iloc[split:]

    return df_val, df_test

@dataclass
class ModelConfig:
    model_name: str
    hosted_model_uri: Optional[str] = None
    temperature: float = 0.0
    max_tokens: Optional[int] = 1000
    timeout: int = 600
    prompt: str = ""

@flyte.trace
async def call_model(
    model_config: ModelConfig,
    messages: list[dict[str, str]],
) -> str:
    from litellm import acompletion

    response = await acompletion(
        model=model_config.model_name,
        api_base=model_config.hosted_model_uri,
        messages=messages,
        temperature=model_config.temperature,
        timeout=model_config.timeout,
        max_tokens=model_config.max_tokens,
    )
    return response.choices[0].message["content"]

@flyte.trace
async def generate_response(db_file: File, sql: str) -> str:
    await db_file.download(local_path="local_db.sqlite")

    engine = create_engine("sqlite:///local_db.sqlite")
    sql_database = SQLDatabase(engine)
    sql_retriever = SQLRetriever(sql_database)

    retrieved_rows = sql_retriever.retrieve(sql)

    if retrieved_rows:
        # Get the structured result and stringify
        return str(retrieved_rows[0].node.metadata["result"])

    return ""

async def generate_and_review(
    index: int,
    question: str,
    answer: str,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    db_file: File,
    table_infos: list[TableInfo | None],
    vector_index_dir: Dir,
) -> dict:
    # Generate response from target model
    table_context = await retrieve_tables(
        question, table_infos, db_file, vector_index_dir
    )
    sql = await generate_sql(
        question,
        table_context,
        target_model_config.model_name,
        target_model_config.prompt,
    )
    sql = sql.replace("sql\n", "")

    try:
        response = await generate_response(db_file, sql)
    except Exception as e:
        print(f"Failed to generate response for question {question}: {e}")
        response = None

    # Format review prompt with response + answer
    review_messages = [
        {
            "role": "system",
            "content": review_model_config.prompt.format(
                query_str=question,
                response=response,
                answer=answer,
            ),
        }
    ]
    verdict = await call_model(review_model_config, review_messages)

    # Normalize verdict
    verdict_clean = verdict.strip().lower()
    if verdict_clean not in {"true", "false"}:
        verdict_clean = "not sure"

    return {
        "index": index,
        "model_response": response,
        "sql": sql,
        "is_correct": verdict_clean == "true",
    }

async def run_grouped_task(
    i,
    index,
    question,
    answer,
    sql,
    semaphore,
    target_model_config,
    review_model_config,
    counter,
    counter_lock,
    db_file,
    table_infos,
    vector_index_dir,
):
    async with semaphore:
        with flyte.group(name=f"row-{i}"):
            result = await generate_and_review(
                index,
                question,
                answer,
                target_model_config,
                review_model_config,
                db_file,
                table_infos,
                vector_index_dir,
            )

            async with counter_lock:
                # Update counters
                counter["processed"] += 1
                if result["is_correct"]:
                    counter["correct"] += 1
                    correct_html = "<span class='correct'>✔ Yes</span>"
                else:
                    correct_html = "<span class='incorrect'>✘ No</span>"

                # Calculate accuracy
                accuracy_pct = (counter["correct"] / counter["processed"]) * 100

            # Update chart
            await flyte.report.log.aio(
                f"<script>updateAccuracy({accuracy_pct});</script>",
                do_flush=True,
            )

            # Add row to table
            await flyte.report.log.aio(
                f"""
                <tr>
                    <td>{html.escape(question)}</td>
                    <td>{html.escape(answer)}</td>
                    <td>{html.escape(sql)}</td>
                    <td>{result['model_response']}</td>
                    <td>{result['sql']}</td>
                    <td>{correct_html}</td>
                </tr>
                """,
                do_flush=True,
            )

            return result

@dataclass
class DatabaseConfig:
    csv_zip_path: str
    search_glob: str
    concurrency: int
    model: str

# {{docs-fragment evaluate_prompt}}
@env.task(report=True)
async def evaluate_prompt(
    df: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    concurrency: int,
    db_config: DatabaseConfig,
) -> float:
    semaphore = asyncio.Semaphore(concurrency)
    counter = {"correct": 0, "processed": 0}
    counter_lock = asyncio.Lock()

    # Write initial HTML structure
    await flyte.report.log.aio(
        CSS
        + """
        <script>
            function updateAccuracy(percent) {
                const bar = document.getElementById('acc-bar');
                const label = document.getElementById('acc-label');
                bar.setAttribute('width', percent * 3);
                label.textContent = `Accuracy: ${percent.toFixed(1)}%`;
            }
        </script>

        <h2 style="margin-top:0;">Model Evaluation Results</h2>
        <h3>Live Accuracy</h3>
        <svg width="320" height="30" id="accuracy-chart">
            <defs>
                <linearGradient id="acc-gradient" x1="0" x2="1" y1="0" y2="0">
                    <stop offset="0%" stop-color="#66bb6a"/>
                    <stop offset="100%" stop-color="#2e7d32"/>
                </linearGradient>
            </defs>
            <rect width="300" height="20" fill="#ddd" rx="5" ry="5"></rect>
            <rect id="acc-bar" width="0" height="20" fill="url(#acc-gradient)" rx="5" ry="5"></rect>
            <text id="acc-label" x="150" y="15" font-size="12" font-weight="bold" text-anchor="middle" fill="#000">
                Accuracy: 0.0%
            </text>
        </svg>

        <table class="results-table">
            <thead>
                <tr>
                    <th>Question</th>
                    <th>Ground Truth Answer</th>
                    <th>Ground Truth SQL</th>
                    <th>Model Response</th>
                    <th>Model SQL</th>
                    <th>Correct?</th>
                </tr>
            </thead>
            <tbody>
        """,
        do_flush=True,
    )

    db_file, table_infos = await data_ingestion(
        db_config.csv_zip_path,
        db_config.search_glob,
        db_config.concurrency,
        db_config.model,
    )

    vector_index_dir = await index_all_tables(db_file)

    # Launch tasks concurrently
    tasks = [
        run_grouped_task(
            i,
            row.Index,
            row.question,
            row.answer,
            row.sql,
            semaphore,
            target_model_config,
            review_model_config,
            counter,
            counter_lock,
            db_file,
            table_infos,
            vector_index_dir,
        )
        for i, row in enumerate(df.itertuples(index=True))
    ]
    await asyncio.gather(*tasks)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    async with counter_lock:
        return (
            (counter["correct"] / counter["processed"]) if counter["processed"] else 0.0
        )

# {{/docs-fragment evaluate_prompt}}

@dataclass
class PromptResult:
    prompt: str
    accuracy: float

# {{docs-fragment prompt_optimizer}}
@env.task(report=True)
async def prompt_optimizer(
    df_val: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    optimizer_model_config: ModelConfig,
    max_iterations: int,
    concurrency: int,
    db_config: DatabaseConfig,
) -> tuple[str, float]:
    prompt_accuracies: list[PromptResult] = []

    # Send styling + table header immediately
    await flyte.report.log.aio(
        CSS
        + """
    <h2 style="margin-bottom:6px;">📊 Prompt Accuracy Comparison</h2>
    <table class="results-table">
        <thead>
            <tr>
                <th>Prompt</th>
                <th>Accuracy</th>
            </tr>
        </thead>
    <tbody>
    """,
        do_flush=True,
    )

    # Step 1: Evaluate starting prompt and stream row
    with flyte.group(name="baseline_evaluation"):
        starting_accuracy = await evaluate_prompt(
            df_val,
            target_model_config,
            review_model_config,
            concurrency,
            db_config,
        )
        prompt_accuracies.append(
            PromptResult(prompt=target_model_config.prompt, accuracy=starting_accuracy)
        )

        await _log_prompt_row(target_model_config.prompt, starting_accuracy)

    # Step 2: Optimize prompts one by one, streaming after each
    while len(prompt_accuracies) <= max_iterations:
        with flyte.group(name=f"prompt_optimization_step_{len(prompt_accuracies)}"):
            # Prepare prompt scores string for optimizer
            prompt_scores_str = "\n".join(
                f"{result.prompt}: {result.accuracy:.2f}"
                for result in sorted(prompt_accuracies, key=lambda x: x.accuracy)
            )

            optimizer_model_prompt = optimizer_model_config.prompt.format(
                prompt_scores_str=prompt_scores_str
            )
            response = await call_model(
                optimizer_model_config,
                [{"role": "system", "content": optimizer_model_prompt}],
            )
            response = response.strip()

            match = re.search(r"\[\[(.*?)\]\]", response, re.DOTALL)
            if not match:
                print("No new prompt found. Skipping.")
                continue

            new_prompt = match.group(1)
            target_model_config.prompt = new_prompt
            accuracy = await evaluate_prompt(
                df_val,
                target_model_config,
                review_model_config,
                concurrency,
                db_config,
            )
            prompt_accuracies.append(PromptResult(prompt=new_prompt, accuracy=accuracy))

            # Log this new prompt row immediately
            await _log_prompt_row(new_prompt, accuracy)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    # Find best
    best_result = max(prompt_accuracies, key=lambda x: x.accuracy)
    improvement = best_result.accuracy - starting_accuracy

    # Summary
    await flyte.report.log.aio(
        f"""
    <div class="summary-card">
        <h3>🏆 Summary</h3>
        <p><strong>Best Prompt:</strong> {html.escape(best_result.prompt)}</p>
        <p><strong>Best Accuracy:</strong> {best_result.accuracy*100:.2f}%</p>
        <p><strong>Improvement Over Baseline:</strong> {improvement*100:.2f}%</p>
    </div>
    """,
        do_flush=True,
    )

    return best_result.prompt, best_result.accuracy

# {{/docs-fragment prompt_optimizer}}

async def _log_prompt_row(prompt: str, accuracy: float):
    """Helper to log a single prompt/accuracy row to Flyte report."""
    pct = accuracy * 100
    if pct > 80:
        color = "linear-gradient(90deg, #4CAF50, #81C784)"
    elif pct > 60:
        color = "linear-gradient(90deg, #FFC107, #FFD54F)"
    else:
        color = "linear-gradient(90deg, #F44336, #E57373)"

    await flyte.report.log.aio(
        f"""
        <tr>
            <td>{html.escape(prompt)}</td>
            <td>
                {pct:.1f}%
                <div class="accuracy-bar-container">
                    <div class="accuracy-bar" style="width:{pct*1.6}px; background:{color};"></div>
                </div>
            </td>
        </tr>
        """,
        do_flush=True,
    )

# {{docs-fragment auto_prompt_engineering}}
@env.task
async def auto_prompt_engineering(
    ground_truth_csv: File | str = "/root/ground_truth.csv",
    db_config: DatabaseConfig = DatabaseConfig(
        csv_zip_path="https://github.com/ppasupat/WikiTableQuestions/releases/download/v1.0.2/WikiTableQuestions-1.0.2-compact.zip",
        search_glob="WikiTableQuestions/csv/200-csv/*.csv",
        concurrency=5,
        model="gpt-4o-mini",
    ),
    target_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="""Given an input question, create a syntactically correct {dialect} query to run.

Schema:
{schema}

Question: {query_str}

SQL query to run:
""",
        max_tokens=10000,
    ),
    review_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1",
        hosted_model_uri=None,
        prompt="""Your job is to determine whether the model's response is correct compared to the ground truth taking into account the context of the question.
Both answers were generated by running SQL queries on the same database.

- If the model's response contains all of the ground truth values, and any additional information is harmless (e.g., extra columns or metadata), output "True".
- If it adds incorrect or unrelated rows, or omits required values, output "False".

Question:
{query_str}

Ground Truth:
{answer}

Model Response:
{response}
""",
    ),
    optimizer_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1",
        hosted_model_uri=None,
        temperature=0.7,
        max_tokens=None,
        prompt="""
<EXPLANATION>
I have some prompts along with their corresponding accuracies.
The prompts are arranged in ascending order based on their accuracy, where higher accuracy indicates better quality.
</EXPLANATION>

<PROMPTS>
{prompt_scores_str}
</PROMPTS>

Each prompt was used to translate a natural-language question into a SQL query against a provided database schema.

<EXAMPLE>
<SCHEMA>
artists(id, name)
albums(id, title, artist_id, release_year)
</SCHEMA>
<QUESTION>
How many albums did The Beatles release?
</QUESTION>
<ANSWER>
SELECT COUNT(*) FROM albums a JOIN artists r ON a.artist_id = r.id WHERE r.name = 'The Beatles';
</ANSWER>
</EXAMPLE>

<TASK>
Write a new prompt that will achieve an accuracy as high as possible and that is different from the old ones.
</TASK>

<RULES>
- It is very important that the new prompt is distinct from ALL the old ones!
- Ensure that you analyse the prompts with a high accuracy and reuse the patterns that worked in the past.
- Ensure that you analyse the prompts with a low accuracy and avoid the patterns that didn't work in the past.
- Think out loud before creating the prompt. Describe what has worked in the past and what hasn't. Only then create the new prompt.
- Use all available information like prompt length, formal/informal use of language, etc. for your analysis.
- Be creative, try out different ways of prompting the model. You may even come up with hypothetical scenarios that might improve the accuracy.
- You are generating a system prompt. Always use three placeholders for each prompt: dialect, schema, query_str.
- Write your new prompt in double square brackets. Use only plain text for the prompt text and do not add any markdown (i.e. no hashtags, backticks, quotes, etc).
</RULES>
""",
    ),
    max_iterations: int = 5,
    concurrency: int = 10,
) -> dict[str, Union[str, float]]:
    if isinstance(ground_truth_csv, str) and os.path.isfile(ground_truth_csv):
        ground_truth_csv = await File.from_local(ground_truth_csv)

    df_val, df_test = await data_prep(ground_truth_csv)

    best_prompt, val_accuracy = await prompt_optimizer(
        df_val,
        target_model_config,
        review_model_config,
        optimizer_model_config,
        max_iterations,
        concurrency,
        db_config,
    )

    with flyte.group(name="test_data_evaluation"):
        baseline_test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
            db_config,
        )

        target_model_config.prompt = best_prompt
        test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
            db_config,
        )

    return {
        "best_prompt": best_prompt,
        "validation_accuracy": val_accuracy,
        "baseline_test_accuracy": baseline_test_accuracy,
        "test_accuracy": test_accuracy,
    }

# {{/docs-fragment auto_prompt_engineering}}

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(auto_prompt_engineering)
    print(run.url)
    run.wait()
CODE11
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "pandas>=2.0.0",
#    "sqlalchemy>=2.0.0",
#    "llama-index-core>=0.11.0",
#    "llama-index-llms-openai>=0.2.0",
# ]
# main = "auto_prompt_engineering"
# params = ""
# ///

import asyncio
import html
import os
import re
from dataclasses import dataclass
from typing import Optional, Union

import flyte
import flyte.report
import pandas as pd
from data_ingestion import TableInfo
from flyte.io import Dir, File
from llama_index.core import SQLDatabase
from llama_index.core.retrievers import SQLRetriever
from sqlalchemy import create_engine
from text_to_sql import data_ingestion, generate_sql, index_all_tables, retrieve_tables
from utils import env

CSS = """
<style>
    body {
        font-family: 'Segoe UI', Roboto, Arial, sans-serif;
    }
    .results-table {
        border-collapse: collapse;
        width: 100%;
        box-shadow: 0 2px 5px rgba(0,0,0,0.1);
        font-size: 14px;
    }
    .results-table th {
        background: linear-gradient(135deg, #4CAF50, #2E7D32);
        color: white;
        padding: 10px;
        text-align: left;
    }
    .results-table td {
        border: 1px solid #ddd;
        padding: 8px;
        vertical-align: top;
    }
    .results-table tr:nth-child(even) {background-color: #f9f9f9;}
    .results-table tr:hover {background-color: #f1f1f1;}
    .correct {color: #2E7D32; font-weight: bold;}
    .incorrect {color: #C62828; font-weight: bold;}
    .summary-card {
        background: #f9fbfd;
        padding: 14px 18px;
        border-radius: 8px;
        box-shadow: 0 1px 4px rgba(0,0,0,0.05);
        max-width: 800px;
        margin-top: 12px;
    }
    .summary-card h3 {
        margin-top: 0;
        color: #1e88e5;
        font-size: 16px;
    }
</style>
"""

@env.task
async def data_prep(csv_file: File | str) -> tuple[pd.DataFrame, pd.DataFrame]:
    """
    Load Q&A data from a public Google Sheet CSV export URL and split into val/test DataFrames.
    The sheet should have columns: 'input' and 'target'.
    """
    df = pd.read_csv(
        await csv_file.download() if isinstance(csv_file, File) else csv_file
    )

    if "input" not in df.columns or "target" not in df.columns:
        raise ValueError("Sheet must contain 'input' and 'target' columns.")

    # Shuffle rows
    df = df.sample(frac=1, random_state=1234).reset_index(drop=True)

    # Val/Test split
    df_renamed = df.rename(columns={"input": "question", "target": "answer"})

    n = len(df_renamed)
    split = n // 2

    df_val = df_renamed.iloc[:split]
    df_test = df_renamed.iloc[split:]

    return df_val, df_test

@dataclass
class ModelConfig:
    model_name: str
    hosted_model_uri: Optional[str] = None
    temperature: float = 0.0
    max_tokens: Optional[int] = 1000
    timeout: int = 600
    prompt: str = ""

@flyte.trace
async def call_model(
    model_config: ModelConfig,
    messages: list[dict[str, str]],
) -> str:
    from litellm import acompletion

    response = await acompletion(
        model=model_config.model_name,
        api_base=model_config.hosted_model_uri,
        messages=messages,
        temperature=model_config.temperature,
        timeout=model_config.timeout,
        max_tokens=model_config.max_tokens,
    )
    return response.choices[0].message["content"]

@flyte.trace
async def generate_response(db_file: File, sql: str) -> str:
    await db_file.download(local_path="local_db.sqlite")

    engine = create_engine("sqlite:///local_db.sqlite")
    sql_database = SQLDatabase(engine)
    sql_retriever = SQLRetriever(sql_database)

    retrieved_rows = sql_retriever.retrieve(sql)

    if retrieved_rows:
        # Get the structured result and stringify
        return str(retrieved_rows[0].node.metadata["result"])

    return ""

async def generate_and_review(
    index: int,
    question: str,
    answer: str,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    db_file: File,
    table_infos: list[TableInfo | None],
    vector_index_dir: Dir,
) -> dict:
    # Generate response from target model
    table_context = await retrieve_tables(
        question, table_infos, db_file, vector_index_dir
    )
    sql = await generate_sql(
        question,
        table_context,
        target_model_config.model_name,
        target_model_config.prompt,
    )
    sql = sql.replace("sql\n", "")

    try:
        response = await generate_response(db_file, sql)
    except Exception as e:
        print(f"Failed to generate response for question {question}: {e}")
        response = None

    # Format review prompt with response + answer
    review_messages = [
        {
            "role": "system",
            "content": review_model_config.prompt.format(
                query_str=question,
                response=response,
                answer=answer,
            ),
        }
    ]
    verdict = await call_model(review_model_config, review_messages)

    # Normalize verdict
    verdict_clean = verdict.strip().lower()
    if verdict_clean not in {"true", "false"}:
        verdict_clean = "not sure"

    return {
        "index": index,
        "model_response": response,
        "sql": sql,
        "is_correct": verdict_clean == "true",
    }

async def run_grouped_task(
    i,
    index,
    question,
    answer,
    sql,
    semaphore,
    target_model_config,
    review_model_config,
    counter,
    counter_lock,
    db_file,
    table_infos,
    vector_index_dir,
):
    async with semaphore:
        with flyte.group(name=f"row-{i}"):
            result = await generate_and_review(
                index,
                question,
                answer,
                target_model_config,
                review_model_config,
                db_file,
                table_infos,
                vector_index_dir,
            )

            async with counter_lock:
                # Update counters
                counter["processed"] += 1
                if result["is_correct"]:
                    counter["correct"] += 1
                    correct_html = "<span class='correct'>✔ Yes</span>"
                else:
                    correct_html = "<span class='incorrect'>✘ No</span>"

                # Calculate accuracy
                accuracy_pct = (counter["correct"] / counter["processed"]) * 100

            # Update chart
            await flyte.report.log.aio(
                f"<script>updateAccuracy({accuracy_pct});</script>",
                do_flush=True,
            )

            # Add row to table
            await flyte.report.log.aio(
                f"""
                <tr>
                    <td>{html.escape(question)}</td>
                    <td>{html.escape(answer)}</td>
                    <td>{html.escape(sql)}</td>
                    <td>{result['model_response']}</td>
                    <td>{result['sql']}</td>
                    <td>{correct_html}</td>
                </tr>
                """,
                do_flush=True,
            )

            return result

@dataclass
class DatabaseConfig:
    csv_zip_path: str
    search_glob: str
    concurrency: int
    model: str

# {{docs-fragment evaluate_prompt}}
@env.task(report=True)
async def evaluate_prompt(
    df: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    concurrency: int,
    db_config: DatabaseConfig,
) -> float:
    semaphore = asyncio.Semaphore(concurrency)
    counter = {"correct": 0, "processed": 0}
    counter_lock = asyncio.Lock()

    # Write initial HTML structure
    await flyte.report.log.aio(
        CSS
        + """
        <script>
            function updateAccuracy(percent) {
                const bar = document.getElementById('acc-bar');
                const label = document.getElementById('acc-label');
                bar.setAttribute('width', percent * 3);
                label.textContent = `Accuracy: ${percent.toFixed(1)}%`;
            }
        </script>

        <h2 style="margin-top:0;">Model Evaluation Results</h2>
        <h3>Live Accuracy</h3>
        <svg width="320" height="30" id="accuracy-chart">
            <defs>
                <linearGradient id="acc-gradient" x1="0" x2="1" y1="0" y2="0">
                    <stop offset="0%" stop-color="#66bb6a"/>
                    <stop offset="100%" stop-color="#2e7d32"/>
                </linearGradient>
            </defs>
            <rect width="300" height="20" fill="#ddd" rx="5" ry="5"></rect>
            <rect id="acc-bar" width="0" height="20" fill="url(#acc-gradient)" rx="5" ry="5"></rect>
            <text id="acc-label" x="150" y="15" font-size="12" font-weight="bold" text-anchor="middle" fill="#000">
                Accuracy: 0.0%
            </text>
        </svg>

        <table class="results-table">
            <thead>
                <tr>
                    <th>Question</th>
                    <th>Ground Truth Answer</th>
                    <th>Ground Truth SQL</th>
                    <th>Model Response</th>
                    <th>Model SQL</th>
                    <th>Correct?</th>
                </tr>
            </thead>
            <tbody>
        """,
        do_flush=True,
    )

    db_file, table_infos = await data_ingestion(
        db_config.csv_zip_path,
        db_config.search_glob,
        db_config.concurrency,
        db_config.model,
    )

    vector_index_dir = await index_all_tables(db_file)

    # Launch tasks concurrently
    tasks = [
        run_grouped_task(
            i,
            row.Index,
            row.question,
            row.answer,
            row.sql,
            semaphore,
            target_model_config,
            review_model_config,
            counter,
            counter_lock,
            db_file,
            table_infos,
            vector_index_dir,
        )
        for i, row in enumerate(df.itertuples(index=True))
    ]
    await asyncio.gather(*tasks)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    async with counter_lock:
        return (
            (counter["correct"] / counter["processed"]) if counter["processed"] else 0.0
        )

# {{/docs-fragment evaluate_prompt}}

@dataclass
class PromptResult:
    prompt: str
    accuracy: float

# {{docs-fragment prompt_optimizer}}
@env.task(report=True)
async def prompt_optimizer(
    df_val: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    optimizer_model_config: ModelConfig,
    max_iterations: int,
    concurrency: int,
    db_config: DatabaseConfig,
) -> tuple[str, float]:
    prompt_accuracies: list[PromptResult] = []

    # Send styling + table header immediately
    await flyte.report.log.aio(
        CSS
        + """
    <h2 style="margin-bottom:6px;">📊 Prompt Accuracy Comparison</h2>
    <table class="results-table">
        <thead>
            <tr>
                <th>Prompt</th>
                <th>Accuracy</th>
            </tr>
        </thead>
    <tbody>
    """,
        do_flush=True,
    )

    # Step 1: Evaluate starting prompt and stream row
    with flyte.group(name="baseline_evaluation"):
        starting_accuracy = await evaluate_prompt(
            df_val,
            target_model_config,
            review_model_config,
            concurrency,
            db_config,
        )
        prompt_accuracies.append(
            PromptResult(prompt=target_model_config.prompt, accuracy=starting_accuracy)
        )

        await _log_prompt_row(target_model_config.prompt, starting_accuracy)

    # Step 2: Optimize prompts one by one, streaming after each
    while len(prompt_accuracies) <= max_iterations:
        with flyte.group(name=f"prompt_optimization_step_{len(prompt_accuracies)}"):
            # Prepare prompt scores string for optimizer
            prompt_scores_str = "\n".join(
                f"{result.prompt}: {result.accuracy:.2f}"
                for result in sorted(prompt_accuracies, key=lambda x: x.accuracy)
            )

            optimizer_model_prompt = optimizer_model_config.prompt.format(
                prompt_scores_str=prompt_scores_str
            )
            response = await call_model(
                optimizer_model_config,
                [{"role": "system", "content": optimizer_model_prompt}],
            )
            response = response.strip()

            match = re.search(r"\[\[(.*?)\]\]", response, re.DOTALL)
            if not match:
                print("No new prompt found. Skipping.")
                continue

            new_prompt = match.group(1)
            target_model_config.prompt = new_prompt
            accuracy = await evaluate_prompt(
                df_val,
                target_model_config,
                review_model_config,
                concurrency,
                db_config,
            )
            prompt_accuracies.append(PromptResult(prompt=new_prompt, accuracy=accuracy))

            # Log this new prompt row immediately
            await _log_prompt_row(new_prompt, accuracy)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    # Find best
    best_result = max(prompt_accuracies, key=lambda x: x.accuracy)
    improvement = best_result.accuracy - starting_accuracy

    # Summary
    await flyte.report.log.aio(
        f"""
    <div class="summary-card">
        <h3>🏆 Summary</h3>
        <p><strong>Best Prompt:</strong> {html.escape(best_result.prompt)}</p>
        <p><strong>Best Accuracy:</strong> {best_result.accuracy*100:.2f}%</p>
        <p><strong>Improvement Over Baseline:</strong> {improvement*100:.2f}%</p>
    </div>
    """,
        do_flush=True,
    )

    return best_result.prompt, best_result.accuracy

# {{/docs-fragment prompt_optimizer}}

async def _log_prompt_row(prompt: str, accuracy: float):
    """Helper to log a single prompt/accuracy row to Flyte report."""
    pct = accuracy * 100
    if pct > 80:
        color = "linear-gradient(90deg, #4CAF50, #81C784)"
    elif pct > 60:
        color = "linear-gradient(90deg, #FFC107, #FFD54F)"
    else:
        color = "linear-gradient(90deg, #F44336, #E57373)"

    await flyte.report.log.aio(
        f"""
        <tr>
            <td>{html.escape(prompt)}</td>
            <td>
                {pct:.1f}%
                <div class="accuracy-bar-container">
                    <div class="accuracy-bar" style="width:{pct*1.6}px; background:{color};"></div>
                </div>
            </td>
        </tr>
        """,
        do_flush=True,
    )

# {{docs-fragment auto_prompt_engineering}}
@env.task
async def auto_prompt_engineering(
    ground_truth_csv: File | str = "/root/ground_truth.csv",
    db_config: DatabaseConfig = DatabaseConfig(
        csv_zip_path="https://github.com/ppasupat/WikiTableQuestions/releases/download/v1.0.2/WikiTableQuestions-1.0.2-compact.zip",
        search_glob="WikiTableQuestions/csv/200-csv/*.csv",
        concurrency=5,
        model="gpt-4o-mini",
    ),
    target_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="""Given an input question, create a syntactically correct {dialect} query to run.

Schema:
{schema}

Question: {query_str}

SQL query to run:
""",
        max_tokens=10000,
    ),
    review_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1",
        hosted_model_uri=None,
        prompt="""Your job is to determine whether the model's response is correct compared to the ground truth taking into account the context of the question.
Both answers were generated by running SQL queries on the same database.

- If the model's response contains all of the ground truth values, and any additional information is harmless (e.g., extra columns or metadata), output "True".
- If it adds incorrect or unrelated rows, or omits required values, output "False".

Question:
{query_str}

Ground Truth:
{answer}

Model Response:
{response}
""",
    ),
    optimizer_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1",
        hosted_model_uri=None,
        temperature=0.7,
        max_tokens=None,
        prompt="""
<EXPLANATION>
I have some prompts along with their corresponding accuracies.
The prompts are arranged in ascending order based on their accuracy, where higher accuracy indicates better quality.
</EXPLANATION>

<PROMPTS>
{prompt_scores_str}
</PROMPTS>

Each prompt was used to translate a natural-language question into a SQL query against a provided database schema.

<EXAMPLE>
<SCHEMA>
artists(id, name)
albums(id, title, artist_id, release_year)
</SCHEMA>
<QUESTION>
How many albums did The Beatles release?
</QUESTION>
<ANSWER>
SELECT COUNT(*) FROM albums a JOIN artists r ON a.artist_id = r.id WHERE r.name = 'The Beatles';
</ANSWER>
</EXAMPLE>

<TASK>
Write a new prompt that will achieve an accuracy as high as possible and that is different from the old ones.
</TASK>

<RULES>
- It is very important that the new prompt is distinct from ALL the old ones!
- Ensure that you analyse the prompts with a high accuracy and reuse the patterns that worked in the past.
- Ensure that you analyse the prompts with a low accuracy and avoid the patterns that didn't work in the past.
- Think out loud before creating the prompt. Describe what has worked in the past and what hasn't. Only then create the new prompt.
- Use all available information like prompt length, formal/informal use of language, etc. for your analysis.
- Be creative, try out different ways of prompting the model. You may even come up with hypothetical scenarios that might improve the accuracy.
- You are generating a system prompt. Always use three placeholders for each prompt: dialect, schema, query_str.
- Write your new prompt in double square brackets. Use only plain text for the prompt text and do not add any markdown (i.e. no hashtags, backticks, quotes, etc).
</RULES>
""",
    ),
    max_iterations: int = 5,
    concurrency: int = 10,
) -> dict[str, Union[str, float]]:
    if isinstance(ground_truth_csv, str) and os.path.isfile(ground_truth_csv):
        ground_truth_csv = await File.from_local(ground_truth_csv)

    df_val, df_test = await data_prep(ground_truth_csv)

    best_prompt, val_accuracy = await prompt_optimizer(
        df_val,
        target_model_config,
        review_model_config,
        optimizer_model_config,
        max_iterations,
        concurrency,
        db_config,
    )

    with flyte.group(name="test_data_evaluation"):
        baseline_test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
            db_config,
        )

        target_model_config.prompt = best_prompt
        test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
            db_config,
        )

    return {
        "best_prompt": best_prompt,
        "validation_accuracy": val_accuracy,
        "baseline_test_accuracy": baseline_test_accuracy,
        "test_accuracy": test_accuracy,
    }

# {{/docs-fragment auto_prompt_engineering}}

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(auto_prompt_engineering)
    print(run.url)
    run.wait()
CODE12
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "pandas>=2.0.0",
#    "sqlalchemy>=2.0.0",
#    "llama-index-core>=0.11.0",
#    "llama-index-llms-openai>=0.2.0",
# ]
# main = "auto_prompt_engineering"
# params = ""
# ///

import asyncio
import html
import os
import re
from dataclasses import dataclass
from typing import Optional, Union

import flyte
import flyte.report
import pandas as pd
from data_ingestion import TableInfo
from flyte.io import Dir, File
from llama_index.core import SQLDatabase
from llama_index.core.retrievers import SQLRetriever
from sqlalchemy import create_engine
from text_to_sql import data_ingestion, generate_sql, index_all_tables, retrieve_tables
from utils import env

CSS = """
<style>
    body {
        font-family: 'Segoe UI', Roboto, Arial, sans-serif;
    }
    .results-table {
        border-collapse: collapse;
        width: 100%;
        box-shadow: 0 2px 5px rgba(0,0,0,0.1);
        font-size: 14px;
    }
    .results-table th {
        background: linear-gradient(135deg, #4CAF50, #2E7D32);
        color: white;
        padding: 10px;
        text-align: left;
    }
    .results-table td {
        border: 1px solid #ddd;
        padding: 8px;
        vertical-align: top;
    }
    .results-table tr:nth-child(even) {background-color: #f9f9f9;}
    .results-table tr:hover {background-color: #f1f1f1;}
    .correct {color: #2E7D32; font-weight: bold;}
    .incorrect {color: #C62828; font-weight: bold;}
    .summary-card {
        background: #f9fbfd;
        padding: 14px 18px;
        border-radius: 8px;
        box-shadow: 0 1px 4px rgba(0,0,0,0.05);
        max-width: 800px;
        margin-top: 12px;
    }
    .summary-card h3 {
        margin-top: 0;
        color: #1e88e5;
        font-size: 16px;
    }
</style>
"""

@env.task
async def data_prep(csv_file: File | str) -> tuple[pd.DataFrame, pd.DataFrame]:
    """
    Load Q&A data from a public Google Sheet CSV export URL and split into val/test DataFrames.
    The sheet should have columns: 'input' and 'target'.
    """
    df = pd.read_csv(
        await csv_file.download() if isinstance(csv_file, File) else csv_file
    )

    if "input" not in df.columns or "target" not in df.columns:
        raise ValueError("Sheet must contain 'input' and 'target' columns.")

    # Shuffle rows
    df = df.sample(frac=1, random_state=1234).reset_index(drop=True)

    # Val/Test split
    df_renamed = df.rename(columns={"input": "question", "target": "answer"})

    n = len(df_renamed)
    split = n // 2

    df_val = df_renamed.iloc[:split]
    df_test = df_renamed.iloc[split:]

    return df_val, df_test

@dataclass
class ModelConfig:
    model_name: str
    hosted_model_uri: Optional[str] = None
    temperature: float = 0.0
    max_tokens: Optional[int] = 1000
    timeout: int = 600
    prompt: str = ""

@flyte.trace
async def call_model(
    model_config: ModelConfig,
    messages: list[dict[str, str]],
) -> str:
    from litellm import acompletion

    response = await acompletion(
        model=model_config.model_name,
        api_base=model_config.hosted_model_uri,
        messages=messages,
        temperature=model_config.temperature,
        timeout=model_config.timeout,
        max_tokens=model_config.max_tokens,
    )
    return response.choices[0].message["content"]

@flyte.trace
async def generate_response(db_file: File, sql: str) -> str:
    await db_file.download(local_path="local_db.sqlite")

    engine = create_engine("sqlite:///local_db.sqlite")
    sql_database = SQLDatabase(engine)
    sql_retriever = SQLRetriever(sql_database)

    retrieved_rows = sql_retriever.retrieve(sql)

    if retrieved_rows:
        # Get the structured result and stringify
        return str(retrieved_rows[0].node.metadata["result"])

    return ""

async def generate_and_review(
    index: int,
    question: str,
    answer: str,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    db_file: File,
    table_infos: list[TableInfo | None],
    vector_index_dir: Dir,
) -> dict:
    # Generate response from target model
    table_context = await retrieve_tables(
        question, table_infos, db_file, vector_index_dir
    )
    sql = await generate_sql(
        question,
        table_context,
        target_model_config.model_name,
        target_model_config.prompt,
    )
    sql = sql.replace("sql\n", "")

    try:
        response = await generate_response(db_file, sql)
    except Exception as e:
        print(f"Failed to generate response for question {question}: {e}")
        response = None

    # Format review prompt with response + answer
    review_messages = [
        {
            "role": "system",
            "content": review_model_config.prompt.format(
                query_str=question,
                response=response,
                answer=answer,
            ),
        }
    ]
    verdict = await call_model(review_model_config, review_messages)

    # Normalize verdict
    verdict_clean = verdict.strip().lower()
    if verdict_clean not in {"true", "false"}:
        verdict_clean = "not sure"

    return {
        "index": index,
        "model_response": response,
        "sql": sql,
        "is_correct": verdict_clean == "true",
    }

async def run_grouped_task(
    i,
    index,
    question,
    answer,
    sql,
    semaphore,
    target_model_config,
    review_model_config,
    counter,
    counter_lock,
    db_file,
    table_infos,
    vector_index_dir,
):
    async with semaphore:
        with flyte.group(name=f"row-{i}"):
            result = await generate_and_review(
                index,
                question,
                answer,
                target_model_config,
                review_model_config,
                db_file,
                table_infos,
                vector_index_dir,
            )

            async with counter_lock:
                # Update counters
                counter["processed"] += 1
                if result["is_correct"]:
                    counter["correct"] += 1
                    correct_html = "<span class='correct'>✔ Yes</span>"
                else:
                    correct_html = "<span class='incorrect'>✘ No</span>"

                # Calculate accuracy
                accuracy_pct = (counter["correct"] / counter["processed"]) * 100

            # Update chart
            await flyte.report.log.aio(
                f"<script>updateAccuracy({accuracy_pct});</script>",
                do_flush=True,
            )

            # Add row to table
            await flyte.report.log.aio(
                f"""
                <tr>
                    <td>{html.escape(question)}</td>
                    <td>{html.escape(answer)}</td>
                    <td>{html.escape(sql)}</td>
                    <td>{result['model_response']}</td>
                    <td>{result['sql']}</td>
                    <td>{correct_html}</td>
                </tr>
                """,
                do_flush=True,
            )

            return result

@dataclass
class DatabaseConfig:
    csv_zip_path: str
    search_glob: str
    concurrency: int
    model: str

# {{docs-fragment evaluate_prompt}}
@env.task(report=True)
async def evaluate_prompt(
    df: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    concurrency: int,
    db_config: DatabaseConfig,
) -> float:
    semaphore = asyncio.Semaphore(concurrency)
    counter = {"correct": 0, "processed": 0}
    counter_lock = asyncio.Lock()

    # Write initial HTML structure
    await flyte.report.log.aio(
        CSS
        + """
        <script>
            function updateAccuracy(percent) {
                const bar = document.getElementById('acc-bar');
                const label = document.getElementById('acc-label');
                bar.setAttribute('width', percent * 3);
                label.textContent = `Accuracy: ${percent.toFixed(1)}%`;
            }
        </script>

        <h2 style="margin-top:0;">Model Evaluation Results</h2>
        <h3>Live Accuracy</h3>
        <svg width="320" height="30" id="accuracy-chart">
            <defs>
                <linearGradient id="acc-gradient" x1="0" x2="1" y1="0" y2="0">
                    <stop offset="0%" stop-color="#66bb6a"/>
                    <stop offset="100%" stop-color="#2e7d32"/>
                </linearGradient>
            </defs>
            <rect width="300" height="20" fill="#ddd" rx="5" ry="5"></rect>
            <rect id="acc-bar" width="0" height="20" fill="url(#acc-gradient)" rx="5" ry="5"></rect>
            <text id="acc-label" x="150" y="15" font-size="12" font-weight="bold" text-anchor="middle" fill="#000">
                Accuracy: 0.0%
            </text>
        </svg>

        <table class="results-table">
            <thead>
                <tr>
                    <th>Question</th>
                    <th>Ground Truth Answer</th>
                    <th>Ground Truth SQL</th>
                    <th>Model Response</th>
                    <th>Model SQL</th>
                    <th>Correct?</th>
                </tr>
            </thead>
            <tbody>
        """,
        do_flush=True,
    )

    db_file, table_infos = await data_ingestion(
        db_config.csv_zip_path,
        db_config.search_glob,
        db_config.concurrency,
        db_config.model,
    )

    vector_index_dir = await index_all_tables(db_file)

    # Launch tasks concurrently
    tasks = [
        run_grouped_task(
            i,
            row.Index,
            row.question,
            row.answer,
            row.sql,
            semaphore,
            target_model_config,
            review_model_config,
            counter,
            counter_lock,
            db_file,
            table_infos,
            vector_index_dir,
        )
        for i, row in enumerate(df.itertuples(index=True))
    ]
    await asyncio.gather(*tasks)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    async with counter_lock:
        return (
            (counter["correct"] / counter["processed"]) if counter["processed"] else 0.0
        )

# {{/docs-fragment evaluate_prompt}}

@dataclass
class PromptResult:
    prompt: str
    accuracy: float

# {{docs-fragment prompt_optimizer}}
@env.task(report=True)
async def prompt_optimizer(
    df_val: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    optimizer_model_config: ModelConfig,
    max_iterations: int,
    concurrency: int,
    db_config: DatabaseConfig,
) -> tuple[str, float]:
    prompt_accuracies: list[PromptResult] = []

    # Send styling + table header immediately
    await flyte.report.log.aio(
        CSS
        + """
    <h2 style="margin-bottom:6px;">📊 Prompt Accuracy Comparison</h2>
    <table class="results-table">
        <thead>
            <tr>
                <th>Prompt</th>
                <th>Accuracy</th>
            </tr>
        </thead>
    <tbody>
    """,
        do_flush=True,
    )

    # Step 1: Evaluate starting prompt and stream row
    with flyte.group(name="baseline_evaluation"):
        starting_accuracy = await evaluate_prompt(
            df_val,
            target_model_config,
            review_model_config,
            concurrency,
            db_config,
        )
        prompt_accuracies.append(
            PromptResult(prompt=target_model_config.prompt, accuracy=starting_accuracy)
        )

        await _log_prompt_row(target_model_config.prompt, starting_accuracy)

    # Step 2: Optimize prompts one by one, streaming after each
    while len(prompt_accuracies) <= max_iterations:
        with flyte.group(name=f"prompt_optimization_step_{len(prompt_accuracies)}"):
            # Prepare prompt scores string for optimizer
            prompt_scores_str = "\n".join(
                f"{result.prompt}: {result.accuracy:.2f}"
                for result in sorted(prompt_accuracies, key=lambda x: x.accuracy)
            )

            optimizer_model_prompt = optimizer_model_config.prompt.format(
                prompt_scores_str=prompt_scores_str
            )
            response = await call_model(
                optimizer_model_config,
                [{"role": "system", "content": optimizer_model_prompt}],
            )
            response = response.strip()

            match = re.search(r"\[\[(.*?)\]\]", response, re.DOTALL)
            if not match:
                print("No new prompt found. Skipping.")
                continue

            new_prompt = match.group(1)
            target_model_config.prompt = new_prompt
            accuracy = await evaluate_prompt(
                df_val,
                target_model_config,
                review_model_config,
                concurrency,
                db_config,
            )
            prompt_accuracies.append(PromptResult(prompt=new_prompt, accuracy=accuracy))

            # Log this new prompt row immediately
            await _log_prompt_row(new_prompt, accuracy)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    # Find best
    best_result = max(prompt_accuracies, key=lambda x: x.accuracy)
    improvement = best_result.accuracy - starting_accuracy

    # Summary
    await flyte.report.log.aio(
        f"""
    <div class="summary-card">
        <h3>🏆 Summary</h3>
        <p><strong>Best Prompt:</strong> {html.escape(best_result.prompt)}</p>
        <p><strong>Best Accuracy:</strong> {best_result.accuracy*100:.2f}%</p>
        <p><strong>Improvement Over Baseline:</strong> {improvement*100:.2f}%</p>
    </div>
    """,
        do_flush=True,
    )

    return best_result.prompt, best_result.accuracy

# {{/docs-fragment prompt_optimizer}}

async def _log_prompt_row(prompt: str, accuracy: float):
    """Helper to log a single prompt/accuracy row to Flyte report."""
    pct = accuracy * 100
    if pct > 80:
        color = "linear-gradient(90deg, #4CAF50, #81C784)"
    elif pct > 60:
        color = "linear-gradient(90deg, #FFC107, #FFD54F)"
    else:
        color = "linear-gradient(90deg, #F44336, #E57373)"

    await flyte.report.log.aio(
        f"""
        <tr>
            <td>{html.escape(prompt)}</td>
            <td>
                {pct:.1f}%
                <div class="accuracy-bar-container">
                    <div class="accuracy-bar" style="width:{pct*1.6}px; background:{color};"></div>
                </div>
            </td>
        </tr>
        """,
        do_flush=True,
    )

# {{docs-fragment auto_prompt_engineering}}
@env.task
async def auto_prompt_engineering(
    ground_truth_csv: File | str = "/root/ground_truth.csv",
    db_config: DatabaseConfig = DatabaseConfig(
        csv_zip_path="https://github.com/ppasupat/WikiTableQuestions/releases/download/v1.0.2/WikiTableQuestions-1.0.2-compact.zip",
        search_glob="WikiTableQuestions/csv/200-csv/*.csv",
        concurrency=5,
        model="gpt-4o-mini",
    ),
    target_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="""Given an input question, create a syntactically correct {dialect} query to run.

Schema:
{schema}

Question: {query_str}

SQL query to run:
""",
        max_tokens=10000,
    ),
    review_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1",
        hosted_model_uri=None,
        prompt="""Your job is to determine whether the model's response is correct compared to the ground truth taking into account the context of the question.
Both answers were generated by running SQL queries on the same database.

- If the model's response contains all of the ground truth values, and any additional information is harmless (e.g., extra columns or metadata), output "True".
- If it adds incorrect or unrelated rows, or omits required values, output "False".

Question:
{query_str}

Ground Truth:
{answer}

Model Response:
{response}
""",
    ),
    optimizer_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1",
        hosted_model_uri=None,
        temperature=0.7,
        max_tokens=None,
        prompt="""
<EXPLANATION>
I have some prompts along with their corresponding accuracies.
The prompts are arranged in ascending order based on their accuracy, where higher accuracy indicates better quality.
</EXPLANATION>

<PROMPTS>
{prompt_scores_str}
</PROMPTS>

Each prompt was used to translate a natural-language question into a SQL query against a provided database schema.

<EXAMPLE>
<SCHEMA>
artists(id, name)
albums(id, title, artist_id, release_year)
</SCHEMA>
<QUESTION>
How many albums did The Beatles release?
</QUESTION>
<ANSWER>
SELECT COUNT(*) FROM albums a JOIN artists r ON a.artist_id = r.id WHERE r.name = 'The Beatles';
</ANSWER>
</EXAMPLE>

<TASK>
Write a new prompt that will achieve an accuracy as high as possible and that is different from the old ones.
</TASK>

<RULES>
- It is very important that the new prompt is distinct from ALL the old ones!
- Ensure that you analyse the prompts with a high accuracy and reuse the patterns that worked in the past.
- Ensure that you analyse the prompts with a low accuracy and avoid the patterns that didn't work in the past.
- Think out loud before creating the prompt. Describe what has worked in the past and what hasn't. Only then create the new prompt.
- Use all available information like prompt length, formal/informal use of language, etc. for your analysis.
- Be creative, try out different ways of prompting the model. You may even come up with hypothetical scenarios that might improve the accuracy.
- You are generating a system prompt. Always use three placeholders for each prompt: dialect, schema, query_str.
- Write your new prompt in double square brackets. Use only plain text for the prompt text and do not add any markdown (i.e. no hashtags, backticks, quotes, etc).
</RULES>
""",
    ),
    max_iterations: int = 5,
    concurrency: int = 10,
) -> dict[str, Union[str, float]]:
    if isinstance(ground_truth_csv, str) and os.path.isfile(ground_truth_csv):
        ground_truth_csv = await File.from_local(ground_truth_csv)

    df_val, df_test = await data_prep(ground_truth_csv)

    best_prompt, val_accuracy = await prompt_optimizer(
        df_val,
        target_model_config,
        review_model_config,
        optimizer_model_config,
        max_iterations,
        concurrency,
        db_config,
    )

    with flyte.group(name="test_data_evaluation"):
        baseline_test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
            db_config,
        )

        target_model_config.prompt = best_prompt
        test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
            db_config,
        )

    return {
        "best_prompt": best_prompt,
        "validation_accuracy": val_accuracy,
        "baseline_test_accuracy": baseline_test_accuracy,
        "test_accuracy": test_accuracy,
    }

# {{/docs-fragment auto_prompt_engineering}}

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(auto_prompt_engineering)
    print(run.url)
    run.wait()
CODE13
python create_qa_dataset.py
CODE14
python optimizer.py
```

## What we observed

Prompt optimization didn't consistently lift SQL accuracy in this workflow. Accuracy plateaued near the baseline. But the process surfaced valuable lessons about what matters when building LLM-powered systems on real infrastructure.

- **Schema clarity matters**: CSV ingestion produced tables with overlapping names, creating ambiguity. This showed how schema design and metadata hygiene directly affect downstream evaluation.
- **Ground truth needs trust**: Because the dataset came from LLM outputs, noise remained even after filtering. Human review proved essential. Golden datasets need deliberate curation, not just automation.
- **Optimization needs context**: The optimizer couldn't “see” which examples failed, limiting its ability to improve. Feeding failures directly risks overfitting. A structured way to capture and reuse evaluation signals is the right long-term path.

Sometimes prompt tweaks alone can lift accuracy, but other times the real bottleneck lives in the data, the schema, or the evaluation loop. The lesson isn't "prompt optimization doesn't work", but that its impact depends on the system around it. Accuracy improves most reliably when prompts evolve alongside clean data, trusted evaluation, and observable feedback loops.

## The bigger lesson

Evaluation and optimization aren’t one-off experiments; they’re continuous processes. What makes them sustainable isn't a clever prompt, it’s the platform around it.

Systems succeed when they:

- **Observe** failures with clarity — track exactly what failed and why.
- **Remain durable** across iterations — run pipelines that are stable, reproducible, and comparable over time.

That's where Flyte 2 comes in. Prompt optimization is one lever, but it becomes powerful only when combined with:

- Clean, human-validated evaluation datasets.
- Systematic reporting and feedback loops.

**The real takeaway: improving LLM pipelines isn't about chasing the perfect prompt. It's about designing workflows with observability and durability at the core, so that every experiment compounds into long-term progress.**


=== PAGE: https://www.union.ai/docs/v2/union/tutorials/auto_prompt_engineering ===

# Automatic prompt engineering

> [!NOTE]
> Code available [here](https://github.com/unionai/unionai-examples/tree/main/v2/tutorials/auto_prompt_engineering).

When building with LLMs and agents, the first prompt almost never works. We usually need several iterations before results are useful. Doing this manually is slow, inconsistent, and hard to reproduce.

Flyte turns prompt engineering into a systematic process. With Flyte we can:

- Generate candidate prompts automatically.
- Run evaluations in parallel.
- Track results in real time with built-in observability.
- Recover from failures without losing progress.
- Trace the lineage of every experiment for reproducibility.

And we're not limited to prompts. Just like [hyperparameter optimization](../hpo/_index) in ML, we can tune model temperature, retrieval strategies, tool usage, and more. Over time, this grows into full agentic evaluations, tracking not only prompts but also how agents behave, make decisions, and interact with their environment.

In this tutorial, we'll build an automated prompt engineering pipeline with Flyte, step by step.

## Set up the environment

First, let's configure our task environment.

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "pandas==2.3.1",
#    "pyarrow==21.0.0",
#    "litellm==1.75.0",
# ]
# main = "auto_prompt_engineering"
# params = ""
# ///

# {{docs-fragment env}}
import asyncio
import html
import os
import re
from dataclasses import dataclass
from typing import Optional, Union

import flyte
import flyte.report
import pandas as pd
from flyte.io._file import File

env = flyte.TaskEnvironment(
    name="auto-prompt-engineering",
    image=flyte.Image.from_uv_script(
        __file__, name="auto-prompt-engineering", pre=True
    ),
    secrets=[flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY")],
    resources=flyte.Resources(cpu=1),
)

CSS = """
<style>
    body {
        font-family: 'Segoe UI', Roboto, Arial, sans-serif;
    }
    .results-table {
        border-collapse: collapse;
        width: 100%;
        box-shadow: 0 2px 5px rgba(0,0,0,0.1);
        font-size: 14px;
    }
    .results-table th {
        background: linear-gradient(135deg, #4CAF50, #2E7D32);
        color: white;
        padding: 10px;
        text-align: left;
    }
    .results-table td {
        border: 1px solid #ddd;
        padding: 8px;
        vertical-align: top;
    }
    .results-table tr:nth-child(even) {background-color: #f9f9f9;}
    .results-table tr:hover {background-color: #f1f1f1;}
    .correct {color: #2E7D32; font-weight: bold;}
    .incorrect {color: #C62828; font-weight: bold;}
    .summary-card {
        background: #f9fbfd;
        padding: 14px 18px;
        border-radius: 8px;
        box-shadow: 0 1px 4px rgba(0,0,0,0.05);
        max-width: 800px;
        margin-top: 12px;
    }
    .summary-card h3 {
        margin-top: 0;
        color: #1e88e5;
        font-size: 16px;
    }
</style>
"""

# {{/docs-fragment env}}

# {{docs-fragment data_prep}}
@env.task
async def data_prep(csv_file: File | str) -> tuple[pd.DataFrame, pd.DataFrame]:
    """
    Load Q&A data from a public Google Sheet CSV export URL and split into train/test DataFrames.
    The sheet should have columns: 'input' and 'target'.
    """
    df = pd.read_csv(
        await csv_file.download() if isinstance(csv_file, File) else csv_file
    )

    if "input" not in df.columns or "target" not in df.columns:
        raise ValueError("Sheet must contain 'input' and 'target' columns.")

    # Shuffle rows
    df = df.sample(frac=1, random_state=1234).reset_index(drop=True)

    # Train/Test split
    df_train = df.iloc[:150].rename(columns={"input": "question", "target": "answer"})
    df_test = df.iloc[150:250].rename(columns={"input": "question", "target": "answer"})

    return df_train, df_test

# {{/docs-fragment data_prep}}

# {{docs-fragment model_config}}
@dataclass
class ModelConfig:
    model_name: str
    hosted_model_uri: Optional[str] = None
    temperature: float = 0.0
    max_tokens: Optional[int] = 1000
    timeout: int = 600
    prompt: str = ""

# {{/docs-fragment model_config}}

# {{docs-fragment call_model}}
@flyte.trace
async def call_model(
    model_config: ModelConfig,
    messages: list[dict[str, str]],
) -> str:
    from litellm import acompletion

    response = await acompletion(
        model=model_config.model_name,
        api_base=model_config.hosted_model_uri,
        messages=messages,
        temperature=model_config.temperature,
        timeout=model_config.timeout,
        max_tokens=model_config.max_tokens,
    )
    return response.choices[0].message["content"]

# {{/docs-fragment call_model}}

# {{docs-fragment generate_and_review}}
async def generate_and_review(
    index: int,
    question: str,
    answer: str,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
) -> dict:
    # Generate response from target model
    response = await call_model(
        target_model_config,
        [
            {"role": "system", "content": target_model_config.prompt},
            {"role": "user", "content": question},
        ],
    )

    # Format review prompt with response + answer
    review_messages = [
        {
            "role": "system",
            "content": review_model_config.prompt.format(
                response=response,
                answer=answer,
            ),
        }
    ]
    verdict = await call_model(review_model_config, review_messages)

    # Normalize verdict
    verdict_clean = verdict.strip().lower()
    if verdict_clean not in {"true", "false"}:
        verdict_clean = "not sure"

    return {
        "index": index,
        "model_response": response,
        "is_correct": verdict_clean == "true",
    }

# {{/docs-fragment generate_and_review}}

async def run_grouped_task(
    i,
    index,
    question,
    answer,
    semaphore,
    target_model_config,
    review_model_config,
    counter,
    counter_lock,
):
    async with semaphore:
        with flyte.group(name=f"row-{i}"):
            result = await generate_and_review(
                index,
                question,
                answer,
                target_model_config,
                review_model_config,
            )

            async with counter_lock:
                # Update counters
                counter["processed"] += 1
                if result["is_correct"]:
                    counter["correct"] += 1
                    correct_html = "<span class='correct'>✔ Yes</span>"
                else:
                    correct_html = "<span class='incorrect'>✘ No</span>"

                # Calculate accuracy
                accuracy_pct = (counter["correct"] / counter["processed"]) * 100

            # Update chart
            await flyte.report.log.aio(
                f"<script>updateAccuracy({accuracy_pct});</script>",
                do_flush=True,
            )

            # Add row to table
            await flyte.report.log.aio(
                f"""
                <tr>
                    <td>{html.escape(question)}</td>
                    <td>{html.escape(answer)}</td>
                    <td>{result['model_response']}</td>
                    <td>{correct_html}</td>
                </tr>
                """,
                do_flush=True,
            )

            return result

# {{docs-fragment evaluate_prompt}}
@env.task(report=True)
async def evaluate_prompt(
    df: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    concurrency: int,
) -> float:
    semaphore = asyncio.Semaphore(concurrency)
    counter = {"correct": 0, "processed": 0}
    counter_lock = asyncio.Lock()

    # Write initial HTML structure
    await flyte.report.log.aio(
        CSS
        + """
        <script>
            function updateAccuracy(percent) {
                const bar = document.getElementById('acc-bar');
                const label = document.getElementById('acc-label');
                bar.setAttribute('width', percent * 3);
                label.textContent = `Accuracy: ${percent.toFixed(1)}%`;
            }
        </script>

        <h2 style="margin-top:0;">Model Evaluation Results</h2>
        <h3>Live Accuracy</h3>
        <svg width="320" height="30" id="accuracy-chart">
            <defs>
                <linearGradient id="acc-gradient" x1="0" x2="1" y1="0" y2="0">
                    <stop offset="0%" stop-color="#66bb6a"/>
                    <stop offset="100%" stop-color="#2e7d32"/>
                </linearGradient>
            </defs>
            <rect width="300" height="20" fill="#ddd" rx="5" ry="5"></rect>
            <rect id="acc-bar" width="0" height="20" fill="url(#acc-gradient)" rx="5" ry="5"></rect>
            <text id="acc-label" x="150" y="15" font-size="12" font-weight="bold" text-anchor="middle" fill="#000">
                Accuracy: 0.0%
            </text>
        </svg>

        <table class="results-table">
            <thead>
                <tr>
                    <th>Question</th>
                    <th>Answer</th>
                    <th>Model Response</th>
                    <th>Correct?</th>
                </tr>
            </thead>
            <tbody>
        """,
        do_flush=True,
    )

    # Launch tasks concurrently
    tasks = [
        run_grouped_task(
            i,
            row.Index,
            row.question,
            row.answer,
            semaphore,
            target_model_config,
            review_model_config,
            counter,
            counter_lock,
        )
        for i, row in enumerate(df.itertuples(index=True))
    ]
    await asyncio.gather(*tasks)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    async with counter_lock:
        return (
            (counter["correct"] / counter["processed"]) if counter["processed"] else 0.0
        )

# {{/docs-fragment evaluate_prompt}}

@dataclass
class PromptResult:
    prompt: str
    accuracy: float

# {{docs-fragment prompt_optimizer}}
@env.task(report=True)
async def prompt_optimizer(
    df_train: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    optimizer_model_config: ModelConfig,
    max_iterations: int,
    concurrency: int,
) -> tuple[str, float]:
    prompt_accuracies: list[PromptResult] = []

    # Send styling + table header immediately
    await flyte.report.log.aio(
        CSS
        + """
    <h2 style="margin-bottom:6px;">📊 Prompt Accuracy Comparison</h2>
    <table class="results-table">
        <thead>
            <tr>
                <th>Prompt</th>
                <th>Accuracy</th>
            </tr>
        </thead>
    <tbody>
    """,
        do_flush=True,
    )

    # Step 1: Evaluate starting prompt and stream row
    with flyte.group(name="baseline_evaluation"):
        starting_accuracy = await evaluate_prompt(
            df_train,
            target_model_config,
            review_model_config,
            concurrency,
        )
        prompt_accuracies.append(
            PromptResult(prompt=target_model_config.prompt, accuracy=starting_accuracy)
        )

        await _log_prompt_row(target_model_config.prompt, starting_accuracy)

    # Step 2: Optimize prompts one by one, streaming after each
    while len(prompt_accuracies) <= max_iterations:
        with flyte.group(name=f"prompt_optimization_step_{len(prompt_accuracies)}"):
            # Prepare prompt scores string for optimizer
            prompt_scores_str = "\n".join(
                f"{result.prompt}: {result.accuracy:.2f}"
                for result in sorted(prompt_accuracies, key=lambda x: x.accuracy)
            )

            optimizer_model_prompt = optimizer_model_config.prompt.format(
                prompt_scores_str=prompt_scores_str
            )
            response = await call_model(
                optimizer_model_config,
                [{"role": "system", "content": optimizer_model_prompt}],
            )
            response = response.strip()

            match = re.search(r"\[\[(.*?)\]\]", response, re.DOTALL)
            if not match:
                print("No new prompt found. Skipping.")
                continue

            new_prompt = match.group(1)
            target_model_config.prompt = new_prompt
            accuracy = await evaluate_prompt(
                df_train,
                target_model_config,
                review_model_config,
                concurrency,
            )
            prompt_accuracies.append(PromptResult(prompt=new_prompt, accuracy=accuracy))

            # Log this new prompt row immediately
            await _log_prompt_row(new_prompt, accuracy)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    # Find best
    best_result = max(prompt_accuracies, key=lambda x: x.accuracy)
    improvement = best_result.accuracy - starting_accuracy

    # Summary
    await flyte.report.log.aio(
        f"""
    <div class="summary-card">
        <h3>🏆 Summary</h3>
        <p><strong>Best Prompt:</strong> {html.escape(best_result.prompt)}</p>
        <p><strong>Best Accuracy:</strong> {best_result.accuracy*100:.2f}%</p>
        <p><strong>Improvement Over Baseline:</strong> {improvement*100:.2f}%</p>
    </div>
    """,
        do_flush=True,
    )

    return best_result.prompt, best_result.accuracy

# {{/docs-fragment prompt_optimizer}}

async def _log_prompt_row(prompt: str, accuracy: float):
    """Helper to log a single prompt/accuracy row to Flyte report."""
    pct = accuracy * 100
    if pct > 80:
        color = "linear-gradient(90deg, #4CAF50, #81C784)"
    elif pct > 60:
        color = "linear-gradient(90deg, #FFC107, #FFD54F)"
    else:
        color = "linear-gradient(90deg, #F44336, #E57373)"

    await flyte.report.log.aio(
        f"""
        <tr>
            <td>{html.escape(prompt)}</td>
            <td>
                {pct:.1f}%
                <div class="accuracy-bar-container">
                    <div class="accuracy-bar" style="width:{pct*1.6}px; background:{color};"></div>
                </div>
            </td>
        </tr>
        """,
        do_flush=True,
    )

# {{docs-fragment auto_prompt_engineering}}
@env.task
async def auto_prompt_engineering(
    csv_file: File | str = "https://dub.sh/geometric-shapes",
    target_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="Solve the given problem about geometric shapes. Think step by step.",
        max_tokens=10000,
    ),
    review_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="""You are a review model tasked with evaluating the correctness of a response to a navigation problem.
The response may contain detailed steps and explanations, but the final answer is the key point.
Please determine if the final answer provided in the response is correct based on the ground truth number.
Respond with 'True' if the final answer is correct and 'False' if it is not.
Only respond with 'True' or 'False', nothing else.

Model Response:
{response}

Ground Truth:
{answer}
""",
    ),
    optimizer_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1",
        hosted_model_uri=None,
        temperature=0.7,
        max_tokens=None,
        prompt="""
<EXPLANATION>
I have some prompts along with their corresponding accuracies.
The prompts are arranged in ascending order based on their accuracy, where higher accuracy indicate better quality.
</EXPLANATION>

<PROMPTS>
{prompt_scores_str}
</PROMPTS>

Each prompt was used together with a problem statement around geometric shapes.

<EXAMPLE>
<QUESTION>
This SVG path element <path d="M 55.57,80.69 L 57.38,65.80 M 57.38,65.80 L 48.90,57.46 M 48.90,57.46 L 45.58,47.78 M 45.58,47.78 L 53.25,36.07 L 66.29,48.90 L 78.69,61.09 L 55.57,80.69"/> draws a Options: (A) circle (B) heptagon (C) hexagon (D) kite (E) line (F) octagon (G) pentagon (H) rectangle (I) sector (J) triangle
</QUESTION>
<ANSWER>
(B)
</ANSWER>
</EXAMPLE>

<TASK>
Write a new prompt that will achieve an accuracy as high as possible and that is different from the old ones.
</TASK>

<RULES>
- It is very important that the new prompt is distinct from ALL the old ones!
- Ensure that you analyse the prompts with a high accuracy and reuse the patterns that worked in the past
- Ensure that you analyse the prompts with a low accuracy and avoid the patterns that didn't worked in the past
- Think out loud before creating the prompt. Describe what has worked in the past and what hasn't. Only then create the new prompt.
- Use all available information like prompt length, formal/informal use of language, etc for your analysis.
- Be creative, try out different ways of prompting the model. You may even come up with hypothetical scenarios that might improve the accuracy.
- You are generating system prompts. This means that there should be no placeholders in the prompt, as they cannot be filled at runtime. Instead focus on general instructions that will help the model to solve the task.
- Write your new prompt in double square brackets. Use only plain text for the prompt text and do not add any markdown (i.e. no hashtags, backticks, quotes, etc).
</RULES>
""",
    ),
    max_iterations: int = 3,
    concurrency: int = 10,
) -> dict[str, Union[str, float]]:
    if isinstance(csv_file, str) and os.path.isfile(csv_file):
        csv_file = await File.from_local(csv_file)

    df_train, df_test = await data_prep(csv_file)

    best_prompt, training_accuracy = await prompt_optimizer(
        df_train,
        target_model_config,
        review_model_config,
        optimizer_model_config,
        max_iterations,
        concurrency,
    )

    with flyte.group(name="test_data_evaluation"):
        baseline_test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
        )

        target_model_config.prompt = best_prompt
        test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
        )

    return {
        "best_prompt": best_prompt,
        "training_accuracy": training_accuracy,
        "baseline_test_accuracy": baseline_test_accuracy,
        "test_accuracy": test_accuracy,
    }

# {{/docs-fragment auto_prompt_engineering}}

# {{docs-fragment main}}
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(auto_prompt_engineering)
    print(run.url)
    run.wait()
# {{/docs-fragment main}}
CODE0
flyte create secret openai_api_key <YOUR_OPENAI_API_KEY>
```

We also define CSS styles for live HTML reports that track prompt optimization in real time:

![Results](https://raw.githubusercontent.com/unionai/unionai-docs-static/main/gifs/tutorials/prompt_engineering/results.gif)

## Prepare the evaluation dataset

Next, we define our golden dataset, a set of prompts with known outputs. This dataset is used to evaluate the quality of generated prompts.

For this tutorial, we use a small geometric shapes dataset. To keep it portable, the data prep task takes a CSV file (as a Flyte `File` or a string for files available remotely) and splits it into train and test subsets.

If you already have prompts and outputs in Google Sheets, simply export them as CSV with two columns: `input` and `target`.

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "pandas==2.3.1",
#    "pyarrow==21.0.0",
#    "litellm==1.75.0",
# ]
# main = "auto_prompt_engineering"
# params = ""
# ///

# {{docs-fragment env}}
import asyncio
import html
import os
import re
from dataclasses import dataclass
from typing import Optional, Union

import flyte
import flyte.report
import pandas as pd
from flyte.io._file import File

env = flyte.TaskEnvironment(
    name="auto-prompt-engineering",
    image=flyte.Image.from_uv_script(
        __file__, name="auto-prompt-engineering", pre=True
    ),
    secrets=[flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY")],
    resources=flyte.Resources(cpu=1),
)

CSS = """
<style>
    body {
        font-family: 'Segoe UI', Roboto, Arial, sans-serif;
    }
    .results-table {
        border-collapse: collapse;
        width: 100%;
        box-shadow: 0 2px 5px rgba(0,0,0,0.1);
        font-size: 14px;
    }
    .results-table th {
        background: linear-gradient(135deg, #4CAF50, #2E7D32);
        color: white;
        padding: 10px;
        text-align: left;
    }
    .results-table td {
        border: 1px solid #ddd;
        padding: 8px;
        vertical-align: top;
    }
    .results-table tr:nth-child(even) {background-color: #f9f9f9;}
    .results-table tr:hover {background-color: #f1f1f1;}
    .correct {color: #2E7D32; font-weight: bold;}
    .incorrect {color: #C62828; font-weight: bold;}
    .summary-card {
        background: #f9fbfd;
        padding: 14px 18px;
        border-radius: 8px;
        box-shadow: 0 1px 4px rgba(0,0,0,0.05);
        max-width: 800px;
        margin-top: 12px;
    }
    .summary-card h3 {
        margin-top: 0;
        color: #1e88e5;
        font-size: 16px;
    }
</style>
"""

# {{/docs-fragment env}}

# {{docs-fragment data_prep}}
@env.task
async def data_prep(csv_file: File | str) -> tuple[pd.DataFrame, pd.DataFrame]:
    """
    Load Q&A data from a public Google Sheet CSV export URL and split into train/test DataFrames.
    The sheet should have columns: 'input' and 'target'.
    """
    df = pd.read_csv(
        await csv_file.download() if isinstance(csv_file, File) else csv_file
    )

    if "input" not in df.columns or "target" not in df.columns:
        raise ValueError("Sheet must contain 'input' and 'target' columns.")

    # Shuffle rows
    df = df.sample(frac=1, random_state=1234).reset_index(drop=True)

    # Train/Test split
    df_train = df.iloc[:150].rename(columns={"input": "question", "target": "answer"})
    df_test = df.iloc[150:250].rename(columns={"input": "question", "target": "answer"})

    return df_train, df_test

# {{/docs-fragment data_prep}}

# {{docs-fragment model_config}}
@dataclass
class ModelConfig:
    model_name: str
    hosted_model_uri: Optional[str] = None
    temperature: float = 0.0
    max_tokens: Optional[int] = 1000
    timeout: int = 600
    prompt: str = ""

# {{/docs-fragment model_config}}

# {{docs-fragment call_model}}
@flyte.trace
async def call_model(
    model_config: ModelConfig,
    messages: list[dict[str, str]],
) -> str:
    from litellm import acompletion

    response = await acompletion(
        model=model_config.model_name,
        api_base=model_config.hosted_model_uri,
        messages=messages,
        temperature=model_config.temperature,
        timeout=model_config.timeout,
        max_tokens=model_config.max_tokens,
    )
    return response.choices[0].message["content"]

# {{/docs-fragment call_model}}

# {{docs-fragment generate_and_review}}
async def generate_and_review(
    index: int,
    question: str,
    answer: str,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
) -> dict:
    # Generate response from target model
    response = await call_model(
        target_model_config,
        [
            {"role": "system", "content": target_model_config.prompt},
            {"role": "user", "content": question},
        ],
    )

    # Format review prompt with response + answer
    review_messages = [
        {
            "role": "system",
            "content": review_model_config.prompt.format(
                response=response,
                answer=answer,
            ),
        }
    ]
    verdict = await call_model(review_model_config, review_messages)

    # Normalize verdict
    verdict_clean = verdict.strip().lower()
    if verdict_clean not in {"true", "false"}:
        verdict_clean = "not sure"

    return {
        "index": index,
        "model_response": response,
        "is_correct": verdict_clean == "true",
    }

# {{/docs-fragment generate_and_review}}

async def run_grouped_task(
    i,
    index,
    question,
    answer,
    semaphore,
    target_model_config,
    review_model_config,
    counter,
    counter_lock,
):
    async with semaphore:
        with flyte.group(name=f"row-{i}"):
            result = await generate_and_review(
                index,
                question,
                answer,
                target_model_config,
                review_model_config,
            )

            async with counter_lock:
                # Update counters
                counter["processed"] += 1
                if result["is_correct"]:
                    counter["correct"] += 1
                    correct_html = "<span class='correct'>✔ Yes</span>"
                else:
                    correct_html = "<span class='incorrect'>✘ No</span>"

                # Calculate accuracy
                accuracy_pct = (counter["correct"] / counter["processed"]) * 100

            # Update chart
            await flyte.report.log.aio(
                f"<script>updateAccuracy({accuracy_pct});</script>",
                do_flush=True,
            )

            # Add row to table
            await flyte.report.log.aio(
                f"""
                <tr>
                    <td>{html.escape(question)}</td>
                    <td>{html.escape(answer)}</td>
                    <td>{result['model_response']}</td>
                    <td>{correct_html}</td>
                </tr>
                """,
                do_flush=True,
            )

            return result

# {{docs-fragment evaluate_prompt}}
@env.task(report=True)
async def evaluate_prompt(
    df: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    concurrency: int,
) -> float:
    semaphore = asyncio.Semaphore(concurrency)
    counter = {"correct": 0, "processed": 0}
    counter_lock = asyncio.Lock()

    # Write initial HTML structure
    await flyte.report.log.aio(
        CSS
        + """
        <script>
            function updateAccuracy(percent) {
                const bar = document.getElementById('acc-bar');
                const label = document.getElementById('acc-label');
                bar.setAttribute('width', percent * 3);
                label.textContent = `Accuracy: ${percent.toFixed(1)}%`;
            }
        </script>

        <h2 style="margin-top:0;">Model Evaluation Results</h2>
        <h3>Live Accuracy</h3>
        <svg width="320" height="30" id="accuracy-chart">
            <defs>
                <linearGradient id="acc-gradient" x1="0" x2="1" y1="0" y2="0">
                    <stop offset="0%" stop-color="#66bb6a"/>
                    <stop offset="100%" stop-color="#2e7d32"/>
                </linearGradient>
            </defs>
            <rect width="300" height="20" fill="#ddd" rx="5" ry="5"></rect>
            <rect id="acc-bar" width="0" height="20" fill="url(#acc-gradient)" rx="5" ry="5"></rect>
            <text id="acc-label" x="150" y="15" font-size="12" font-weight="bold" text-anchor="middle" fill="#000">
                Accuracy: 0.0%
            </text>
        </svg>

        <table class="results-table">
            <thead>
                <tr>
                    <th>Question</th>
                    <th>Answer</th>
                    <th>Model Response</th>
                    <th>Correct?</th>
                </tr>
            </thead>
            <tbody>
        """,
        do_flush=True,
    )

    # Launch tasks concurrently
    tasks = [
        run_grouped_task(
            i,
            row.Index,
            row.question,
            row.answer,
            semaphore,
            target_model_config,
            review_model_config,
            counter,
            counter_lock,
        )
        for i, row in enumerate(df.itertuples(index=True))
    ]
    await asyncio.gather(*tasks)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    async with counter_lock:
        return (
            (counter["correct"] / counter["processed"]) if counter["processed"] else 0.0
        )

# {{/docs-fragment evaluate_prompt}}

@dataclass
class PromptResult:
    prompt: str
    accuracy: float

# {{docs-fragment prompt_optimizer}}
@env.task(report=True)
async def prompt_optimizer(
    df_train: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    optimizer_model_config: ModelConfig,
    max_iterations: int,
    concurrency: int,
) -> tuple[str, float]:
    prompt_accuracies: list[PromptResult] = []

    # Send styling + table header immediately
    await flyte.report.log.aio(
        CSS
        + """
    <h2 style="margin-bottom:6px;">📊 Prompt Accuracy Comparison</h2>
    <table class="results-table">
        <thead>
            <tr>
                <th>Prompt</th>
                <th>Accuracy</th>
            </tr>
        </thead>
    <tbody>
    """,
        do_flush=True,
    )

    # Step 1: Evaluate starting prompt and stream row
    with flyte.group(name="baseline_evaluation"):
        starting_accuracy = await evaluate_prompt(
            df_train,
            target_model_config,
            review_model_config,
            concurrency,
        )
        prompt_accuracies.append(
            PromptResult(prompt=target_model_config.prompt, accuracy=starting_accuracy)
        )

        await _log_prompt_row(target_model_config.prompt, starting_accuracy)

    # Step 2: Optimize prompts one by one, streaming after each
    while len(prompt_accuracies) <= max_iterations:
        with flyte.group(name=f"prompt_optimization_step_{len(prompt_accuracies)}"):
            # Prepare prompt scores string for optimizer
            prompt_scores_str = "\n".join(
                f"{result.prompt}: {result.accuracy:.2f}"
                for result in sorted(prompt_accuracies, key=lambda x: x.accuracy)
            )

            optimizer_model_prompt = optimizer_model_config.prompt.format(
                prompt_scores_str=prompt_scores_str
            )
            response = await call_model(
                optimizer_model_config,
                [{"role": "system", "content": optimizer_model_prompt}],
            )
            response = response.strip()

            match = re.search(r"\[\[(.*?)\]\]", response, re.DOTALL)
            if not match:
                print("No new prompt found. Skipping.")
                continue

            new_prompt = match.group(1)
            target_model_config.prompt = new_prompt
            accuracy = await evaluate_prompt(
                df_train,
                target_model_config,
                review_model_config,
                concurrency,
            )
            prompt_accuracies.append(PromptResult(prompt=new_prompt, accuracy=accuracy))

            # Log this new prompt row immediately
            await _log_prompt_row(new_prompt, accuracy)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    # Find best
    best_result = max(prompt_accuracies, key=lambda x: x.accuracy)
    improvement = best_result.accuracy - starting_accuracy

    # Summary
    await flyte.report.log.aio(
        f"""
    <div class="summary-card">
        <h3>🏆 Summary</h3>
        <p><strong>Best Prompt:</strong> {html.escape(best_result.prompt)}</p>
        <p><strong>Best Accuracy:</strong> {best_result.accuracy*100:.2f}%</p>
        <p><strong>Improvement Over Baseline:</strong> {improvement*100:.2f}%</p>
    </div>
    """,
        do_flush=True,
    )

    return best_result.prompt, best_result.accuracy

# {{/docs-fragment prompt_optimizer}}

async def _log_prompt_row(prompt: str, accuracy: float):
    """Helper to log a single prompt/accuracy row to Flyte report."""
    pct = accuracy * 100
    if pct > 80:
        color = "linear-gradient(90deg, #4CAF50, #81C784)"
    elif pct > 60:
        color = "linear-gradient(90deg, #FFC107, #FFD54F)"
    else:
        color = "linear-gradient(90deg, #F44336, #E57373)"

    await flyte.report.log.aio(
        f"""
        <tr>
            <td>{html.escape(prompt)}</td>
            <td>
                {pct:.1f}%
                <div class="accuracy-bar-container">
                    <div class="accuracy-bar" style="width:{pct*1.6}px; background:{color};"></div>
                </div>
            </td>
        </tr>
        """,
        do_flush=True,
    )

# {{docs-fragment auto_prompt_engineering}}
@env.task
async def auto_prompt_engineering(
    csv_file: File | str = "https://dub.sh/geometric-shapes",
    target_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="Solve the given problem about geometric shapes. Think step by step.",
        max_tokens=10000,
    ),
    review_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="""You are a review model tasked with evaluating the correctness of a response to a navigation problem.
The response may contain detailed steps and explanations, but the final answer is the key point.
Please determine if the final answer provided in the response is correct based on the ground truth number.
Respond with 'True' if the final answer is correct and 'False' if it is not.
Only respond with 'True' or 'False', nothing else.

Model Response:
{response}

Ground Truth:
{answer}
""",
    ),
    optimizer_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1",
        hosted_model_uri=None,
        temperature=0.7,
        max_tokens=None,
        prompt="""
<EXPLANATION>
I have some prompts along with their corresponding accuracies.
The prompts are arranged in ascending order based on their accuracy, where higher accuracy indicate better quality.
</EXPLANATION>

<PROMPTS>
{prompt_scores_str}
</PROMPTS>

Each prompt was used together with a problem statement around geometric shapes.

<EXAMPLE>
<QUESTION>
This SVG path element <path d="M 55.57,80.69 L 57.38,65.80 M 57.38,65.80 L 48.90,57.46 M 48.90,57.46 L 45.58,47.78 M 45.58,47.78 L 53.25,36.07 L 66.29,48.90 L 78.69,61.09 L 55.57,80.69"/> draws a Options: (A) circle (B) heptagon (C) hexagon (D) kite (E) line (F) octagon (G) pentagon (H) rectangle (I) sector (J) triangle
</QUESTION>
<ANSWER>
(B)
</ANSWER>
</EXAMPLE>

<TASK>
Write a new prompt that will achieve an accuracy as high as possible and that is different from the old ones.
</TASK>

<RULES>
- It is very important that the new prompt is distinct from ALL the old ones!
- Ensure that you analyse the prompts with a high accuracy and reuse the patterns that worked in the past
- Ensure that you analyse the prompts with a low accuracy and avoid the patterns that didn't worked in the past
- Think out loud before creating the prompt. Describe what has worked in the past and what hasn't. Only then create the new prompt.
- Use all available information like prompt length, formal/informal use of language, etc for your analysis.
- Be creative, try out different ways of prompting the model. You may even come up with hypothetical scenarios that might improve the accuracy.
- You are generating system prompts. This means that there should be no placeholders in the prompt, as they cannot be filled at runtime. Instead focus on general instructions that will help the model to solve the task.
- Write your new prompt in double square brackets. Use only plain text for the prompt text and do not add any markdown (i.e. no hashtags, backticks, quotes, etc).
</RULES>
""",
    ),
    max_iterations: int = 3,
    concurrency: int = 10,
) -> dict[str, Union[str, float]]:
    if isinstance(csv_file, str) and os.path.isfile(csv_file):
        csv_file = await File.from_local(csv_file)

    df_train, df_test = await data_prep(csv_file)

    best_prompt, training_accuracy = await prompt_optimizer(
        df_train,
        target_model_config,
        review_model_config,
        optimizer_model_config,
        max_iterations,
        concurrency,
    )

    with flyte.group(name="test_data_evaluation"):
        baseline_test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
        )

        target_model_config.prompt = best_prompt
        test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
        )

    return {
        "best_prompt": best_prompt,
        "training_accuracy": training_accuracy,
        "baseline_test_accuracy": baseline_test_accuracy,
        "test_accuracy": test_accuracy,
    }

# {{/docs-fragment auto_prompt_engineering}}

# {{docs-fragment main}}
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(auto_prompt_engineering)
    print(run.url)
    run.wait()
# {{/docs-fragment main}}
CODE1
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "pandas==2.3.1",
#    "pyarrow==21.0.0",
#    "litellm==1.75.0",
# ]
# main = "auto_prompt_engineering"
# params = ""
# ///

# {{docs-fragment env}}
import asyncio
import html
import os
import re
from dataclasses import dataclass
from typing import Optional, Union

import flyte
import flyte.report
import pandas as pd
from flyte.io._file import File

env = flyte.TaskEnvironment(
    name="auto-prompt-engineering",
    image=flyte.Image.from_uv_script(
        __file__, name="auto-prompt-engineering", pre=True
    ),
    secrets=[flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY")],
    resources=flyte.Resources(cpu=1),
)

CSS = """
<style>
    body {
        font-family: 'Segoe UI', Roboto, Arial, sans-serif;
    }
    .results-table {
        border-collapse: collapse;
        width: 100%;
        box-shadow: 0 2px 5px rgba(0,0,0,0.1);
        font-size: 14px;
    }
    .results-table th {
        background: linear-gradient(135deg, #4CAF50, #2E7D32);
        color: white;
        padding: 10px;
        text-align: left;
    }
    .results-table td {
        border: 1px solid #ddd;
        padding: 8px;
        vertical-align: top;
    }
    .results-table tr:nth-child(even) {background-color: #f9f9f9;}
    .results-table tr:hover {background-color: #f1f1f1;}
    .correct {color: #2E7D32; font-weight: bold;}
    .incorrect {color: #C62828; font-weight: bold;}
    .summary-card {
        background: #f9fbfd;
        padding: 14px 18px;
        border-radius: 8px;
        box-shadow: 0 1px 4px rgba(0,0,0,0.05);
        max-width: 800px;
        margin-top: 12px;
    }
    .summary-card h3 {
        margin-top: 0;
        color: #1e88e5;
        font-size: 16px;
    }
</style>
"""

# {{/docs-fragment env}}

# {{docs-fragment data_prep}}
@env.task
async def data_prep(csv_file: File | str) -> tuple[pd.DataFrame, pd.DataFrame]:
    """
    Load Q&A data from a public Google Sheet CSV export URL and split into train/test DataFrames.
    The sheet should have columns: 'input' and 'target'.
    """
    df = pd.read_csv(
        await csv_file.download() if isinstance(csv_file, File) else csv_file
    )

    if "input" not in df.columns or "target" not in df.columns:
        raise ValueError("Sheet must contain 'input' and 'target' columns.")

    # Shuffle rows
    df = df.sample(frac=1, random_state=1234).reset_index(drop=True)

    # Train/Test split
    df_train = df.iloc[:150].rename(columns={"input": "question", "target": "answer"})
    df_test = df.iloc[150:250].rename(columns={"input": "question", "target": "answer"})

    return df_train, df_test

# {{/docs-fragment data_prep}}

# {{docs-fragment model_config}}
@dataclass
class ModelConfig:
    model_name: str
    hosted_model_uri: Optional[str] = None
    temperature: float = 0.0
    max_tokens: Optional[int] = 1000
    timeout: int = 600
    prompt: str = ""

# {{/docs-fragment model_config}}

# {{docs-fragment call_model}}
@flyte.trace
async def call_model(
    model_config: ModelConfig,
    messages: list[dict[str, str]],
) -> str:
    from litellm import acompletion

    response = await acompletion(
        model=model_config.model_name,
        api_base=model_config.hosted_model_uri,
        messages=messages,
        temperature=model_config.temperature,
        timeout=model_config.timeout,
        max_tokens=model_config.max_tokens,
    )
    return response.choices[0].message["content"]

# {{/docs-fragment call_model}}

# {{docs-fragment generate_and_review}}
async def generate_and_review(
    index: int,
    question: str,
    answer: str,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
) -> dict:
    # Generate response from target model
    response = await call_model(
        target_model_config,
        [
            {"role": "system", "content": target_model_config.prompt},
            {"role": "user", "content": question},
        ],
    )

    # Format review prompt with response + answer
    review_messages = [
        {
            "role": "system",
            "content": review_model_config.prompt.format(
                response=response,
                answer=answer,
            ),
        }
    ]
    verdict = await call_model(review_model_config, review_messages)

    # Normalize verdict
    verdict_clean = verdict.strip().lower()
    if verdict_clean not in {"true", "false"}:
        verdict_clean = "not sure"

    return {
        "index": index,
        "model_response": response,
        "is_correct": verdict_clean == "true",
    }

# {{/docs-fragment generate_and_review}}

async def run_grouped_task(
    i,
    index,
    question,
    answer,
    semaphore,
    target_model_config,
    review_model_config,
    counter,
    counter_lock,
):
    async with semaphore:
        with flyte.group(name=f"row-{i}"):
            result = await generate_and_review(
                index,
                question,
                answer,
                target_model_config,
                review_model_config,
            )

            async with counter_lock:
                # Update counters
                counter["processed"] += 1
                if result["is_correct"]:
                    counter["correct"] += 1
                    correct_html = "<span class='correct'>✔ Yes</span>"
                else:
                    correct_html = "<span class='incorrect'>✘ No</span>"

                # Calculate accuracy
                accuracy_pct = (counter["correct"] / counter["processed"]) * 100

            # Update chart
            await flyte.report.log.aio(
                f"<script>updateAccuracy({accuracy_pct});</script>",
                do_flush=True,
            )

            # Add row to table
            await flyte.report.log.aio(
                f"""
                <tr>
                    <td>{html.escape(question)}</td>
                    <td>{html.escape(answer)}</td>
                    <td>{result['model_response']}</td>
                    <td>{correct_html}</td>
                </tr>
                """,
                do_flush=True,
            )

            return result

# {{docs-fragment evaluate_prompt}}
@env.task(report=True)
async def evaluate_prompt(
    df: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    concurrency: int,
) -> float:
    semaphore = asyncio.Semaphore(concurrency)
    counter = {"correct": 0, "processed": 0}
    counter_lock = asyncio.Lock()

    # Write initial HTML structure
    await flyte.report.log.aio(
        CSS
        + """
        <script>
            function updateAccuracy(percent) {
                const bar = document.getElementById('acc-bar');
                const label = document.getElementById('acc-label');
                bar.setAttribute('width', percent * 3);
                label.textContent = `Accuracy: ${percent.toFixed(1)}%`;
            }
        </script>

        <h2 style="margin-top:0;">Model Evaluation Results</h2>
        <h3>Live Accuracy</h3>
        <svg width="320" height="30" id="accuracy-chart">
            <defs>
                <linearGradient id="acc-gradient" x1="0" x2="1" y1="0" y2="0">
                    <stop offset="0%" stop-color="#66bb6a"/>
                    <stop offset="100%" stop-color="#2e7d32"/>
                </linearGradient>
            </defs>
            <rect width="300" height="20" fill="#ddd" rx="5" ry="5"></rect>
            <rect id="acc-bar" width="0" height="20" fill="url(#acc-gradient)" rx="5" ry="5"></rect>
            <text id="acc-label" x="150" y="15" font-size="12" font-weight="bold" text-anchor="middle" fill="#000">
                Accuracy: 0.0%
            </text>
        </svg>

        <table class="results-table">
            <thead>
                <tr>
                    <th>Question</th>
                    <th>Answer</th>
                    <th>Model Response</th>
                    <th>Correct?</th>
                </tr>
            </thead>
            <tbody>
        """,
        do_flush=True,
    )

    # Launch tasks concurrently
    tasks = [
        run_grouped_task(
            i,
            row.Index,
            row.question,
            row.answer,
            semaphore,
            target_model_config,
            review_model_config,
            counter,
            counter_lock,
        )
        for i, row in enumerate(df.itertuples(index=True))
    ]
    await asyncio.gather(*tasks)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    async with counter_lock:
        return (
            (counter["correct"] / counter["processed"]) if counter["processed"] else 0.0
        )

# {{/docs-fragment evaluate_prompt}}

@dataclass
class PromptResult:
    prompt: str
    accuracy: float

# {{docs-fragment prompt_optimizer}}
@env.task(report=True)
async def prompt_optimizer(
    df_train: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    optimizer_model_config: ModelConfig,
    max_iterations: int,
    concurrency: int,
) -> tuple[str, float]:
    prompt_accuracies: list[PromptResult] = []

    # Send styling + table header immediately
    await flyte.report.log.aio(
        CSS
        + """
    <h2 style="margin-bottom:6px;">📊 Prompt Accuracy Comparison</h2>
    <table class="results-table">
        <thead>
            <tr>
                <th>Prompt</th>
                <th>Accuracy</th>
            </tr>
        </thead>
    <tbody>
    """,
        do_flush=True,
    )

    # Step 1: Evaluate starting prompt and stream row
    with flyte.group(name="baseline_evaluation"):
        starting_accuracy = await evaluate_prompt(
            df_train,
            target_model_config,
            review_model_config,
            concurrency,
        )
        prompt_accuracies.append(
            PromptResult(prompt=target_model_config.prompt, accuracy=starting_accuracy)
        )

        await _log_prompt_row(target_model_config.prompt, starting_accuracy)

    # Step 2: Optimize prompts one by one, streaming after each
    while len(prompt_accuracies) <= max_iterations:
        with flyte.group(name=f"prompt_optimization_step_{len(prompt_accuracies)}"):
            # Prepare prompt scores string for optimizer
            prompt_scores_str = "\n".join(
                f"{result.prompt}: {result.accuracy:.2f}"
                for result in sorted(prompt_accuracies, key=lambda x: x.accuracy)
            )

            optimizer_model_prompt = optimizer_model_config.prompt.format(
                prompt_scores_str=prompt_scores_str
            )
            response = await call_model(
                optimizer_model_config,
                [{"role": "system", "content": optimizer_model_prompt}],
            )
            response = response.strip()

            match = re.search(r"\[\[(.*?)\]\]", response, re.DOTALL)
            if not match:
                print("No new prompt found. Skipping.")
                continue

            new_prompt = match.group(1)
            target_model_config.prompt = new_prompt
            accuracy = await evaluate_prompt(
                df_train,
                target_model_config,
                review_model_config,
                concurrency,
            )
            prompt_accuracies.append(PromptResult(prompt=new_prompt, accuracy=accuracy))

            # Log this new prompt row immediately
            await _log_prompt_row(new_prompt, accuracy)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    # Find best
    best_result = max(prompt_accuracies, key=lambda x: x.accuracy)
    improvement = best_result.accuracy - starting_accuracy

    # Summary
    await flyte.report.log.aio(
        f"""
    <div class="summary-card">
        <h3>🏆 Summary</h3>
        <p><strong>Best Prompt:</strong> {html.escape(best_result.prompt)}</p>
        <p><strong>Best Accuracy:</strong> {best_result.accuracy*100:.2f}%</p>
        <p><strong>Improvement Over Baseline:</strong> {improvement*100:.2f}%</p>
    </div>
    """,
        do_flush=True,
    )

    return best_result.prompt, best_result.accuracy

# {{/docs-fragment prompt_optimizer}}

async def _log_prompt_row(prompt: str, accuracy: float):
    """Helper to log a single prompt/accuracy row to Flyte report."""
    pct = accuracy * 100
    if pct > 80:
        color = "linear-gradient(90deg, #4CAF50, #81C784)"
    elif pct > 60:
        color = "linear-gradient(90deg, #FFC107, #FFD54F)"
    else:
        color = "linear-gradient(90deg, #F44336, #E57373)"

    await flyte.report.log.aio(
        f"""
        <tr>
            <td>{html.escape(prompt)}</td>
            <td>
                {pct:.1f}%
                <div class="accuracy-bar-container">
                    <div class="accuracy-bar" style="width:{pct*1.6}px; background:{color};"></div>
                </div>
            </td>
        </tr>
        """,
        do_flush=True,
    )

# {{docs-fragment auto_prompt_engineering}}
@env.task
async def auto_prompt_engineering(
    csv_file: File | str = "https://dub.sh/geometric-shapes",
    target_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="Solve the given problem about geometric shapes. Think step by step.",
        max_tokens=10000,
    ),
    review_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="""You are a review model tasked with evaluating the correctness of a response to a navigation problem.
The response may contain detailed steps and explanations, but the final answer is the key point.
Please determine if the final answer provided in the response is correct based on the ground truth number.
Respond with 'True' if the final answer is correct and 'False' if it is not.
Only respond with 'True' or 'False', nothing else.

Model Response:
{response}

Ground Truth:
{answer}
""",
    ),
    optimizer_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1",
        hosted_model_uri=None,
        temperature=0.7,
        max_tokens=None,
        prompt="""
<EXPLANATION>
I have some prompts along with their corresponding accuracies.
The prompts are arranged in ascending order based on their accuracy, where higher accuracy indicate better quality.
</EXPLANATION>

<PROMPTS>
{prompt_scores_str}
</PROMPTS>

Each prompt was used together with a problem statement around geometric shapes.

<EXAMPLE>
<QUESTION>
This SVG path element <path d="M 55.57,80.69 L 57.38,65.80 M 57.38,65.80 L 48.90,57.46 M 48.90,57.46 L 45.58,47.78 M 45.58,47.78 L 53.25,36.07 L 66.29,48.90 L 78.69,61.09 L 55.57,80.69"/> draws a Options: (A) circle (B) heptagon (C) hexagon (D) kite (E) line (F) octagon (G) pentagon (H) rectangle (I) sector (J) triangle
</QUESTION>
<ANSWER>
(B)
</ANSWER>
</EXAMPLE>

<TASK>
Write a new prompt that will achieve an accuracy as high as possible and that is different from the old ones.
</TASK>

<RULES>
- It is very important that the new prompt is distinct from ALL the old ones!
- Ensure that you analyse the prompts with a high accuracy and reuse the patterns that worked in the past
- Ensure that you analyse the prompts with a low accuracy and avoid the patterns that didn't worked in the past
- Think out loud before creating the prompt. Describe what has worked in the past and what hasn't. Only then create the new prompt.
- Use all available information like prompt length, formal/informal use of language, etc for your analysis.
- Be creative, try out different ways of prompting the model. You may even come up with hypothetical scenarios that might improve the accuracy.
- You are generating system prompts. This means that there should be no placeholders in the prompt, as they cannot be filled at runtime. Instead focus on general instructions that will help the model to solve the task.
- Write your new prompt in double square brackets. Use only plain text for the prompt text and do not add any markdown (i.e. no hashtags, backticks, quotes, etc).
</RULES>
""",
    ),
    max_iterations: int = 3,
    concurrency: int = 10,
) -> dict[str, Union[str, float]]:
    if isinstance(csv_file, str) and os.path.isfile(csv_file):
        csv_file = await File.from_local(csv_file)

    df_train, df_test = await data_prep(csv_file)

    best_prompt, training_accuracy = await prompt_optimizer(
        df_train,
        target_model_config,
        review_model_config,
        optimizer_model_config,
        max_iterations,
        concurrency,
    )

    with flyte.group(name="test_data_evaluation"):
        baseline_test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
        )

        target_model_config.prompt = best_prompt
        test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
        )

    return {
        "best_prompt": best_prompt,
        "training_accuracy": training_accuracy,
        "baseline_test_accuracy": baseline_test_accuracy,
        "test_accuracy": test_accuracy,
    }

# {{/docs-fragment auto_prompt_engineering}}

# {{docs-fragment main}}
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(auto_prompt_engineering)
    print(run.url)
    run.wait()
# {{/docs-fragment main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/auto_prompt_engineering/optimizer.py*

Then we define a Flyte `trace` to call the model. Unlike a task, a trace runs within the same runtime as the parent process. Since the model is hosted externally, this keeps the call lightweight but still observable.

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "pandas==2.3.1",
#    "pyarrow==21.0.0",
#    "litellm==1.75.0",
# ]
# main = "auto_prompt_engineering"
# params = ""
# ///

# {{docs-fragment env}}
import asyncio
import html
import os
import re
from dataclasses import dataclass
from typing import Optional, Union

import flyte
import flyte.report
import pandas as pd
from flyte.io._file import File

env = flyte.TaskEnvironment(
    name="auto-prompt-engineering",
    image=flyte.Image.from_uv_script(
        __file__, name="auto-prompt-engineering", pre=True
    ),
    secrets=[flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY")],
    resources=flyte.Resources(cpu=1),
)

CSS = """
<style>
    body {
        font-family: 'Segoe UI', Roboto, Arial, sans-serif;
    }
    .results-table {
        border-collapse: collapse;
        width: 100%;
        box-shadow: 0 2px 5px rgba(0,0,0,0.1);
        font-size: 14px;
    }
    .results-table th {
        background: linear-gradient(135deg, #4CAF50, #2E7D32);
        color: white;
        padding: 10px;
        text-align: left;
    }
    .results-table td {
        border: 1px solid #ddd;
        padding: 8px;
        vertical-align: top;
    }
    .results-table tr:nth-child(even) {background-color: #f9f9f9;}
    .results-table tr:hover {background-color: #f1f1f1;}
    .correct {color: #2E7D32; font-weight: bold;}
    .incorrect {color: #C62828; font-weight: bold;}
    .summary-card {
        background: #f9fbfd;
        padding: 14px 18px;
        border-radius: 8px;
        box-shadow: 0 1px 4px rgba(0,0,0,0.05);
        max-width: 800px;
        margin-top: 12px;
    }
    .summary-card h3 {
        margin-top: 0;
        color: #1e88e5;
        font-size: 16px;
    }
</style>
"""

# {{/docs-fragment env}}

# {{docs-fragment data_prep}}
@env.task
async def data_prep(csv_file: File | str) -> tuple[pd.DataFrame, pd.DataFrame]:
    """
    Load Q&A data from a public Google Sheet CSV export URL and split into train/test DataFrames.
    The sheet should have columns: 'input' and 'target'.
    """
    df = pd.read_csv(
        await csv_file.download() if isinstance(csv_file, File) else csv_file
    )

    if "input" not in df.columns or "target" not in df.columns:
        raise ValueError("Sheet must contain 'input' and 'target' columns.")

    # Shuffle rows
    df = df.sample(frac=1, random_state=1234).reset_index(drop=True)

    # Train/Test split
    df_train = df.iloc[:150].rename(columns={"input": "question", "target": "answer"})
    df_test = df.iloc[150:250].rename(columns={"input": "question", "target": "answer"})

    return df_train, df_test

# {{/docs-fragment data_prep}}

# {{docs-fragment model_config}}
@dataclass
class ModelConfig:
    model_name: str
    hosted_model_uri: Optional[str] = None
    temperature: float = 0.0
    max_tokens: Optional[int] = 1000
    timeout: int = 600
    prompt: str = ""

# {{/docs-fragment model_config}}

# {{docs-fragment call_model}}
@flyte.trace
async def call_model(
    model_config: ModelConfig,
    messages: list[dict[str, str]],
) -> str:
    from litellm import acompletion

    response = await acompletion(
        model=model_config.model_name,
        api_base=model_config.hosted_model_uri,
        messages=messages,
        temperature=model_config.temperature,
        timeout=model_config.timeout,
        max_tokens=model_config.max_tokens,
    )
    return response.choices[0].message["content"]

# {{/docs-fragment call_model}}

# {{docs-fragment generate_and_review}}
async def generate_and_review(
    index: int,
    question: str,
    answer: str,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
) -> dict:
    # Generate response from target model
    response = await call_model(
        target_model_config,
        [
            {"role": "system", "content": target_model_config.prompt},
            {"role": "user", "content": question},
        ],
    )

    # Format review prompt with response + answer
    review_messages = [
        {
            "role": "system",
            "content": review_model_config.prompt.format(
                response=response,
                answer=answer,
            ),
        }
    ]
    verdict = await call_model(review_model_config, review_messages)

    # Normalize verdict
    verdict_clean = verdict.strip().lower()
    if verdict_clean not in {"true", "false"}:
        verdict_clean = "not sure"

    return {
        "index": index,
        "model_response": response,
        "is_correct": verdict_clean == "true",
    }

# {{/docs-fragment generate_and_review}}

async def run_grouped_task(
    i,
    index,
    question,
    answer,
    semaphore,
    target_model_config,
    review_model_config,
    counter,
    counter_lock,
):
    async with semaphore:
        with flyte.group(name=f"row-{i}"):
            result = await generate_and_review(
                index,
                question,
                answer,
                target_model_config,
                review_model_config,
            )

            async with counter_lock:
                # Update counters
                counter["processed"] += 1
                if result["is_correct"]:
                    counter["correct"] += 1
                    correct_html = "<span class='correct'>✔ Yes</span>"
                else:
                    correct_html = "<span class='incorrect'>✘ No</span>"

                # Calculate accuracy
                accuracy_pct = (counter["correct"] / counter["processed"]) * 100

            # Update chart
            await flyte.report.log.aio(
                f"<script>updateAccuracy({accuracy_pct});</script>",
                do_flush=True,
            )

            # Add row to table
            await flyte.report.log.aio(
                f"""
                <tr>
                    <td>{html.escape(question)}</td>
                    <td>{html.escape(answer)}</td>
                    <td>{result['model_response']}</td>
                    <td>{correct_html}</td>
                </tr>
                """,
                do_flush=True,
            )

            return result

# {{docs-fragment evaluate_prompt}}
@env.task(report=True)
async def evaluate_prompt(
    df: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    concurrency: int,
) -> float:
    semaphore = asyncio.Semaphore(concurrency)
    counter = {"correct": 0, "processed": 0}
    counter_lock = asyncio.Lock()

    # Write initial HTML structure
    await flyte.report.log.aio(
        CSS
        + """
        <script>
            function updateAccuracy(percent) {
                const bar = document.getElementById('acc-bar');
                const label = document.getElementById('acc-label');
                bar.setAttribute('width', percent * 3);
                label.textContent = `Accuracy: ${percent.toFixed(1)}%`;
            }
        </script>

        <h2 style="margin-top:0;">Model Evaluation Results</h2>
        <h3>Live Accuracy</h3>
        <svg width="320" height="30" id="accuracy-chart">
            <defs>
                <linearGradient id="acc-gradient" x1="0" x2="1" y1="0" y2="0">
                    <stop offset="0%" stop-color="#66bb6a"/>
                    <stop offset="100%" stop-color="#2e7d32"/>
                </linearGradient>
            </defs>
            <rect width="300" height="20" fill="#ddd" rx="5" ry="5"></rect>
            <rect id="acc-bar" width="0" height="20" fill="url(#acc-gradient)" rx="5" ry="5"></rect>
            <text id="acc-label" x="150" y="15" font-size="12" font-weight="bold" text-anchor="middle" fill="#000">
                Accuracy: 0.0%
            </text>
        </svg>

        <table class="results-table">
            <thead>
                <tr>
                    <th>Question</th>
                    <th>Answer</th>
                    <th>Model Response</th>
                    <th>Correct?</th>
                </tr>
            </thead>
            <tbody>
        """,
        do_flush=True,
    )

    # Launch tasks concurrently
    tasks = [
        run_grouped_task(
            i,
            row.Index,
            row.question,
            row.answer,
            semaphore,
            target_model_config,
            review_model_config,
            counter,
            counter_lock,
        )
        for i, row in enumerate(df.itertuples(index=True))
    ]
    await asyncio.gather(*tasks)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    async with counter_lock:
        return (
            (counter["correct"] / counter["processed"]) if counter["processed"] else 0.0
        )

# {{/docs-fragment evaluate_prompt}}

@dataclass
class PromptResult:
    prompt: str
    accuracy: float

# {{docs-fragment prompt_optimizer}}
@env.task(report=True)
async def prompt_optimizer(
    df_train: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    optimizer_model_config: ModelConfig,
    max_iterations: int,
    concurrency: int,
) -> tuple[str, float]:
    prompt_accuracies: list[PromptResult] = []

    # Send styling + table header immediately
    await flyte.report.log.aio(
        CSS
        + """
    <h2 style="margin-bottom:6px;">📊 Prompt Accuracy Comparison</h2>
    <table class="results-table">
        <thead>
            <tr>
                <th>Prompt</th>
                <th>Accuracy</th>
            </tr>
        </thead>
    <tbody>
    """,
        do_flush=True,
    )

    # Step 1: Evaluate starting prompt and stream row
    with flyte.group(name="baseline_evaluation"):
        starting_accuracy = await evaluate_prompt(
            df_train,
            target_model_config,
            review_model_config,
            concurrency,
        )
        prompt_accuracies.append(
            PromptResult(prompt=target_model_config.prompt, accuracy=starting_accuracy)
        )

        await _log_prompt_row(target_model_config.prompt, starting_accuracy)

    # Step 2: Optimize prompts one by one, streaming after each
    while len(prompt_accuracies) <= max_iterations:
        with flyte.group(name=f"prompt_optimization_step_{len(prompt_accuracies)}"):
            # Prepare prompt scores string for optimizer
            prompt_scores_str = "\n".join(
                f"{result.prompt}: {result.accuracy:.2f}"
                for result in sorted(prompt_accuracies, key=lambda x: x.accuracy)
            )

            optimizer_model_prompt = optimizer_model_config.prompt.format(
                prompt_scores_str=prompt_scores_str
            )
            response = await call_model(
                optimizer_model_config,
                [{"role": "system", "content": optimizer_model_prompt}],
            )
            response = response.strip()

            match = re.search(r"\[\[(.*?)\]\]", response, re.DOTALL)
            if not match:
                print("No new prompt found. Skipping.")
                continue

            new_prompt = match.group(1)
            target_model_config.prompt = new_prompt
            accuracy = await evaluate_prompt(
                df_train,
                target_model_config,
                review_model_config,
                concurrency,
            )
            prompt_accuracies.append(PromptResult(prompt=new_prompt, accuracy=accuracy))

            # Log this new prompt row immediately
            await _log_prompt_row(new_prompt, accuracy)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    # Find best
    best_result = max(prompt_accuracies, key=lambda x: x.accuracy)
    improvement = best_result.accuracy - starting_accuracy

    # Summary
    await flyte.report.log.aio(
        f"""
    <div class="summary-card">
        <h3>🏆 Summary</h3>
        <p><strong>Best Prompt:</strong> {html.escape(best_result.prompt)}</p>
        <p><strong>Best Accuracy:</strong> {best_result.accuracy*100:.2f}%</p>
        <p><strong>Improvement Over Baseline:</strong> {improvement*100:.2f}%</p>
    </div>
    """,
        do_flush=True,
    )

    return best_result.prompt, best_result.accuracy

# {{/docs-fragment prompt_optimizer}}

async def _log_prompt_row(prompt: str, accuracy: float):
    """Helper to log a single prompt/accuracy row to Flyte report."""
    pct = accuracy * 100
    if pct > 80:
        color = "linear-gradient(90deg, #4CAF50, #81C784)"
    elif pct > 60:
        color = "linear-gradient(90deg, #FFC107, #FFD54F)"
    else:
        color = "linear-gradient(90deg, #F44336, #E57373)"

    await flyte.report.log.aio(
        f"""
        <tr>
            <td>{html.escape(prompt)}</td>
            <td>
                {pct:.1f}%
                <div class="accuracy-bar-container">
                    <div class="accuracy-bar" style="width:{pct*1.6}px; background:{color};"></div>
                </div>
            </td>
        </tr>
        """,
        do_flush=True,
    )

# {{docs-fragment auto_prompt_engineering}}
@env.task
async def auto_prompt_engineering(
    csv_file: File | str = "https://dub.sh/geometric-shapes",
    target_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="Solve the given problem about geometric shapes. Think step by step.",
        max_tokens=10000,
    ),
    review_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="""You are a review model tasked with evaluating the correctness of a response to a navigation problem.
The response may contain detailed steps and explanations, but the final answer is the key point.
Please determine if the final answer provided in the response is correct based on the ground truth number.
Respond with 'True' if the final answer is correct and 'False' if it is not.
Only respond with 'True' or 'False', nothing else.

Model Response:
{response}

Ground Truth:
{answer}
""",
    ),
    optimizer_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1",
        hosted_model_uri=None,
        temperature=0.7,
        max_tokens=None,
        prompt="""
<EXPLANATION>
I have some prompts along with their corresponding accuracies.
The prompts are arranged in ascending order based on their accuracy, where higher accuracy indicate better quality.
</EXPLANATION>

<PROMPTS>
{prompt_scores_str}
</PROMPTS>

Each prompt was used together with a problem statement around geometric shapes.

<EXAMPLE>
<QUESTION>
This SVG path element <path d="M 55.57,80.69 L 57.38,65.80 M 57.38,65.80 L 48.90,57.46 M 48.90,57.46 L 45.58,47.78 M 45.58,47.78 L 53.25,36.07 L 66.29,48.90 L 78.69,61.09 L 55.57,80.69"/> draws a Options: (A) circle (B) heptagon (C) hexagon (D) kite (E) line (F) octagon (G) pentagon (H) rectangle (I) sector (J) triangle
</QUESTION>
<ANSWER>
(B)
</ANSWER>
</EXAMPLE>

<TASK>
Write a new prompt that will achieve an accuracy as high as possible and that is different from the old ones.
</TASK>

<RULES>
- It is very important that the new prompt is distinct from ALL the old ones!
- Ensure that you analyse the prompts with a high accuracy and reuse the patterns that worked in the past
- Ensure that you analyse the prompts with a low accuracy and avoid the patterns that didn't worked in the past
- Think out loud before creating the prompt. Describe what has worked in the past and what hasn't. Only then create the new prompt.
- Use all available information like prompt length, formal/informal use of language, etc for your analysis.
- Be creative, try out different ways of prompting the model. You may even come up with hypothetical scenarios that might improve the accuracy.
- You are generating system prompts. This means that there should be no placeholders in the prompt, as they cannot be filled at runtime. Instead focus on general instructions that will help the model to solve the task.
- Write your new prompt in double square brackets. Use only plain text for the prompt text and do not add any markdown (i.e. no hashtags, backticks, quotes, etc).
</RULES>
""",
    ),
    max_iterations: int = 3,
    concurrency: int = 10,
) -> dict[str, Union[str, float]]:
    if isinstance(csv_file, str) and os.path.isfile(csv_file):
        csv_file = await File.from_local(csv_file)

    df_train, df_test = await data_prep(csv_file)

    best_prompt, training_accuracy = await prompt_optimizer(
        df_train,
        target_model_config,
        review_model_config,
        optimizer_model_config,
        max_iterations,
        concurrency,
    )

    with flyte.group(name="test_data_evaluation"):
        baseline_test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
        )

        target_model_config.prompt = best_prompt
        test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
        )

    return {
        "best_prompt": best_prompt,
        "training_accuracy": training_accuracy,
        "baseline_test_accuracy": baseline_test_accuracy,
        "test_accuracy": test_accuracy,
    }

# {{/docs-fragment auto_prompt_engineering}}

# {{docs-fragment main}}
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(auto_prompt_engineering)
    print(run.url)
    run.wait()
# {{/docs-fragment main}}
CODE2
import union
from union.app.llm import VLLMApp
from flytekit.extras.accelerators import A10G

Model = union.Artifact(name="gpt-oss-20b")

image = union.ImageSpec(
    name="vllm-gpt-oss",
    builder="union",
    apt_packages=["build-essential", "wget", "gnupg"],
    packages=[
        "union[vllm]==0.1.191b0",
        "--pre vllm==0.10.1+gptoss \
        --extra-index-url https://wheels.vllm.ai/gpt-oss/ \
        --extra-index-url https://download.pytorch.org/whl/nightly/cu128 \
        --index-strategy unsafe-best-match",
    ],
).with_commands(
    [
        "wget https://developer.download.nvidia.com/compute/cuda/repos/debian12/x86_64/cuda-keyring_1.1-1_all.deb",
        "dpkg -i cuda-keyring_1.1-1_all.deb",
        "apt-get update",
        "apt-get install -y cuda-toolkit-12-8",
        "/usr/local/cuda/bin/nvcc --version",
        "chown -R union /root",
        "chown -R union /home",
    ]
)

gpt_oss_app = VLLMApp(
    name="gpt-oss-20b-vllm",
    model=Model.query(),
    model_id="gpt-oss",
    container_image=image,
    requests=union.Resources(cpu="5", mem="26Gi", gpu="1", ephemeral_storage="150Gi"),
    accelerator=A10G,
    scaledown_after=300,
    stream_model=True,
    requires_auth=False,
    extra_args="--async-scheduling",
    env={"VLLM_ATTENTION_BACKEND": "TRITON_ATTN_VLLM_V1"},
)
CODE3
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "pandas==2.3.1",
#    "pyarrow==21.0.0",
#    "litellm==1.75.0",
# ]
# main = "auto_prompt_engineering"
# params = ""
# ///

# {{docs-fragment env}}
import asyncio
import html
import os
import re
from dataclasses import dataclass
from typing import Optional, Union

import flyte
import flyte.report
import pandas as pd
from flyte.io._file import File

env = flyte.TaskEnvironment(
    name="auto-prompt-engineering",
    image=flyte.Image.from_uv_script(
        __file__, name="auto-prompt-engineering", pre=True
    ),
    secrets=[flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY")],
    resources=flyte.Resources(cpu=1),
)

CSS = """
<style>
    body {
        font-family: 'Segoe UI', Roboto, Arial, sans-serif;
    }
    .results-table {
        border-collapse: collapse;
        width: 100%;
        box-shadow: 0 2px 5px rgba(0,0,0,0.1);
        font-size: 14px;
    }
    .results-table th {
        background: linear-gradient(135deg, #4CAF50, #2E7D32);
        color: white;
        padding: 10px;
        text-align: left;
    }
    .results-table td {
        border: 1px solid #ddd;
        padding: 8px;
        vertical-align: top;
    }
    .results-table tr:nth-child(even) {background-color: #f9f9f9;}
    .results-table tr:hover {background-color: #f1f1f1;}
    .correct {color: #2E7D32; font-weight: bold;}
    .incorrect {color: #C62828; font-weight: bold;}
    .summary-card {
        background: #f9fbfd;
        padding: 14px 18px;
        border-radius: 8px;
        box-shadow: 0 1px 4px rgba(0,0,0,0.05);
        max-width: 800px;
        margin-top: 12px;
    }
    .summary-card h3 {
        margin-top: 0;
        color: #1e88e5;
        font-size: 16px;
    }
</style>
"""

# {{/docs-fragment env}}

# {{docs-fragment data_prep}}
@env.task
async def data_prep(csv_file: File | str) -> tuple[pd.DataFrame, pd.DataFrame]:
    """
    Load Q&A data from a public Google Sheet CSV export URL and split into train/test DataFrames.
    The sheet should have columns: 'input' and 'target'.
    """
    df = pd.read_csv(
        await csv_file.download() if isinstance(csv_file, File) else csv_file
    )

    if "input" not in df.columns or "target" not in df.columns:
        raise ValueError("Sheet must contain 'input' and 'target' columns.")

    # Shuffle rows
    df = df.sample(frac=1, random_state=1234).reset_index(drop=True)

    # Train/Test split
    df_train = df.iloc[:150].rename(columns={"input": "question", "target": "answer"})
    df_test = df.iloc[150:250].rename(columns={"input": "question", "target": "answer"})

    return df_train, df_test

# {{/docs-fragment data_prep}}

# {{docs-fragment model_config}}
@dataclass
class ModelConfig:
    model_name: str
    hosted_model_uri: Optional[str] = None
    temperature: float = 0.0
    max_tokens: Optional[int] = 1000
    timeout: int = 600
    prompt: str = ""

# {{/docs-fragment model_config}}

# {{docs-fragment call_model}}
@flyte.trace
async def call_model(
    model_config: ModelConfig,
    messages: list[dict[str, str]],
) -> str:
    from litellm import acompletion

    response = await acompletion(
        model=model_config.model_name,
        api_base=model_config.hosted_model_uri,
        messages=messages,
        temperature=model_config.temperature,
        timeout=model_config.timeout,
        max_tokens=model_config.max_tokens,
    )
    return response.choices[0].message["content"]

# {{/docs-fragment call_model}}

# {{docs-fragment generate_and_review}}
async def generate_and_review(
    index: int,
    question: str,
    answer: str,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
) -> dict:
    # Generate response from target model
    response = await call_model(
        target_model_config,
        [
            {"role": "system", "content": target_model_config.prompt},
            {"role": "user", "content": question},
        ],
    )

    # Format review prompt with response + answer
    review_messages = [
        {
            "role": "system",
            "content": review_model_config.prompt.format(
                response=response,
                answer=answer,
            ),
        }
    ]
    verdict = await call_model(review_model_config, review_messages)

    # Normalize verdict
    verdict_clean = verdict.strip().lower()
    if verdict_clean not in {"true", "false"}:
        verdict_clean = "not sure"

    return {
        "index": index,
        "model_response": response,
        "is_correct": verdict_clean == "true",
    }

# {{/docs-fragment generate_and_review}}

async def run_grouped_task(
    i,
    index,
    question,
    answer,
    semaphore,
    target_model_config,
    review_model_config,
    counter,
    counter_lock,
):
    async with semaphore:
        with flyte.group(name=f"row-{i}"):
            result = await generate_and_review(
                index,
                question,
                answer,
                target_model_config,
                review_model_config,
            )

            async with counter_lock:
                # Update counters
                counter["processed"] += 1
                if result["is_correct"]:
                    counter["correct"] += 1
                    correct_html = "<span class='correct'>✔ Yes</span>"
                else:
                    correct_html = "<span class='incorrect'>✘ No</span>"

                # Calculate accuracy
                accuracy_pct = (counter["correct"] / counter["processed"]) * 100

            # Update chart
            await flyte.report.log.aio(
                f"<script>updateAccuracy({accuracy_pct});</script>",
                do_flush=True,
            )

            # Add row to table
            await flyte.report.log.aio(
                f"""
                <tr>
                    <td>{html.escape(question)}</td>
                    <td>{html.escape(answer)}</td>
                    <td>{result['model_response']}</td>
                    <td>{correct_html}</td>
                </tr>
                """,
                do_flush=True,
            )

            return result

# {{docs-fragment evaluate_prompt}}
@env.task(report=True)
async def evaluate_prompt(
    df: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    concurrency: int,
) -> float:
    semaphore = asyncio.Semaphore(concurrency)
    counter = {"correct": 0, "processed": 0}
    counter_lock = asyncio.Lock()

    # Write initial HTML structure
    await flyte.report.log.aio(
        CSS
        + """
        <script>
            function updateAccuracy(percent) {
                const bar = document.getElementById('acc-bar');
                const label = document.getElementById('acc-label');
                bar.setAttribute('width', percent * 3);
                label.textContent = `Accuracy: ${percent.toFixed(1)}%`;
            }
        </script>

        <h2 style="margin-top:0;">Model Evaluation Results</h2>
        <h3>Live Accuracy</h3>
        <svg width="320" height="30" id="accuracy-chart">
            <defs>
                <linearGradient id="acc-gradient" x1="0" x2="1" y1="0" y2="0">
                    <stop offset="0%" stop-color="#66bb6a"/>
                    <stop offset="100%" stop-color="#2e7d32"/>
                </linearGradient>
            </defs>
            <rect width="300" height="20" fill="#ddd" rx="5" ry="5"></rect>
            <rect id="acc-bar" width="0" height="20" fill="url(#acc-gradient)" rx="5" ry="5"></rect>
            <text id="acc-label" x="150" y="15" font-size="12" font-weight="bold" text-anchor="middle" fill="#000">
                Accuracy: 0.0%
            </text>
        </svg>

        <table class="results-table">
            <thead>
                <tr>
                    <th>Question</th>
                    <th>Answer</th>
                    <th>Model Response</th>
                    <th>Correct?</th>
                </tr>
            </thead>
            <tbody>
        """,
        do_flush=True,
    )

    # Launch tasks concurrently
    tasks = [
        run_grouped_task(
            i,
            row.Index,
            row.question,
            row.answer,
            semaphore,
            target_model_config,
            review_model_config,
            counter,
            counter_lock,
        )
        for i, row in enumerate(df.itertuples(index=True))
    ]
    await asyncio.gather(*tasks)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    async with counter_lock:
        return (
            (counter["correct"] / counter["processed"]) if counter["processed"] else 0.0
        )

# {{/docs-fragment evaluate_prompt}}

@dataclass
class PromptResult:
    prompt: str
    accuracy: float

# {{docs-fragment prompt_optimizer}}
@env.task(report=True)
async def prompt_optimizer(
    df_train: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    optimizer_model_config: ModelConfig,
    max_iterations: int,
    concurrency: int,
) -> tuple[str, float]:
    prompt_accuracies: list[PromptResult] = []

    # Send styling + table header immediately
    await flyte.report.log.aio(
        CSS
        + """
    <h2 style="margin-bottom:6px;">📊 Prompt Accuracy Comparison</h2>
    <table class="results-table">
        <thead>
            <tr>
                <th>Prompt</th>
                <th>Accuracy</th>
            </tr>
        </thead>
    <tbody>
    """,
        do_flush=True,
    )

    # Step 1: Evaluate starting prompt and stream row
    with flyte.group(name="baseline_evaluation"):
        starting_accuracy = await evaluate_prompt(
            df_train,
            target_model_config,
            review_model_config,
            concurrency,
        )
        prompt_accuracies.append(
            PromptResult(prompt=target_model_config.prompt, accuracy=starting_accuracy)
        )

        await _log_prompt_row(target_model_config.prompt, starting_accuracy)

    # Step 2: Optimize prompts one by one, streaming after each
    while len(prompt_accuracies) <= max_iterations:
        with flyte.group(name=f"prompt_optimization_step_{len(prompt_accuracies)}"):
            # Prepare prompt scores string for optimizer
            prompt_scores_str = "\n".join(
                f"{result.prompt}: {result.accuracy:.2f}"
                for result in sorted(prompt_accuracies, key=lambda x: x.accuracy)
            )

            optimizer_model_prompt = optimizer_model_config.prompt.format(
                prompt_scores_str=prompt_scores_str
            )
            response = await call_model(
                optimizer_model_config,
                [{"role": "system", "content": optimizer_model_prompt}],
            )
            response = response.strip()

            match = re.search(r"\[\[(.*?)\]\]", response, re.DOTALL)
            if not match:
                print("No new prompt found. Skipping.")
                continue

            new_prompt = match.group(1)
            target_model_config.prompt = new_prompt
            accuracy = await evaluate_prompt(
                df_train,
                target_model_config,
                review_model_config,
                concurrency,
            )
            prompt_accuracies.append(PromptResult(prompt=new_prompt, accuracy=accuracy))

            # Log this new prompt row immediately
            await _log_prompt_row(new_prompt, accuracy)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    # Find best
    best_result = max(prompt_accuracies, key=lambda x: x.accuracy)
    improvement = best_result.accuracy - starting_accuracy

    # Summary
    await flyte.report.log.aio(
        f"""
    <div class="summary-card">
        <h3>🏆 Summary</h3>
        <p><strong>Best Prompt:</strong> {html.escape(best_result.prompt)}</p>
        <p><strong>Best Accuracy:</strong> {best_result.accuracy*100:.2f}%</p>
        <p><strong>Improvement Over Baseline:</strong> {improvement*100:.2f}%</p>
    </div>
    """,
        do_flush=True,
    )

    return best_result.prompt, best_result.accuracy

# {{/docs-fragment prompt_optimizer}}

async def _log_prompt_row(prompt: str, accuracy: float):
    """Helper to log a single prompt/accuracy row to Flyte report."""
    pct = accuracy * 100
    if pct > 80:
        color = "linear-gradient(90deg, #4CAF50, #81C784)"
    elif pct > 60:
        color = "linear-gradient(90deg, #FFC107, #FFD54F)"
    else:
        color = "linear-gradient(90deg, #F44336, #E57373)"

    await flyte.report.log.aio(
        f"""
        <tr>
            <td>{html.escape(prompt)}</td>
            <td>
                {pct:.1f}%
                <div class="accuracy-bar-container">
                    <div class="accuracy-bar" style="width:{pct*1.6}px; background:{color};"></div>
                </div>
            </td>
        </tr>
        """,
        do_flush=True,
    )

# {{docs-fragment auto_prompt_engineering}}
@env.task
async def auto_prompt_engineering(
    csv_file: File | str = "https://dub.sh/geometric-shapes",
    target_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="Solve the given problem about geometric shapes. Think step by step.",
        max_tokens=10000,
    ),
    review_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="""You are a review model tasked with evaluating the correctness of a response to a navigation problem.
The response may contain detailed steps and explanations, but the final answer is the key point.
Please determine if the final answer provided in the response is correct based on the ground truth number.
Respond with 'True' if the final answer is correct and 'False' if it is not.
Only respond with 'True' or 'False', nothing else.

Model Response:
{response}

Ground Truth:
{answer}
""",
    ),
    optimizer_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1",
        hosted_model_uri=None,
        temperature=0.7,
        max_tokens=None,
        prompt="""
<EXPLANATION>
I have some prompts along with their corresponding accuracies.
The prompts are arranged in ascending order based on their accuracy, where higher accuracy indicate better quality.
</EXPLANATION>

<PROMPTS>
{prompt_scores_str}
</PROMPTS>

Each prompt was used together with a problem statement around geometric shapes.

<EXAMPLE>
<QUESTION>
This SVG path element <path d="M 55.57,80.69 L 57.38,65.80 M 57.38,65.80 L 48.90,57.46 M 48.90,57.46 L 45.58,47.78 M 45.58,47.78 L 53.25,36.07 L 66.29,48.90 L 78.69,61.09 L 55.57,80.69"/> draws a Options: (A) circle (B) heptagon (C) hexagon (D) kite (E) line (F) octagon (G) pentagon (H) rectangle (I) sector (J) triangle
</QUESTION>
<ANSWER>
(B)
</ANSWER>
</EXAMPLE>

<TASK>
Write a new prompt that will achieve an accuracy as high as possible and that is different from the old ones.
</TASK>

<RULES>
- It is very important that the new prompt is distinct from ALL the old ones!
- Ensure that you analyse the prompts with a high accuracy and reuse the patterns that worked in the past
- Ensure that you analyse the prompts with a low accuracy and avoid the patterns that didn't worked in the past
- Think out loud before creating the prompt. Describe what has worked in the past and what hasn't. Only then create the new prompt.
- Use all available information like prompt length, formal/informal use of language, etc for your analysis.
- Be creative, try out different ways of prompting the model. You may even come up with hypothetical scenarios that might improve the accuracy.
- You are generating system prompts. This means that there should be no placeholders in the prompt, as they cannot be filled at runtime. Instead focus on general instructions that will help the model to solve the task.
- Write your new prompt in double square brackets. Use only plain text for the prompt text and do not add any markdown (i.e. no hashtags, backticks, quotes, etc).
</RULES>
""",
    ),
    max_iterations: int = 3,
    concurrency: int = 10,
) -> dict[str, Union[str, float]]:
    if isinstance(csv_file, str) and os.path.isfile(csv_file):
        csv_file = await File.from_local(csv_file)

    df_train, df_test = await data_prep(csv_file)

    best_prompt, training_accuracy = await prompt_optimizer(
        df_train,
        target_model_config,
        review_model_config,
        optimizer_model_config,
        max_iterations,
        concurrency,
    )

    with flyte.group(name="test_data_evaluation"):
        baseline_test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
        )

        target_model_config.prompt = best_prompt
        test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
        )

    return {
        "best_prompt": best_prompt,
        "training_accuracy": training_accuracy,
        "baseline_test_accuracy": baseline_test_accuracy,
        "test_accuracy": test_accuracy,
    }

# {{/docs-fragment auto_prompt_engineering}}

# {{docs-fragment main}}
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(auto_prompt_engineering)
    print(run.url)
    run.wait()
# {{/docs-fragment main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/auto_prompt_engineering/optimizer.py*

## Evaluate prompts

We now define the evaluation process.

Each prompt in the dataset is tested in parallel, but we use a semaphore to control concurrency. A helper function ties together the `generate_and_review` task with an HTML report template. Using `asyncio.gather`, we evaluate multiple prompts at once.

The function measures accuracy as the fraction of responses that match the ground truth. Flyte streams these results to the UI, so you can watch evaluations happen live.

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "pandas==2.3.1",
#    "pyarrow==21.0.0",
#    "litellm==1.75.0",
# ]
# main = "auto_prompt_engineering"
# params = ""
# ///

# {{docs-fragment env}}
import asyncio
import html
import os
import re
from dataclasses import dataclass
from typing import Optional, Union

import flyte
import flyte.report
import pandas as pd
from flyte.io._file import File

env = flyte.TaskEnvironment(
    name="auto-prompt-engineering",
    image=flyte.Image.from_uv_script(
        __file__, name="auto-prompt-engineering", pre=True
    ),
    secrets=[flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY")],
    resources=flyte.Resources(cpu=1),
)

CSS = """
<style>
    body {
        font-family: 'Segoe UI', Roboto, Arial, sans-serif;
    }
    .results-table {
        border-collapse: collapse;
        width: 100%;
        box-shadow: 0 2px 5px rgba(0,0,0,0.1);
        font-size: 14px;
    }
    .results-table th {
        background: linear-gradient(135deg, #4CAF50, #2E7D32);
        color: white;
        padding: 10px;
        text-align: left;
    }
    .results-table td {
        border: 1px solid #ddd;
        padding: 8px;
        vertical-align: top;
    }
    .results-table tr:nth-child(even) {background-color: #f9f9f9;}
    .results-table tr:hover {background-color: #f1f1f1;}
    .correct {color: #2E7D32; font-weight: bold;}
    .incorrect {color: #C62828; font-weight: bold;}
    .summary-card {
        background: #f9fbfd;
        padding: 14px 18px;
        border-radius: 8px;
        box-shadow: 0 1px 4px rgba(0,0,0,0.05);
        max-width: 800px;
        margin-top: 12px;
    }
    .summary-card h3 {
        margin-top: 0;
        color: #1e88e5;
        font-size: 16px;
    }
</style>
"""

# {{/docs-fragment env}}

# {{docs-fragment data_prep}}
@env.task
async def data_prep(csv_file: File | str) -> tuple[pd.DataFrame, pd.DataFrame]:
    """
    Load Q&A data from a public Google Sheet CSV export URL and split into train/test DataFrames.
    The sheet should have columns: 'input' and 'target'.
    """
    df = pd.read_csv(
        await csv_file.download() if isinstance(csv_file, File) else csv_file
    )

    if "input" not in df.columns or "target" not in df.columns:
        raise ValueError("Sheet must contain 'input' and 'target' columns.")

    # Shuffle rows
    df = df.sample(frac=1, random_state=1234).reset_index(drop=True)

    # Train/Test split
    df_train = df.iloc[:150].rename(columns={"input": "question", "target": "answer"})
    df_test = df.iloc[150:250].rename(columns={"input": "question", "target": "answer"})

    return df_train, df_test

# {{/docs-fragment data_prep}}

# {{docs-fragment model_config}}
@dataclass
class ModelConfig:
    model_name: str
    hosted_model_uri: Optional[str] = None
    temperature: float = 0.0
    max_tokens: Optional[int] = 1000
    timeout: int = 600
    prompt: str = ""

# {{/docs-fragment model_config}}

# {{docs-fragment call_model}}
@flyte.trace
async def call_model(
    model_config: ModelConfig,
    messages: list[dict[str, str]],
) -> str:
    from litellm import acompletion

    response = await acompletion(
        model=model_config.model_name,
        api_base=model_config.hosted_model_uri,
        messages=messages,
        temperature=model_config.temperature,
        timeout=model_config.timeout,
        max_tokens=model_config.max_tokens,
    )
    return response.choices[0].message["content"]

# {{/docs-fragment call_model}}

# {{docs-fragment generate_and_review}}
async def generate_and_review(
    index: int,
    question: str,
    answer: str,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
) -> dict:
    # Generate response from target model
    response = await call_model(
        target_model_config,
        [
            {"role": "system", "content": target_model_config.prompt},
            {"role": "user", "content": question},
        ],
    )

    # Format review prompt with response + answer
    review_messages = [
        {
            "role": "system",
            "content": review_model_config.prompt.format(
                response=response,
                answer=answer,
            ),
        }
    ]
    verdict = await call_model(review_model_config, review_messages)

    # Normalize verdict
    verdict_clean = verdict.strip().lower()
    if verdict_clean not in {"true", "false"}:
        verdict_clean = "not sure"

    return {
        "index": index,
        "model_response": response,
        "is_correct": verdict_clean == "true",
    }

# {{/docs-fragment generate_and_review}}

async def run_grouped_task(
    i,
    index,
    question,
    answer,
    semaphore,
    target_model_config,
    review_model_config,
    counter,
    counter_lock,
):
    async with semaphore:
        with flyte.group(name=f"row-{i}"):
            result = await generate_and_review(
                index,
                question,
                answer,
                target_model_config,
                review_model_config,
            )

            async with counter_lock:
                # Update counters
                counter["processed"] += 1
                if result["is_correct"]:
                    counter["correct"] += 1
                    correct_html = "<span class='correct'>✔ Yes</span>"
                else:
                    correct_html = "<span class='incorrect'>✘ No</span>"

                # Calculate accuracy
                accuracy_pct = (counter["correct"] / counter["processed"]) * 100

            # Update chart
            await flyte.report.log.aio(
                f"<script>updateAccuracy({accuracy_pct});</script>",
                do_flush=True,
            )

            # Add row to table
            await flyte.report.log.aio(
                f"""
                <tr>
                    <td>{html.escape(question)}</td>
                    <td>{html.escape(answer)}</td>
                    <td>{result['model_response']}</td>
                    <td>{correct_html}</td>
                </tr>
                """,
                do_flush=True,
            )

            return result

# {{docs-fragment evaluate_prompt}}
@env.task(report=True)
async def evaluate_prompt(
    df: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    concurrency: int,
) -> float:
    semaphore = asyncio.Semaphore(concurrency)
    counter = {"correct": 0, "processed": 0}
    counter_lock = asyncio.Lock()

    # Write initial HTML structure
    await flyte.report.log.aio(
        CSS
        + """
        <script>
            function updateAccuracy(percent) {
                const bar = document.getElementById('acc-bar');
                const label = document.getElementById('acc-label');
                bar.setAttribute('width', percent * 3);
                label.textContent = `Accuracy: ${percent.toFixed(1)}%`;
            }
        </script>

        <h2 style="margin-top:0;">Model Evaluation Results</h2>
        <h3>Live Accuracy</h3>
        <svg width="320" height="30" id="accuracy-chart">
            <defs>
                <linearGradient id="acc-gradient" x1="0" x2="1" y1="0" y2="0">
                    <stop offset="0%" stop-color="#66bb6a"/>
                    <stop offset="100%" stop-color="#2e7d32"/>
                </linearGradient>
            </defs>
            <rect width="300" height="20" fill="#ddd" rx="5" ry="5"></rect>
            <rect id="acc-bar" width="0" height="20" fill="url(#acc-gradient)" rx="5" ry="5"></rect>
            <text id="acc-label" x="150" y="15" font-size="12" font-weight="bold" text-anchor="middle" fill="#000">
                Accuracy: 0.0%
            </text>
        </svg>

        <table class="results-table">
            <thead>
                <tr>
                    <th>Question</th>
                    <th>Answer</th>
                    <th>Model Response</th>
                    <th>Correct?</th>
                </tr>
            </thead>
            <tbody>
        """,
        do_flush=True,
    )

    # Launch tasks concurrently
    tasks = [
        run_grouped_task(
            i,
            row.Index,
            row.question,
            row.answer,
            semaphore,
            target_model_config,
            review_model_config,
            counter,
            counter_lock,
        )
        for i, row in enumerate(df.itertuples(index=True))
    ]
    await asyncio.gather(*tasks)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    async with counter_lock:
        return (
            (counter["correct"] / counter["processed"]) if counter["processed"] else 0.0
        )

# {{/docs-fragment evaluate_prompt}}

@dataclass
class PromptResult:
    prompt: str
    accuracy: float

# {{docs-fragment prompt_optimizer}}
@env.task(report=True)
async def prompt_optimizer(
    df_train: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    optimizer_model_config: ModelConfig,
    max_iterations: int,
    concurrency: int,
) -> tuple[str, float]:
    prompt_accuracies: list[PromptResult] = []

    # Send styling + table header immediately
    await flyte.report.log.aio(
        CSS
        + """
    <h2 style="margin-bottom:6px;">📊 Prompt Accuracy Comparison</h2>
    <table class="results-table">
        <thead>
            <tr>
                <th>Prompt</th>
                <th>Accuracy</th>
            </tr>
        </thead>
    <tbody>
    """,
        do_flush=True,
    )

    # Step 1: Evaluate starting prompt and stream row
    with flyte.group(name="baseline_evaluation"):
        starting_accuracy = await evaluate_prompt(
            df_train,
            target_model_config,
            review_model_config,
            concurrency,
        )
        prompt_accuracies.append(
            PromptResult(prompt=target_model_config.prompt, accuracy=starting_accuracy)
        )

        await _log_prompt_row(target_model_config.prompt, starting_accuracy)

    # Step 2: Optimize prompts one by one, streaming after each
    while len(prompt_accuracies) <= max_iterations:
        with flyte.group(name=f"prompt_optimization_step_{len(prompt_accuracies)}"):
            # Prepare prompt scores string for optimizer
            prompt_scores_str = "\n".join(
                f"{result.prompt}: {result.accuracy:.2f}"
                for result in sorted(prompt_accuracies, key=lambda x: x.accuracy)
            )

            optimizer_model_prompt = optimizer_model_config.prompt.format(
                prompt_scores_str=prompt_scores_str
            )
            response = await call_model(
                optimizer_model_config,
                [{"role": "system", "content": optimizer_model_prompt}],
            )
            response = response.strip()

            match = re.search(r"\[\[(.*?)\]\]", response, re.DOTALL)
            if not match:
                print("No new prompt found. Skipping.")
                continue

            new_prompt = match.group(1)
            target_model_config.prompt = new_prompt
            accuracy = await evaluate_prompt(
                df_train,
                target_model_config,
                review_model_config,
                concurrency,
            )
            prompt_accuracies.append(PromptResult(prompt=new_prompt, accuracy=accuracy))

            # Log this new prompt row immediately
            await _log_prompt_row(new_prompt, accuracy)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    # Find best
    best_result = max(prompt_accuracies, key=lambda x: x.accuracy)
    improvement = best_result.accuracy - starting_accuracy

    # Summary
    await flyte.report.log.aio(
        f"""
    <div class="summary-card">
        <h3>🏆 Summary</h3>
        <p><strong>Best Prompt:</strong> {html.escape(best_result.prompt)}</p>
        <p><strong>Best Accuracy:</strong> {best_result.accuracy*100:.2f}%</p>
        <p><strong>Improvement Over Baseline:</strong> {improvement*100:.2f}%</p>
    </div>
    """,
        do_flush=True,
    )

    return best_result.prompt, best_result.accuracy

# {{/docs-fragment prompt_optimizer}}

async def _log_prompt_row(prompt: str, accuracy: float):
    """Helper to log a single prompt/accuracy row to Flyte report."""
    pct = accuracy * 100
    if pct > 80:
        color = "linear-gradient(90deg, #4CAF50, #81C784)"
    elif pct > 60:
        color = "linear-gradient(90deg, #FFC107, #FFD54F)"
    else:
        color = "linear-gradient(90deg, #F44336, #E57373)"

    await flyte.report.log.aio(
        f"""
        <tr>
            <td>{html.escape(prompt)}</td>
            <td>
                {pct:.1f}%
                <div class="accuracy-bar-container">
                    <div class="accuracy-bar" style="width:{pct*1.6}px; background:{color};"></div>
                </div>
            </td>
        </tr>
        """,
        do_flush=True,
    )

# {{docs-fragment auto_prompt_engineering}}
@env.task
async def auto_prompt_engineering(
    csv_file: File | str = "https://dub.sh/geometric-shapes",
    target_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="Solve the given problem about geometric shapes. Think step by step.",
        max_tokens=10000,
    ),
    review_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="""You are a review model tasked with evaluating the correctness of a response to a navigation problem.
The response may contain detailed steps and explanations, but the final answer is the key point.
Please determine if the final answer provided in the response is correct based on the ground truth number.
Respond with 'True' if the final answer is correct and 'False' if it is not.
Only respond with 'True' or 'False', nothing else.

Model Response:
{response}

Ground Truth:
{answer}
""",
    ),
    optimizer_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1",
        hosted_model_uri=None,
        temperature=0.7,
        max_tokens=None,
        prompt="""
<EXPLANATION>
I have some prompts along with their corresponding accuracies.
The prompts are arranged in ascending order based on their accuracy, where higher accuracy indicate better quality.
</EXPLANATION>

<PROMPTS>
{prompt_scores_str}
</PROMPTS>

Each prompt was used together with a problem statement around geometric shapes.

<EXAMPLE>
<QUESTION>
This SVG path element <path d="M 55.57,80.69 L 57.38,65.80 M 57.38,65.80 L 48.90,57.46 M 48.90,57.46 L 45.58,47.78 M 45.58,47.78 L 53.25,36.07 L 66.29,48.90 L 78.69,61.09 L 55.57,80.69"/> draws a Options: (A) circle (B) heptagon (C) hexagon (D) kite (E) line (F) octagon (G) pentagon (H) rectangle (I) sector (J) triangle
</QUESTION>
<ANSWER>
(B)
</ANSWER>
</EXAMPLE>

<TASK>
Write a new prompt that will achieve an accuracy as high as possible and that is different from the old ones.
</TASK>

<RULES>
- It is very important that the new prompt is distinct from ALL the old ones!
- Ensure that you analyse the prompts with a high accuracy and reuse the patterns that worked in the past
- Ensure that you analyse the prompts with a low accuracy and avoid the patterns that didn't worked in the past
- Think out loud before creating the prompt. Describe what has worked in the past and what hasn't. Only then create the new prompt.
- Use all available information like prompt length, formal/informal use of language, etc for your analysis.
- Be creative, try out different ways of prompting the model. You may even come up with hypothetical scenarios that might improve the accuracy.
- You are generating system prompts. This means that there should be no placeholders in the prompt, as they cannot be filled at runtime. Instead focus on general instructions that will help the model to solve the task.
- Write your new prompt in double square brackets. Use only plain text for the prompt text and do not add any markdown (i.e. no hashtags, backticks, quotes, etc).
</RULES>
""",
    ),
    max_iterations: int = 3,
    concurrency: int = 10,
) -> dict[str, Union[str, float]]:
    if isinstance(csv_file, str) and os.path.isfile(csv_file):
        csv_file = await File.from_local(csv_file)

    df_train, df_test = await data_prep(csv_file)

    best_prompt, training_accuracy = await prompt_optimizer(
        df_train,
        target_model_config,
        review_model_config,
        optimizer_model_config,
        max_iterations,
        concurrency,
    )

    with flyte.group(name="test_data_evaluation"):
        baseline_test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
        )

        target_model_config.prompt = best_prompt
        test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
        )

    return {
        "best_prompt": best_prompt,
        "training_accuracy": training_accuracy,
        "baseline_test_accuracy": baseline_test_accuracy,
        "test_accuracy": test_accuracy,
    }

# {{/docs-fragment auto_prompt_engineering}}

# {{docs-fragment main}}
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(auto_prompt_engineering)
    print(run.url)
    run.wait()
# {{/docs-fragment main}}
CODE4
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "pandas==2.3.1",
#    "pyarrow==21.0.0",
#    "litellm==1.75.0",
# ]
# main = "auto_prompt_engineering"
# params = ""
# ///

# {{docs-fragment env}}
import asyncio
import html
import os
import re
from dataclasses import dataclass
from typing import Optional, Union

import flyte
import flyte.report
import pandas as pd
from flyte.io._file import File

env = flyte.TaskEnvironment(
    name="auto-prompt-engineering",
    image=flyte.Image.from_uv_script(
        __file__, name="auto-prompt-engineering", pre=True
    ),
    secrets=[flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY")],
    resources=flyte.Resources(cpu=1),
)

CSS = """
<style>
    body {
        font-family: 'Segoe UI', Roboto, Arial, sans-serif;
    }
    .results-table {
        border-collapse: collapse;
        width: 100%;
        box-shadow: 0 2px 5px rgba(0,0,0,0.1);
        font-size: 14px;
    }
    .results-table th {
        background: linear-gradient(135deg, #4CAF50, #2E7D32);
        color: white;
        padding: 10px;
        text-align: left;
    }
    .results-table td {
        border: 1px solid #ddd;
        padding: 8px;
        vertical-align: top;
    }
    .results-table tr:nth-child(even) {background-color: #f9f9f9;}
    .results-table tr:hover {background-color: #f1f1f1;}
    .correct {color: #2E7D32; font-weight: bold;}
    .incorrect {color: #C62828; font-weight: bold;}
    .summary-card {
        background: #f9fbfd;
        padding: 14px 18px;
        border-radius: 8px;
        box-shadow: 0 1px 4px rgba(0,0,0,0.05);
        max-width: 800px;
        margin-top: 12px;
    }
    .summary-card h3 {
        margin-top: 0;
        color: #1e88e5;
        font-size: 16px;
    }
</style>
"""

# {{/docs-fragment env}}

# {{docs-fragment data_prep}}
@env.task
async def data_prep(csv_file: File | str) -> tuple[pd.DataFrame, pd.DataFrame]:
    """
    Load Q&A data from a public Google Sheet CSV export URL and split into train/test DataFrames.
    The sheet should have columns: 'input' and 'target'.
    """
    df = pd.read_csv(
        await csv_file.download() if isinstance(csv_file, File) else csv_file
    )

    if "input" not in df.columns or "target" not in df.columns:
        raise ValueError("Sheet must contain 'input' and 'target' columns.")

    # Shuffle rows
    df = df.sample(frac=1, random_state=1234).reset_index(drop=True)

    # Train/Test split
    df_train = df.iloc[:150].rename(columns={"input": "question", "target": "answer"})
    df_test = df.iloc[150:250].rename(columns={"input": "question", "target": "answer"})

    return df_train, df_test

# {{/docs-fragment data_prep}}

# {{docs-fragment model_config}}
@dataclass
class ModelConfig:
    model_name: str
    hosted_model_uri: Optional[str] = None
    temperature: float = 0.0
    max_tokens: Optional[int] = 1000
    timeout: int = 600
    prompt: str = ""

# {{/docs-fragment model_config}}

# {{docs-fragment call_model}}
@flyte.trace
async def call_model(
    model_config: ModelConfig,
    messages: list[dict[str, str]],
) -> str:
    from litellm import acompletion

    response = await acompletion(
        model=model_config.model_name,
        api_base=model_config.hosted_model_uri,
        messages=messages,
        temperature=model_config.temperature,
        timeout=model_config.timeout,
        max_tokens=model_config.max_tokens,
    )
    return response.choices[0].message["content"]

# {{/docs-fragment call_model}}

# {{docs-fragment generate_and_review}}
async def generate_and_review(
    index: int,
    question: str,
    answer: str,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
) -> dict:
    # Generate response from target model
    response = await call_model(
        target_model_config,
        [
            {"role": "system", "content": target_model_config.prompt},
            {"role": "user", "content": question},
        ],
    )

    # Format review prompt with response + answer
    review_messages = [
        {
            "role": "system",
            "content": review_model_config.prompt.format(
                response=response,
                answer=answer,
            ),
        }
    ]
    verdict = await call_model(review_model_config, review_messages)

    # Normalize verdict
    verdict_clean = verdict.strip().lower()
    if verdict_clean not in {"true", "false"}:
        verdict_clean = "not sure"

    return {
        "index": index,
        "model_response": response,
        "is_correct": verdict_clean == "true",
    }

# {{/docs-fragment generate_and_review}}

async def run_grouped_task(
    i,
    index,
    question,
    answer,
    semaphore,
    target_model_config,
    review_model_config,
    counter,
    counter_lock,
):
    async with semaphore:
        with flyte.group(name=f"row-{i}"):
            result = await generate_and_review(
                index,
                question,
                answer,
                target_model_config,
                review_model_config,
            )

            async with counter_lock:
                # Update counters
                counter["processed"] += 1
                if result["is_correct"]:
                    counter["correct"] += 1
                    correct_html = "<span class='correct'>✔ Yes</span>"
                else:
                    correct_html = "<span class='incorrect'>✘ No</span>"

                # Calculate accuracy
                accuracy_pct = (counter["correct"] / counter["processed"]) * 100

            # Update chart
            await flyte.report.log.aio(
                f"<script>updateAccuracy({accuracy_pct});</script>",
                do_flush=True,
            )

            # Add row to table
            await flyte.report.log.aio(
                f"""
                <tr>
                    <td>{html.escape(question)}</td>
                    <td>{html.escape(answer)}</td>
                    <td>{result['model_response']}</td>
                    <td>{correct_html}</td>
                </tr>
                """,
                do_flush=True,
            )

            return result

# {{docs-fragment evaluate_prompt}}
@env.task(report=True)
async def evaluate_prompt(
    df: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    concurrency: int,
) -> float:
    semaphore = asyncio.Semaphore(concurrency)
    counter = {"correct": 0, "processed": 0}
    counter_lock = asyncio.Lock()

    # Write initial HTML structure
    await flyte.report.log.aio(
        CSS
        + """
        <script>
            function updateAccuracy(percent) {
                const bar = document.getElementById('acc-bar');
                const label = document.getElementById('acc-label');
                bar.setAttribute('width', percent * 3);
                label.textContent = `Accuracy: ${percent.toFixed(1)}%`;
            }
        </script>

        <h2 style="margin-top:0;">Model Evaluation Results</h2>
        <h3>Live Accuracy</h3>
        <svg width="320" height="30" id="accuracy-chart">
            <defs>
                <linearGradient id="acc-gradient" x1="0" x2="1" y1="0" y2="0">
                    <stop offset="0%" stop-color="#66bb6a"/>
                    <stop offset="100%" stop-color="#2e7d32"/>
                </linearGradient>
            </defs>
            <rect width="300" height="20" fill="#ddd" rx="5" ry="5"></rect>
            <rect id="acc-bar" width="0" height="20" fill="url(#acc-gradient)" rx="5" ry="5"></rect>
            <text id="acc-label" x="150" y="15" font-size="12" font-weight="bold" text-anchor="middle" fill="#000">
                Accuracy: 0.0%
            </text>
        </svg>

        <table class="results-table">
            <thead>
                <tr>
                    <th>Question</th>
                    <th>Answer</th>
                    <th>Model Response</th>
                    <th>Correct?</th>
                </tr>
            </thead>
            <tbody>
        """,
        do_flush=True,
    )

    # Launch tasks concurrently
    tasks = [
        run_grouped_task(
            i,
            row.Index,
            row.question,
            row.answer,
            semaphore,
            target_model_config,
            review_model_config,
            counter,
            counter_lock,
        )
        for i, row in enumerate(df.itertuples(index=True))
    ]
    await asyncio.gather(*tasks)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    async with counter_lock:
        return (
            (counter["correct"] / counter["processed"]) if counter["processed"] else 0.0
        )

# {{/docs-fragment evaluate_prompt}}

@dataclass
class PromptResult:
    prompt: str
    accuracy: float

# {{docs-fragment prompt_optimizer}}
@env.task(report=True)
async def prompt_optimizer(
    df_train: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    optimizer_model_config: ModelConfig,
    max_iterations: int,
    concurrency: int,
) -> tuple[str, float]:
    prompt_accuracies: list[PromptResult] = []

    # Send styling + table header immediately
    await flyte.report.log.aio(
        CSS
        + """
    <h2 style="margin-bottom:6px;">📊 Prompt Accuracy Comparison</h2>
    <table class="results-table">
        <thead>
            <tr>
                <th>Prompt</th>
                <th>Accuracy</th>
            </tr>
        </thead>
    <tbody>
    """,
        do_flush=True,
    )

    # Step 1: Evaluate starting prompt and stream row
    with flyte.group(name="baseline_evaluation"):
        starting_accuracy = await evaluate_prompt(
            df_train,
            target_model_config,
            review_model_config,
            concurrency,
        )
        prompt_accuracies.append(
            PromptResult(prompt=target_model_config.prompt, accuracy=starting_accuracy)
        )

        await _log_prompt_row(target_model_config.prompt, starting_accuracy)

    # Step 2: Optimize prompts one by one, streaming after each
    while len(prompt_accuracies) <= max_iterations:
        with flyte.group(name=f"prompt_optimization_step_{len(prompt_accuracies)}"):
            # Prepare prompt scores string for optimizer
            prompt_scores_str = "\n".join(
                f"{result.prompt}: {result.accuracy:.2f}"
                for result in sorted(prompt_accuracies, key=lambda x: x.accuracy)
            )

            optimizer_model_prompt = optimizer_model_config.prompt.format(
                prompt_scores_str=prompt_scores_str
            )
            response = await call_model(
                optimizer_model_config,
                [{"role": "system", "content": optimizer_model_prompt}],
            )
            response = response.strip()

            match = re.search(r"\[\[(.*?)\]\]", response, re.DOTALL)
            if not match:
                print("No new prompt found. Skipping.")
                continue

            new_prompt = match.group(1)
            target_model_config.prompt = new_prompt
            accuracy = await evaluate_prompt(
                df_train,
                target_model_config,
                review_model_config,
                concurrency,
            )
            prompt_accuracies.append(PromptResult(prompt=new_prompt, accuracy=accuracy))

            # Log this new prompt row immediately
            await _log_prompt_row(new_prompt, accuracy)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    # Find best
    best_result = max(prompt_accuracies, key=lambda x: x.accuracy)
    improvement = best_result.accuracy - starting_accuracy

    # Summary
    await flyte.report.log.aio(
        f"""
    <div class="summary-card">
        <h3>🏆 Summary</h3>
        <p><strong>Best Prompt:</strong> {html.escape(best_result.prompt)}</p>
        <p><strong>Best Accuracy:</strong> {best_result.accuracy*100:.2f}%</p>
        <p><strong>Improvement Over Baseline:</strong> {improvement*100:.2f}%</p>
    </div>
    """,
        do_flush=True,
    )

    return best_result.prompt, best_result.accuracy

# {{/docs-fragment prompt_optimizer}}

async def _log_prompt_row(prompt: str, accuracy: float):
    """Helper to log a single prompt/accuracy row to Flyte report."""
    pct = accuracy * 100
    if pct > 80:
        color = "linear-gradient(90deg, #4CAF50, #81C784)"
    elif pct > 60:
        color = "linear-gradient(90deg, #FFC107, #FFD54F)"
    else:
        color = "linear-gradient(90deg, #F44336, #E57373)"

    await flyte.report.log.aio(
        f"""
        <tr>
            <td>{html.escape(prompt)}</td>
            <td>
                {pct:.1f}%
                <div class="accuracy-bar-container">
                    <div class="accuracy-bar" style="width:{pct*1.6}px; background:{color};"></div>
                </div>
            </td>
        </tr>
        """,
        do_flush=True,
    )

# {{docs-fragment auto_prompt_engineering}}
@env.task
async def auto_prompt_engineering(
    csv_file: File | str = "https://dub.sh/geometric-shapes",
    target_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="Solve the given problem about geometric shapes. Think step by step.",
        max_tokens=10000,
    ),
    review_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="""You are a review model tasked with evaluating the correctness of a response to a navigation problem.
The response may contain detailed steps and explanations, but the final answer is the key point.
Please determine if the final answer provided in the response is correct based on the ground truth number.
Respond with 'True' if the final answer is correct and 'False' if it is not.
Only respond with 'True' or 'False', nothing else.

Model Response:
{response}

Ground Truth:
{answer}
""",
    ),
    optimizer_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1",
        hosted_model_uri=None,
        temperature=0.7,
        max_tokens=None,
        prompt="""
<EXPLANATION>
I have some prompts along with their corresponding accuracies.
The prompts are arranged in ascending order based on their accuracy, where higher accuracy indicate better quality.
</EXPLANATION>

<PROMPTS>
{prompt_scores_str}
</PROMPTS>

Each prompt was used together with a problem statement around geometric shapes.

<EXAMPLE>
<QUESTION>
This SVG path element <path d="M 55.57,80.69 L 57.38,65.80 M 57.38,65.80 L 48.90,57.46 M 48.90,57.46 L 45.58,47.78 M 45.58,47.78 L 53.25,36.07 L 66.29,48.90 L 78.69,61.09 L 55.57,80.69"/> draws a Options: (A) circle (B) heptagon (C) hexagon (D) kite (E) line (F) octagon (G) pentagon (H) rectangle (I) sector (J) triangle
</QUESTION>
<ANSWER>
(B)
</ANSWER>
</EXAMPLE>

<TASK>
Write a new prompt that will achieve an accuracy as high as possible and that is different from the old ones.
</TASK>

<RULES>
- It is very important that the new prompt is distinct from ALL the old ones!
- Ensure that you analyse the prompts with a high accuracy and reuse the patterns that worked in the past
- Ensure that you analyse the prompts with a low accuracy and avoid the patterns that didn't worked in the past
- Think out loud before creating the prompt. Describe what has worked in the past and what hasn't. Only then create the new prompt.
- Use all available information like prompt length, formal/informal use of language, etc for your analysis.
- Be creative, try out different ways of prompting the model. You may even come up with hypothetical scenarios that might improve the accuracy.
- You are generating system prompts. This means that there should be no placeholders in the prompt, as they cannot be filled at runtime. Instead focus on general instructions that will help the model to solve the task.
- Write your new prompt in double square brackets. Use only plain text for the prompt text and do not add any markdown (i.e. no hashtags, backticks, quotes, etc).
</RULES>
""",
    ),
    max_iterations: int = 3,
    concurrency: int = 10,
) -> dict[str, Union[str, float]]:
    if isinstance(csv_file, str) and os.path.isfile(csv_file):
        csv_file = await File.from_local(csv_file)

    df_train, df_test = await data_prep(csv_file)

    best_prompt, training_accuracy = await prompt_optimizer(
        df_train,
        target_model_config,
        review_model_config,
        optimizer_model_config,
        max_iterations,
        concurrency,
    )

    with flyte.group(name="test_data_evaluation"):
        baseline_test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
        )

        target_model_config.prompt = best_prompt
        test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
        )

    return {
        "best_prompt": best_prompt,
        "training_accuracy": training_accuracy,
        "baseline_test_accuracy": baseline_test_accuracy,
        "test_accuracy": test_accuracy,
    }

# {{/docs-fragment auto_prompt_engineering}}

# {{docs-fragment main}}
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(auto_prompt_engineering)
    print(run.url)
    run.wait()
# {{/docs-fragment main}}
CODE5
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "pandas==2.3.1",
#    "pyarrow==21.0.0",
#    "litellm==1.75.0",
# ]
# main = "auto_prompt_engineering"
# params = ""
# ///

# {{docs-fragment env}}
import asyncio
import html
import os
import re
from dataclasses import dataclass
from typing import Optional, Union

import flyte
import flyte.report
import pandas as pd
from flyte.io._file import File

env = flyte.TaskEnvironment(
    name="auto-prompt-engineering",
    image=flyte.Image.from_uv_script(
        __file__, name="auto-prompt-engineering", pre=True
    ),
    secrets=[flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY")],
    resources=flyte.Resources(cpu=1),
)

CSS = """
<style>
    body {
        font-family: 'Segoe UI', Roboto, Arial, sans-serif;
    }
    .results-table {
        border-collapse: collapse;
        width: 100%;
        box-shadow: 0 2px 5px rgba(0,0,0,0.1);
        font-size: 14px;
    }
    .results-table th {
        background: linear-gradient(135deg, #4CAF50, #2E7D32);
        color: white;
        padding: 10px;
        text-align: left;
    }
    .results-table td {
        border: 1px solid #ddd;
        padding: 8px;
        vertical-align: top;
    }
    .results-table tr:nth-child(even) {background-color: #f9f9f9;}
    .results-table tr:hover {background-color: #f1f1f1;}
    .correct {color: #2E7D32; font-weight: bold;}
    .incorrect {color: #C62828; font-weight: bold;}
    .summary-card {
        background: #f9fbfd;
        padding: 14px 18px;
        border-radius: 8px;
        box-shadow: 0 1px 4px rgba(0,0,0,0.05);
        max-width: 800px;
        margin-top: 12px;
    }
    .summary-card h3 {
        margin-top: 0;
        color: #1e88e5;
        font-size: 16px;
    }
</style>
"""

# {{/docs-fragment env}}

# {{docs-fragment data_prep}}
@env.task
async def data_prep(csv_file: File | str) -> tuple[pd.DataFrame, pd.DataFrame]:
    """
    Load Q&A data from a public Google Sheet CSV export URL and split into train/test DataFrames.
    The sheet should have columns: 'input' and 'target'.
    """
    df = pd.read_csv(
        await csv_file.download() if isinstance(csv_file, File) else csv_file
    )

    if "input" not in df.columns or "target" not in df.columns:
        raise ValueError("Sheet must contain 'input' and 'target' columns.")

    # Shuffle rows
    df = df.sample(frac=1, random_state=1234).reset_index(drop=True)

    # Train/Test split
    df_train = df.iloc[:150].rename(columns={"input": "question", "target": "answer"})
    df_test = df.iloc[150:250].rename(columns={"input": "question", "target": "answer"})

    return df_train, df_test

# {{/docs-fragment data_prep}}

# {{docs-fragment model_config}}
@dataclass
class ModelConfig:
    model_name: str
    hosted_model_uri: Optional[str] = None
    temperature: float = 0.0
    max_tokens: Optional[int] = 1000
    timeout: int = 600
    prompt: str = ""

# {{/docs-fragment model_config}}

# {{docs-fragment call_model}}
@flyte.trace
async def call_model(
    model_config: ModelConfig,
    messages: list[dict[str, str]],
) -> str:
    from litellm import acompletion

    response = await acompletion(
        model=model_config.model_name,
        api_base=model_config.hosted_model_uri,
        messages=messages,
        temperature=model_config.temperature,
        timeout=model_config.timeout,
        max_tokens=model_config.max_tokens,
    )
    return response.choices[0].message["content"]

# {{/docs-fragment call_model}}

# {{docs-fragment generate_and_review}}
async def generate_and_review(
    index: int,
    question: str,
    answer: str,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
) -> dict:
    # Generate response from target model
    response = await call_model(
        target_model_config,
        [
            {"role": "system", "content": target_model_config.prompt},
            {"role": "user", "content": question},
        ],
    )

    # Format review prompt with response + answer
    review_messages = [
        {
            "role": "system",
            "content": review_model_config.prompt.format(
                response=response,
                answer=answer,
            ),
        }
    ]
    verdict = await call_model(review_model_config, review_messages)

    # Normalize verdict
    verdict_clean = verdict.strip().lower()
    if verdict_clean not in {"true", "false"}:
        verdict_clean = "not sure"

    return {
        "index": index,
        "model_response": response,
        "is_correct": verdict_clean == "true",
    }

# {{/docs-fragment generate_and_review}}

async def run_grouped_task(
    i,
    index,
    question,
    answer,
    semaphore,
    target_model_config,
    review_model_config,
    counter,
    counter_lock,
):
    async with semaphore:
        with flyte.group(name=f"row-{i}"):
            result = await generate_and_review(
                index,
                question,
                answer,
                target_model_config,
                review_model_config,
            )

            async with counter_lock:
                # Update counters
                counter["processed"] += 1
                if result["is_correct"]:
                    counter["correct"] += 1
                    correct_html = "<span class='correct'>✔ Yes</span>"
                else:
                    correct_html = "<span class='incorrect'>✘ No</span>"

                # Calculate accuracy
                accuracy_pct = (counter["correct"] / counter["processed"]) * 100

            # Update chart
            await flyte.report.log.aio(
                f"<script>updateAccuracy({accuracy_pct});</script>",
                do_flush=True,
            )

            # Add row to table
            await flyte.report.log.aio(
                f"""
                <tr>
                    <td>{html.escape(question)}</td>
                    <td>{html.escape(answer)}</td>
                    <td>{result['model_response']}</td>
                    <td>{correct_html}</td>
                </tr>
                """,
                do_flush=True,
            )

            return result

# {{docs-fragment evaluate_prompt}}
@env.task(report=True)
async def evaluate_prompt(
    df: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    concurrency: int,
) -> float:
    semaphore = asyncio.Semaphore(concurrency)
    counter = {"correct": 0, "processed": 0}
    counter_lock = asyncio.Lock()

    # Write initial HTML structure
    await flyte.report.log.aio(
        CSS
        + """
        <script>
            function updateAccuracy(percent) {
                const bar = document.getElementById('acc-bar');
                const label = document.getElementById('acc-label');
                bar.setAttribute('width', percent * 3);
                label.textContent = `Accuracy: ${percent.toFixed(1)}%`;
            }
        </script>

        <h2 style="margin-top:0;">Model Evaluation Results</h2>
        <h3>Live Accuracy</h3>
        <svg width="320" height="30" id="accuracy-chart">
            <defs>
                <linearGradient id="acc-gradient" x1="0" x2="1" y1="0" y2="0">
                    <stop offset="0%" stop-color="#66bb6a"/>
                    <stop offset="100%" stop-color="#2e7d32"/>
                </linearGradient>
            </defs>
            <rect width="300" height="20" fill="#ddd" rx="5" ry="5"></rect>
            <rect id="acc-bar" width="0" height="20" fill="url(#acc-gradient)" rx="5" ry="5"></rect>
            <text id="acc-label" x="150" y="15" font-size="12" font-weight="bold" text-anchor="middle" fill="#000">
                Accuracy: 0.0%
            </text>
        </svg>

        <table class="results-table">
            <thead>
                <tr>
                    <th>Question</th>
                    <th>Answer</th>
                    <th>Model Response</th>
                    <th>Correct?</th>
                </tr>
            </thead>
            <tbody>
        """,
        do_flush=True,
    )

    # Launch tasks concurrently
    tasks = [
        run_grouped_task(
            i,
            row.Index,
            row.question,
            row.answer,
            semaphore,
            target_model_config,
            review_model_config,
            counter,
            counter_lock,
        )
        for i, row in enumerate(df.itertuples(index=True))
    ]
    await asyncio.gather(*tasks)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    async with counter_lock:
        return (
            (counter["correct"] / counter["processed"]) if counter["processed"] else 0.0
        )

# {{/docs-fragment evaluate_prompt}}

@dataclass
class PromptResult:
    prompt: str
    accuracy: float

# {{docs-fragment prompt_optimizer}}
@env.task(report=True)
async def prompt_optimizer(
    df_train: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    optimizer_model_config: ModelConfig,
    max_iterations: int,
    concurrency: int,
) -> tuple[str, float]:
    prompt_accuracies: list[PromptResult] = []

    # Send styling + table header immediately
    await flyte.report.log.aio(
        CSS
        + """
    <h2 style="margin-bottom:6px;">📊 Prompt Accuracy Comparison</h2>
    <table class="results-table">
        <thead>
            <tr>
                <th>Prompt</th>
                <th>Accuracy</th>
            </tr>
        </thead>
    <tbody>
    """,
        do_flush=True,
    )

    # Step 1: Evaluate starting prompt and stream row
    with flyte.group(name="baseline_evaluation"):
        starting_accuracy = await evaluate_prompt(
            df_train,
            target_model_config,
            review_model_config,
            concurrency,
        )
        prompt_accuracies.append(
            PromptResult(prompt=target_model_config.prompt, accuracy=starting_accuracy)
        )

        await _log_prompt_row(target_model_config.prompt, starting_accuracy)

    # Step 2: Optimize prompts one by one, streaming after each
    while len(prompt_accuracies) <= max_iterations:
        with flyte.group(name=f"prompt_optimization_step_{len(prompt_accuracies)}"):
            # Prepare prompt scores string for optimizer
            prompt_scores_str = "\n".join(
                f"{result.prompt}: {result.accuracy:.2f}"
                for result in sorted(prompt_accuracies, key=lambda x: x.accuracy)
            )

            optimizer_model_prompt = optimizer_model_config.prompt.format(
                prompt_scores_str=prompt_scores_str
            )
            response = await call_model(
                optimizer_model_config,
                [{"role": "system", "content": optimizer_model_prompt}],
            )
            response = response.strip()

            match = re.search(r"\[\[(.*?)\]\]", response, re.DOTALL)
            if not match:
                print("No new prompt found. Skipping.")
                continue

            new_prompt = match.group(1)
            target_model_config.prompt = new_prompt
            accuracy = await evaluate_prompt(
                df_train,
                target_model_config,
                review_model_config,
                concurrency,
            )
            prompt_accuracies.append(PromptResult(prompt=new_prompt, accuracy=accuracy))

            # Log this new prompt row immediately
            await _log_prompt_row(new_prompt, accuracy)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    # Find best
    best_result = max(prompt_accuracies, key=lambda x: x.accuracy)
    improvement = best_result.accuracy - starting_accuracy

    # Summary
    await flyte.report.log.aio(
        f"""
    <div class="summary-card">
        <h3>🏆 Summary</h3>
        <p><strong>Best Prompt:</strong> {html.escape(best_result.prompt)}</p>
        <p><strong>Best Accuracy:</strong> {best_result.accuracy*100:.2f}%</p>
        <p><strong>Improvement Over Baseline:</strong> {improvement*100:.2f}%</p>
    </div>
    """,
        do_flush=True,
    )

    return best_result.prompt, best_result.accuracy

# {{/docs-fragment prompt_optimizer}}

async def _log_prompt_row(prompt: str, accuracy: float):
    """Helper to log a single prompt/accuracy row to Flyte report."""
    pct = accuracy * 100
    if pct > 80:
        color = "linear-gradient(90deg, #4CAF50, #81C784)"
    elif pct > 60:
        color = "linear-gradient(90deg, #FFC107, #FFD54F)"
    else:
        color = "linear-gradient(90deg, #F44336, #E57373)"

    await flyte.report.log.aio(
        f"""
        <tr>
            <td>{html.escape(prompt)}</td>
            <td>
                {pct:.1f}%
                <div class="accuracy-bar-container">
                    <div class="accuracy-bar" style="width:{pct*1.6}px; background:{color};"></div>
                </div>
            </td>
        </tr>
        """,
        do_flush=True,
    )

# {{docs-fragment auto_prompt_engineering}}
@env.task
async def auto_prompt_engineering(
    csv_file: File | str = "https://dub.sh/geometric-shapes",
    target_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="Solve the given problem about geometric shapes. Think step by step.",
        max_tokens=10000,
    ),
    review_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="""You are a review model tasked with evaluating the correctness of a response to a navigation problem.
The response may contain detailed steps and explanations, but the final answer is the key point.
Please determine if the final answer provided in the response is correct based on the ground truth number.
Respond with 'True' if the final answer is correct and 'False' if it is not.
Only respond with 'True' or 'False', nothing else.

Model Response:
{response}

Ground Truth:
{answer}
""",
    ),
    optimizer_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1",
        hosted_model_uri=None,
        temperature=0.7,
        max_tokens=None,
        prompt="""
<EXPLANATION>
I have some prompts along with their corresponding accuracies.
The prompts are arranged in ascending order based on their accuracy, where higher accuracy indicate better quality.
</EXPLANATION>

<PROMPTS>
{prompt_scores_str}
</PROMPTS>

Each prompt was used together with a problem statement around geometric shapes.

<EXAMPLE>
<QUESTION>
This SVG path element <path d="M 55.57,80.69 L 57.38,65.80 M 57.38,65.80 L 48.90,57.46 M 48.90,57.46 L 45.58,47.78 M 45.58,47.78 L 53.25,36.07 L 66.29,48.90 L 78.69,61.09 L 55.57,80.69"/> draws a Options: (A) circle (B) heptagon (C) hexagon (D) kite (E) line (F) octagon (G) pentagon (H) rectangle (I) sector (J) triangle
</QUESTION>
<ANSWER>
(B)
</ANSWER>
</EXAMPLE>

<TASK>
Write a new prompt that will achieve an accuracy as high as possible and that is different from the old ones.
</TASK>

<RULES>
- It is very important that the new prompt is distinct from ALL the old ones!
- Ensure that you analyse the prompts with a high accuracy and reuse the patterns that worked in the past
- Ensure that you analyse the prompts with a low accuracy and avoid the patterns that didn't worked in the past
- Think out loud before creating the prompt. Describe what has worked in the past and what hasn't. Only then create the new prompt.
- Use all available information like prompt length, formal/informal use of language, etc for your analysis.
- Be creative, try out different ways of prompting the model. You may even come up with hypothetical scenarios that might improve the accuracy.
- You are generating system prompts. This means that there should be no placeholders in the prompt, as they cannot be filled at runtime. Instead focus on general instructions that will help the model to solve the task.
- Write your new prompt in double square brackets. Use only plain text for the prompt text and do not add any markdown (i.e. no hashtags, backticks, quotes, etc).
</RULES>
""",
    ),
    max_iterations: int = 3,
    concurrency: int = 10,
) -> dict[str, Union[str, float]]:
    if isinstance(csv_file, str) and os.path.isfile(csv_file):
        csv_file = await File.from_local(csv_file)

    df_train, df_test = await data_prep(csv_file)

    best_prompt, training_accuracy = await prompt_optimizer(
        df_train,
        target_model_config,
        review_model_config,
        optimizer_model_config,
        max_iterations,
        concurrency,
    )

    with flyte.group(name="test_data_evaluation"):
        baseline_test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
        )

        target_model_config.prompt = best_prompt
        test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
        )

    return {
        "best_prompt": best_prompt,
        "training_accuracy": training_accuracy,
        "baseline_test_accuracy": baseline_test_accuracy,
        "test_accuracy": test_accuracy,
    }

# {{/docs-fragment auto_prompt_engineering}}

# {{docs-fragment main}}
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(auto_prompt_engineering)
    print(run.url)
    run.wait()
# {{/docs-fragment main}}
CODE6
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "pandas==2.3.1",
#    "pyarrow==21.0.0",
#    "litellm==1.75.0",
# ]
# main = "auto_prompt_engineering"
# params = ""
# ///

# {{docs-fragment env}}
import asyncio
import html
import os
import re
from dataclasses import dataclass
from typing import Optional, Union

import flyte
import flyte.report
import pandas as pd
from flyte.io._file import File

env = flyte.TaskEnvironment(
    name="auto-prompt-engineering",
    image=flyte.Image.from_uv_script(
        __file__, name="auto-prompt-engineering", pre=True
    ),
    secrets=[flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY")],
    resources=flyte.Resources(cpu=1),
)

CSS = """
<style>
    body {
        font-family: 'Segoe UI', Roboto, Arial, sans-serif;
    }
    .results-table {
        border-collapse: collapse;
        width: 100%;
        box-shadow: 0 2px 5px rgba(0,0,0,0.1);
        font-size: 14px;
    }
    .results-table th {
        background: linear-gradient(135deg, #4CAF50, #2E7D32);
        color: white;
        padding: 10px;
        text-align: left;
    }
    .results-table td {
        border: 1px solid #ddd;
        padding: 8px;
        vertical-align: top;
    }
    .results-table tr:nth-child(even) {background-color: #f9f9f9;}
    .results-table tr:hover {background-color: #f1f1f1;}
    .correct {color: #2E7D32; font-weight: bold;}
    .incorrect {color: #C62828; font-weight: bold;}
    .summary-card {
        background: #f9fbfd;
        padding: 14px 18px;
        border-radius: 8px;
        box-shadow: 0 1px 4px rgba(0,0,0,0.05);
        max-width: 800px;
        margin-top: 12px;
    }
    .summary-card h3 {
        margin-top: 0;
        color: #1e88e5;
        font-size: 16px;
    }
</style>
"""

# {{/docs-fragment env}}

# {{docs-fragment data_prep}}
@env.task
async def data_prep(csv_file: File | str) -> tuple[pd.DataFrame, pd.DataFrame]:
    """
    Load Q&A data from a public Google Sheet CSV export URL and split into train/test DataFrames.
    The sheet should have columns: 'input' and 'target'.
    """
    df = pd.read_csv(
        await csv_file.download() if isinstance(csv_file, File) else csv_file
    )

    if "input" not in df.columns or "target" not in df.columns:
        raise ValueError("Sheet must contain 'input' and 'target' columns.")

    # Shuffle rows
    df = df.sample(frac=1, random_state=1234).reset_index(drop=True)

    # Train/Test split
    df_train = df.iloc[:150].rename(columns={"input": "question", "target": "answer"})
    df_test = df.iloc[150:250].rename(columns={"input": "question", "target": "answer"})

    return df_train, df_test

# {{/docs-fragment data_prep}}

# {{docs-fragment model_config}}
@dataclass
class ModelConfig:
    model_name: str
    hosted_model_uri: Optional[str] = None
    temperature: float = 0.0
    max_tokens: Optional[int] = 1000
    timeout: int = 600
    prompt: str = ""

# {{/docs-fragment model_config}}

# {{docs-fragment call_model}}
@flyte.trace
async def call_model(
    model_config: ModelConfig,
    messages: list[dict[str, str]],
) -> str:
    from litellm import acompletion

    response = await acompletion(
        model=model_config.model_name,
        api_base=model_config.hosted_model_uri,
        messages=messages,
        temperature=model_config.temperature,
        timeout=model_config.timeout,
        max_tokens=model_config.max_tokens,
    )
    return response.choices[0].message["content"]

# {{/docs-fragment call_model}}

# {{docs-fragment generate_and_review}}
async def generate_and_review(
    index: int,
    question: str,
    answer: str,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
) -> dict:
    # Generate response from target model
    response = await call_model(
        target_model_config,
        [
            {"role": "system", "content": target_model_config.prompt},
            {"role": "user", "content": question},
        ],
    )

    # Format review prompt with response + answer
    review_messages = [
        {
            "role": "system",
            "content": review_model_config.prompt.format(
                response=response,
                answer=answer,
            ),
        }
    ]
    verdict = await call_model(review_model_config, review_messages)

    # Normalize verdict
    verdict_clean = verdict.strip().lower()
    if verdict_clean not in {"true", "false"}:
        verdict_clean = "not sure"

    return {
        "index": index,
        "model_response": response,
        "is_correct": verdict_clean == "true",
    }

# {{/docs-fragment generate_and_review}}

async def run_grouped_task(
    i,
    index,
    question,
    answer,
    semaphore,
    target_model_config,
    review_model_config,
    counter,
    counter_lock,
):
    async with semaphore:
        with flyte.group(name=f"row-{i}"):
            result = await generate_and_review(
                index,
                question,
                answer,
                target_model_config,
                review_model_config,
            )

            async with counter_lock:
                # Update counters
                counter["processed"] += 1
                if result["is_correct"]:
                    counter["correct"] += 1
                    correct_html = "<span class='correct'>✔ Yes</span>"
                else:
                    correct_html = "<span class='incorrect'>✘ No</span>"

                # Calculate accuracy
                accuracy_pct = (counter["correct"] / counter["processed"]) * 100

            # Update chart
            await flyte.report.log.aio(
                f"<script>updateAccuracy({accuracy_pct});</script>",
                do_flush=True,
            )

            # Add row to table
            await flyte.report.log.aio(
                f"""
                <tr>
                    <td>{html.escape(question)}</td>
                    <td>{html.escape(answer)}</td>
                    <td>{result['model_response']}</td>
                    <td>{correct_html}</td>
                </tr>
                """,
                do_flush=True,
            )

            return result

# {{docs-fragment evaluate_prompt}}
@env.task(report=True)
async def evaluate_prompt(
    df: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    concurrency: int,
) -> float:
    semaphore = asyncio.Semaphore(concurrency)
    counter = {"correct": 0, "processed": 0}
    counter_lock = asyncio.Lock()

    # Write initial HTML structure
    await flyte.report.log.aio(
        CSS
        + """
        <script>
            function updateAccuracy(percent) {
                const bar = document.getElementById('acc-bar');
                const label = document.getElementById('acc-label');
                bar.setAttribute('width', percent * 3);
                label.textContent = `Accuracy: ${percent.toFixed(1)}%`;
            }
        </script>

        <h2 style="margin-top:0;">Model Evaluation Results</h2>
        <h3>Live Accuracy</h3>
        <svg width="320" height="30" id="accuracy-chart">
            <defs>
                <linearGradient id="acc-gradient" x1="0" x2="1" y1="0" y2="0">
                    <stop offset="0%" stop-color="#66bb6a"/>
                    <stop offset="100%" stop-color="#2e7d32"/>
                </linearGradient>
            </defs>
            <rect width="300" height="20" fill="#ddd" rx="5" ry="5"></rect>
            <rect id="acc-bar" width="0" height="20" fill="url(#acc-gradient)" rx="5" ry="5"></rect>
            <text id="acc-label" x="150" y="15" font-size="12" font-weight="bold" text-anchor="middle" fill="#000">
                Accuracy: 0.0%
            </text>
        </svg>

        <table class="results-table">
            <thead>
                <tr>
                    <th>Question</th>
                    <th>Answer</th>
                    <th>Model Response</th>
                    <th>Correct?</th>
                </tr>
            </thead>
            <tbody>
        """,
        do_flush=True,
    )

    # Launch tasks concurrently
    tasks = [
        run_grouped_task(
            i,
            row.Index,
            row.question,
            row.answer,
            semaphore,
            target_model_config,
            review_model_config,
            counter,
            counter_lock,
        )
        for i, row in enumerate(df.itertuples(index=True))
    ]
    await asyncio.gather(*tasks)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    async with counter_lock:
        return (
            (counter["correct"] / counter["processed"]) if counter["processed"] else 0.0
        )

# {{/docs-fragment evaluate_prompt}}

@dataclass
class PromptResult:
    prompt: str
    accuracy: float

# {{docs-fragment prompt_optimizer}}
@env.task(report=True)
async def prompt_optimizer(
    df_train: pd.DataFrame,
    target_model_config: ModelConfig,
    review_model_config: ModelConfig,
    optimizer_model_config: ModelConfig,
    max_iterations: int,
    concurrency: int,
) -> tuple[str, float]:
    prompt_accuracies: list[PromptResult] = []

    # Send styling + table header immediately
    await flyte.report.log.aio(
        CSS
        + """
    <h2 style="margin-bottom:6px;">📊 Prompt Accuracy Comparison</h2>
    <table class="results-table">
        <thead>
            <tr>
                <th>Prompt</th>
                <th>Accuracy</th>
            </tr>
        </thead>
    <tbody>
    """,
        do_flush=True,
    )

    # Step 1: Evaluate starting prompt and stream row
    with flyte.group(name="baseline_evaluation"):
        starting_accuracy = await evaluate_prompt(
            df_train,
            target_model_config,
            review_model_config,
            concurrency,
        )
        prompt_accuracies.append(
            PromptResult(prompt=target_model_config.prompt, accuracy=starting_accuracy)
        )

        await _log_prompt_row(target_model_config.prompt, starting_accuracy)

    # Step 2: Optimize prompts one by one, streaming after each
    while len(prompt_accuracies) <= max_iterations:
        with flyte.group(name=f"prompt_optimization_step_{len(prompt_accuracies)}"):
            # Prepare prompt scores string for optimizer
            prompt_scores_str = "\n".join(
                f"{result.prompt}: {result.accuracy:.2f}"
                for result in sorted(prompt_accuracies, key=lambda x: x.accuracy)
            )

            optimizer_model_prompt = optimizer_model_config.prompt.format(
                prompt_scores_str=prompt_scores_str
            )
            response = await call_model(
                optimizer_model_config,
                [{"role": "system", "content": optimizer_model_prompt}],
            )
            response = response.strip()

            match = re.search(r"\[\[(.*?)\]\]", response, re.DOTALL)
            if not match:
                print("No new prompt found. Skipping.")
                continue

            new_prompt = match.group(1)
            target_model_config.prompt = new_prompt
            accuracy = await evaluate_prompt(
                df_train,
                target_model_config,
                review_model_config,
                concurrency,
            )
            prompt_accuracies.append(PromptResult(prompt=new_prompt, accuracy=accuracy))

            # Log this new prompt row immediately
            await _log_prompt_row(new_prompt, accuracy)

    # Close table
    await flyte.report.log.aio("</tbody></table>", do_flush=True)

    # Find best
    best_result = max(prompt_accuracies, key=lambda x: x.accuracy)
    improvement = best_result.accuracy - starting_accuracy

    # Summary
    await flyte.report.log.aio(
        f"""
    <div class="summary-card">
        <h3>🏆 Summary</h3>
        <p><strong>Best Prompt:</strong> {html.escape(best_result.prompt)}</p>
        <p><strong>Best Accuracy:</strong> {best_result.accuracy*100:.2f}%</p>
        <p><strong>Improvement Over Baseline:</strong> {improvement*100:.2f}%</p>
    </div>
    """,
        do_flush=True,
    )

    return best_result.prompt, best_result.accuracy

# {{/docs-fragment prompt_optimizer}}

async def _log_prompt_row(prompt: str, accuracy: float):
    """Helper to log a single prompt/accuracy row to Flyte report."""
    pct = accuracy * 100
    if pct > 80:
        color = "linear-gradient(90deg, #4CAF50, #81C784)"
    elif pct > 60:
        color = "linear-gradient(90deg, #FFC107, #FFD54F)"
    else:
        color = "linear-gradient(90deg, #F44336, #E57373)"

    await flyte.report.log.aio(
        f"""
        <tr>
            <td>{html.escape(prompt)}</td>
            <td>
                {pct:.1f}%
                <div class="accuracy-bar-container">
                    <div class="accuracy-bar" style="width:{pct*1.6}px; background:{color};"></div>
                </div>
            </td>
        </tr>
        """,
        do_flush=True,
    )

# {{docs-fragment auto_prompt_engineering}}
@env.task
async def auto_prompt_engineering(
    csv_file: File | str = "https://dub.sh/geometric-shapes",
    target_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="Solve the given problem about geometric shapes. Think step by step.",
        max_tokens=10000,
    ),
    review_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1-mini",
        hosted_model_uri=None,
        prompt="""You are a review model tasked with evaluating the correctness of a response to a navigation problem.
The response may contain detailed steps and explanations, but the final answer is the key point.
Please determine if the final answer provided in the response is correct based on the ground truth number.
Respond with 'True' if the final answer is correct and 'False' if it is not.
Only respond with 'True' or 'False', nothing else.

Model Response:
{response}

Ground Truth:
{answer}
""",
    ),
    optimizer_model_config: ModelConfig = ModelConfig(
        model_name="gpt-4.1",
        hosted_model_uri=None,
        temperature=0.7,
        max_tokens=None,
        prompt="""
<EXPLANATION>
I have some prompts along with their corresponding accuracies.
The prompts are arranged in ascending order based on their accuracy, where higher accuracy indicate better quality.
</EXPLANATION>

<PROMPTS>
{prompt_scores_str}
</PROMPTS>

Each prompt was used together with a problem statement around geometric shapes.

<EXAMPLE>
<QUESTION>
This SVG path element <path d="M 55.57,80.69 L 57.38,65.80 M 57.38,65.80 L 48.90,57.46 M 48.90,57.46 L 45.58,47.78 M 45.58,47.78 L 53.25,36.07 L 66.29,48.90 L 78.69,61.09 L 55.57,80.69"/> draws a Options: (A) circle (B) heptagon (C) hexagon (D) kite (E) line (F) octagon (G) pentagon (H) rectangle (I) sector (J) triangle
</QUESTION>
<ANSWER>
(B)
</ANSWER>
</EXAMPLE>

<TASK>
Write a new prompt that will achieve an accuracy as high as possible and that is different from the old ones.
</TASK>

<RULES>
- It is very important that the new prompt is distinct from ALL the old ones!
- Ensure that you analyse the prompts with a high accuracy and reuse the patterns that worked in the past
- Ensure that you analyse the prompts with a low accuracy and avoid the patterns that didn't worked in the past
- Think out loud before creating the prompt. Describe what has worked in the past and what hasn't. Only then create the new prompt.
- Use all available information like prompt length, formal/informal use of language, etc for your analysis.
- Be creative, try out different ways of prompting the model. You may even come up with hypothetical scenarios that might improve the accuracy.
- You are generating system prompts. This means that there should be no placeholders in the prompt, as they cannot be filled at runtime. Instead focus on general instructions that will help the model to solve the task.
- Write your new prompt in double square brackets. Use only plain text for the prompt text and do not add any markdown (i.e. no hashtags, backticks, quotes, etc).
</RULES>
""",
    ),
    max_iterations: int = 3,
    concurrency: int = 10,
) -> dict[str, Union[str, float]]:
    if isinstance(csv_file, str) and os.path.isfile(csv_file):
        csv_file = await File.from_local(csv_file)

    df_train, df_test = await data_prep(csv_file)

    best_prompt, training_accuracy = await prompt_optimizer(
        df_train,
        target_model_config,
        review_model_config,
        optimizer_model_config,
        max_iterations,
        concurrency,
    )

    with flyte.group(name="test_data_evaluation"):
        baseline_test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
        )

        target_model_config.prompt = best_prompt
        test_accuracy = await evaluate_prompt(
            df_test,
            target_model_config,
            review_model_config,
            concurrency,
        )

    return {
        "best_prompt": best_prompt,
        "training_accuracy": training_accuracy,
        "baseline_test_accuracy": baseline_test_accuracy,
        "test_accuracy": test_accuracy,
    }

# {{/docs-fragment auto_prompt_engineering}}

# {{docs-fragment main}}
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(auto_prompt_engineering)
    print(run.url)
    run.wait()
# {{/docs-fragment main}}
CODE7
uv run optimizer.py
```

![Execution](https://raw.githubusercontent.com/unionai/unionai-docs-static/main/gifs/tutorials/prompt_engineering/execution.gif)

## Why this matters

Most prompt engineering pipelines start as quick scripts or notebooks. They're fine for experimenting, but they're difficult to scale, reproduce, or debug when things go wrong.

With Flyte 2, we get a more reliable setup:

- Run many evaluations in parallel with **From Flyte 1 to 2 > Asynchronous model > Why we need an async model > True parallelism for all workloads** or **From Flyte 1 to 2 > Asynchronous model > Calling sync tasks from async tasks > The `flyte.map` function: Familiar patterns**.
- Watch accuracy improve in real time and link results back to the exact dataset, prompt, and model config used.
- Resume cleanly after failures without rerunning everything from scratch.
- Reuse the same pattern to tune other parameters like temperature, retrieval depth, or agent strategies, not just prompts.

## Next steps

You now have a working automated prompt engineering pipeline. Here’s how you can take it further:

- **Optimize beyond prompts**: Tune temperature, retrieval strategies, or tool usage just like prompts.
- **Expand evaluation metrics**: Add latency, cost, robustness, or diversity alongside accuracy.
- **Move toward agentic evaluation**: Instead of single prompts, test how agents plan, use tools, and recover from failures in long-horizon tasks.

With this foundation, prompt engineering becomes repeatable, observable, and scalable, ready for production-grade LLM and agent systems.


=== PAGE: https://www.union.ai/docs/v2/union/tutorials/micro-batching ===

<!--

   This file was generated by Makefile.jupyter. Do not edit this file directly.

   The only parts of this file that should be edited are the front matter and the
   comment at the top of the file.

-->

# Batching strategies for efficient scaling

> [!NOTE]
> [View source on GitHub](https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/batching_patterns/batch_processing.ipynb) | [Run in Google Colab](https://colab.research.google.com/github/unionai/unionai-examples/blob/main/v2/tutorials/batching_patterns/batch_processing.ipynb)

This notebook demonstrates a production-ready pattern for processing millions of items efficiently using Flyte v2's advanced features. You'll learn how to build resilient, scalable workflows that can handle failures gracefully and optimize resource consumption.

## Use Case

**The Challenge:** Processing massive datasets (100K to 1M+ items) that require external API calls or long-running operations.

**Real-World Examples:**
- Web scraping large lists of URLs
- Batch inference on millions of data points
- Processing documents through external APIs
- ETL pipelines with rate-limited services
- Data validation against third-party services

**The Problem:** When you have so many inputs that you must:
1. Split them into batches 
2. Submit each batch to an external service and wait for completion
3. Handle failures without losing progress
4. Optimize resource usage across thousands of operations

**Why This Matters:** Without proper batching and checkpointing, a single failure in a million-item workflow could force you to restart from scratch, wasting compute resources and time.

## Goals

**Our Goals:**
1. **Resilience:** Mitigate the impact of batches that take longer or fail
2. **Determinism:** Make operations with external API dependencies predictable and resumable
3. **Efficiency:** Optimize resource consumption through container reuse and parallel processing
4. **Cost Savings:** Minimize wasted compute by checkpointing progress

## Solution Architecture

This example demonstrates a production-ready micro-batching pattern that combines some Union features, including:

### 1. Failure transparency with @flyte.trace
The `@flyte.trace` decorator creates automatic checkpoints:
- **What it does:** Records inputs and outputs of decorated functions
- **Why it matters:** If a task fails, it resumes from the last successful checkpoint
- **Result:** No re-execution of completed work

### 2. Reusable Containers for Efficiency
Instead of creating a new container for each task:
- **Container pools:** Pre-warmed replicas ready to handle work
- **Concurrent processing:** Each replica handles multiple items simultaneously
- **Automatic scaling:** Replicas scale between min/max based on workload
- **Resource optimization:** Dramatically reduced startup overhead

### Key Benefits:
- **Automatic checkpointing** at batch and operation boundaries  
- **Resume from last successful point** on any failure  
- **No wasted compute** - never re-execute completed work  
- **Massive parallelism** - process thousands of batches concurrently  
- **Cost efficient** - container reuse minimizes cold-start overhead  

### Architecture Flow:
```
1M items → Split into 1,000 batches (1K each)
         ↓
    Parallel processing across reusable container pool
         ↓
    Each batch: Submit → Poll → Checkpoint
         ↓
    Aggregate results from all batches
```

### Architecture Diagram

![Micro-batching Architecture](./images/micro-batching.png)

**Diagram shows:**
- Input data split into batches
- Reusable container pool 
- Concurrent processing within each replica 
- Submit and wait phases with `@flyte.trace` checkpoints
- Parallel execution across all batches

## Implementation

### Step 0: Set up the runtime
Prepare the runtime environment for execution

```python
!uv pip install --no-cache --prerelease=allow --upgrade "flyte>=2.0.0b52" "unionai-reuse>=0.1.10"
```

### Step 1: Initialize Flyte Configuration

Configure your connection to the Flyte cluster. This tells Flyte where to run your workflows and how to build container images.

**Configuration Options:**
- `endpoint`: Your Flyte cluster URL
- `org`: Your organization name
- `project`: Project to organize workflows
- `domain`: Environment (development, staging, production)
- `image_builder`: Use "remote" to build images on the cluster (no local Docker required)

```python
# Initialize connection to your Flyte cluster
# Replace these values with your own cluster details

import flyte
flyte.init(
    endpoint="https://<MY_TENANT_HOST>",  # Your Union cluster URL
    org="demo",                                     # Your organization
    project="flytesnacks",                               # Your project name
    domain="development",                           # Environment: development/staging/production
    image_builder="remote",                         # Build images on cluster (no local Docker needed)
    auth_type="DeviceFlow",
)
```

```python
# Import required libraries
import asyncio                          # For concurrent async operations
from datetime import timedelta          # For time-based configuration
from pathlib import Path                # For file path handling
from typing import Dict, List           # For type hints

import flyte                            # Main Flyte SDK
from flyte.remote import Run            # For interacting with remote executions
```

```python
# ============================================
# CONFIGURATION: Adjust these for your use case
# ============================================

# Total number of items to process
# In production, this could be the size of your dataset
NUMBER_OF_INPUTS = 1_000_000  # 1 million items

# Size of each batch
# Considerations for choosing batch size:
# - Larger batches: Fewer tasks, more memory per task
# - Smaller batches: More granular checkpointing, better parallelism
# - Recommendation: Start with 1000-10000 depending on item complexity
BATCH_SIZE = 1000

# Example calculations:
# 1M items ÷ 1K batch = 1,000 parallel batch tasks
# Each batch processes 1K items concurrently within its container
```

### Step 2: Define Container Image

Create a container image specification with all required dependencies.

**Key Dependencies:**
- `flyte>=2.0.0b52`: Flyte v2 SDK for workflow orchestration
- `unionai-reuse>=0.1.10`: Required for Reusable Containers feature

**Note:** You can add any additional packages your tasks need (e.g., `httpx` for API calls, `beautifulsoup4` for web scraping, etc.)

```python
# Define the container image that will run our tasks
# This image will be built once and shared across all task executions
image = (
    flyte.Image.from_debian_base()  # Start with a lightweight Debian base
    .with_pip_packages(
        "flyte>=2.0.0b52",          # Flyte v2 SDK
        "unionai-reuse>=0.1.10"      # Required for reusable containers
        # Add your own dependencies here
    )
)
```

### Step 3: Define Task Environments

Task environments encapsulate the runtime configuration for tasks. We'll create one with **Reusable Containers** for efficient batch processing.

#### What are Reusable Containers?

Instead of creating a new Kubernetes Pod for every task execution, Reusable Containers maintain a pool of pre-warmed replicas that can handle multiple tasks sequentially or concurrently.

**Benefits:**
- **Faster execution:** No container startup overhead (can save 10-60 seconds per task)
- **Better resource utilization:** Containers stay warm and handle multiple items
- **Cost savings:** Especially significant for tasks with expensive initialization
- **Concurrent processing:** Each replica can process multiple items simultaneously

```python
# Create a TaskEnvironment with Reusable Containers for batch processing
batch_env = flyte.TaskEnvironment(
    name="batch_processor",  # Name used for Kubernetes pods: batch_processor-<hash>

    # Resource allocation per replica (per pod)
    resources=flyte.Resources(
        memory="2Gi",  # Memory per replica
        cpu="1"        # CPU cores per replica
    ),

    # Reusable container configuration
    reusable=flyte.ReusePolicy(
        # Number of replica pods to maintain
        # (min, max) - scales between these values based on workload
        replicas=(3, 10),  # Start with 3, scale up to 10 as needed

        # Concurrency: How many items each replica processes simultaneously
        # Higher = more throughput per replica, but more memory usage
        concurrency=5,  # Each pod handles 5 concurrent operations

        # How long idle replicas stay alive before being torn down
        idle_ttl=timedelta(minutes=5),  # Keep warm for 5 minutes
    ),

    # Use the container image we defined earlier
    image=image,
)

# CAPACITY CALCULATION:
# With replicas=(3, 10) and concurrency=5:
# - Minimum concurrent processing: 3 replicas × 5 concurrency = 15 operations
# - Maximum concurrent processing: 10 replicas × 5 concurrency = 50 operations
#
# For 1,000 batches with these settings:
# - Best case: 50 batches processing simultaneously
# - Time to process all: ~20 rounds of execution
```

#### Understanding TaskEnvironment Parameters

**name:** 
- Used as the prefix for Kubernetes pod names
- Example: `batch_processor-abc123`

**resources:** 
- Compute resources allocated to *each replica*
- Set based on your task's memory and CPU needs
- Tip: Monitor actual usage and adjust accordingly

**replicas (min, max):**
- Flyte autoscales between these values based on workload
- More replicas = more parallel processing capacity
- Consider your cluster's capacity and quota limits

**concurrency:**
- Number of async operations each Python process (per pod) handles simultaneously
- This is *within* each replica, not across replicas
- Higher values increase throughput but require more memory
- Best for I/O-bound tasks (API calls, web scraping)
- For CPU-bound tasks, keep this lower (1-2)

**idle_ttl:**
- Time replicas stay alive without active work before shutdown
- Longer TTL = faster subsequent executions, higher resource costs
- Shorter TTL = lower costs, potential startup delays
- Recommendation: 5-15 minutes for typical workloads

**image:**
- The container image specification with all dependencies
- Built once and reused across all task executions

#### Creating the Orchestrator Environment

The orchestrator task coordinates all batch processing but doesn't need container reuse since it only runs once per workflow execution.

```python
# Create a separate environment for the orchestrator task
orchestrator_env = flyte.TaskEnvironment(
    name="orchestrator",

    # depends_on: Use the same image as batch_env (avoids rebuilding)
    # Flyte will build batch_env's image first, then reuse it here.
    # This is also needed as the orchestrator task calls batch tasks that use batch_env.
    depends_on=[batch_env],

    # Orchestrator needs more memory to track all batch executions
    # but doesn't need reusable containers (runs once per workflow)
    resources=flyte.Resources(
        memory="4Gi",  # More memory to manage many parallel batches
        cpu="1"        # Single CPU is sufficient for orchestration
    ),

    image=image,  # Same image, different resource allocation
)
```

#### Why Two Environments?

**Separation of Concerns:**
- **Batch Environment:** Does the heavy lifting (processing items)
  - Needs reusable containers for efficiency
  - Scales horizontally (many replicas)
  - I/O bound operations benefit from concurrency

- **Orchestrator Environment:** Coordinates the workflow
  - Runs once per workflow execution
  - Doesn't need container reuse
  - Needs enough memory to track all batches
  - CPU bound for coordination logic

This separation optimizes both cost and performance.

### Step 4: Define External Service Interactions

These helper functions simulate interactions with external services (APIs, web scraping, etc.). 

```python
async def submit_to_service(request_id: int) -> str:
    """
    Submit a request to an external service and get a job ID.

    This simulates the "submit" phase of a batch job pattern where you:
    1. Send data to an external service
    2. Receive a job/task ID for tracking
    3. Use that ID to poll for completion later

    PRODUCTION IMPLEMENTATION:
    Replace this simulation with your actual service call:

    ```python
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://your-service.com/api/submit",
            json={"request_id": request_id, "data": your_data},
            timeout=30.0
        )
        response.raise_for_status()
        return response.json()["job_id"]
    ```

    Args:
        request_id: Unique identifier for this request

    Returns:
        job_id: Identifier to track this job's progress
    """
    await asyncio.sleep(0.01)  # Simulate network latency
    job_id = f"job_{request_id}"
    return job_id

async def poll_job_status(job_id: str, request_id: int) -> int:
    """
    Poll an external service until a job completes and return results.

    This simulates the "wait" phase where you:
    1. Repeatedly check if a submitted job has completed
    2. Wait between checks to avoid overwhelming the service
    3. Return the final result when ready

    PRODUCTION IMPLEMENTATION:
    Replace this simulation with your actual polling logic:

    ```python
    async with httpx.AsyncClient() as client:
        max_attempts = 60  # 5 minutes with 5-second intervals

        for attempt in range(max_attempts):
            response = await client.get(
                f"https://your-service.com/api/status/{job_id}",
                timeout=10.0
            )
            response.raise_for_status()
            status = response.json()

            if status["state"] == "completed":
                return status["result"]
            elif status["state"] == "failed":
                raise Exception(f"Job {job_id} failed: {status['error']}")

            # Wait before next poll
            await asyncio.sleep(5)

        raise TimeoutError(f"Job {job_id} did not complete in time")
    ```

    Args:
        job_id: The job identifier from submit_to_service
        request_id: Original request ID for logging/tracking

    Returns:
        result: The processed result from the external service
    """
    await asyncio.sleep(0.05)  # Simulate polling + processing time
    return request_id * 2  # Dummy result

# IMPORTANT NOTES:
# 1. Both functions are async - they don't block while waiting
# 2. Add logging for debugging and monitoring
```

### Step 5: Implement the Batch Processing Task

This is the heart of the pattern. The `process_batch` task processes a batch of items with automatic checkpointing using `@flyte.trace`.

#### Key Concepts:

**Two-Phase Processing:**
1. **Submit Phase:** Send all items to external service concurrently
2. **Wait Phase:** Poll for completion of all submitted jobs

**Why @flyte.trace?**
- Creates checkpoints at phase boundaries
- If the task fails during wait phase, it resumes from there (doesn't re-submit)
- Enables forward recovery without re-execution

**Concurrency Pattern:**
- Uses `asyncio.gather()` to process all items in a batch simultaneously
- `return_exceptions=True` prevents one failure from stopping the batch
- Each phase completes fully before moving to the next

```python
@batch_env.task  # This task runs in the reusable container pool
async def process_batch(batch_start: int, batch_end: int) -> List[int]:
    """
    Process a single batch of items with checkpointed phases.

    This function demonstrates the core micro-batching pattern with:
    1. Two-phase processing (submit → wait)
    2. Automatic checkpointing via @flyte.trace
    3. Error handling without stopping the entire batch
    4. Concurrent processing within the batch

    Args:
        batch_start: Starting index for this batch (inclusive)
        batch_end: Ending index for this batch (exclusive)

    Returns:
        List of processed results (or -1 for failed items)

    Example:
        process_batch(0, 1000) processes items 0-999
        process_batch(1000, 2000) processes items 1000-1999
    """

    # ========================================
    # PHASE 1: SUBMIT ALL ITEMS TO SERVICE
    # ========================================
    @flyte.trace  # Creates a checkpoint after this phase completes
    async def submit_phase(items: List[int]) -> Dict[int, str]:
        """
        Submit all items concurrently and collect job IDs.

        This function:
        1. Launches submit_to_service() for ALL items simultaneously
        2. Waits for all submissions to complete with asyncio.gather()
        3. Handles errors gracefully (return_exceptions=True)
        4. Maps each request_id to its job_id (or None if failed)

        Why @flyte.trace here:
        - If this phase succeeds but wait_phase fails, we don't re-submit
        - Checkpointed data includes all job_ids for the wait phase
        - Forward recovery from exact failure point

        """

        job_ids = await asyncio.gather(
            *(submit_to_service(request_id=x) for x in items),
            return_exceptions=True  # Don't stop on individual failures
        )

        # Map request IDs to job IDs (or None for failures)
        job_mapping = {}
        for request_id, job_id in zip(items, job_ids):
            if isinstance(job_id, Exception):
                print(f"[ERROR] Submit failed for {request_id}: {job_id}")
                job_mapping[request_id] = None  # Mark as failed
            else:
                job_mapping[request_id] = job_id

        return job_mapping

    # ========================================
    # PHASE 2: WAIT FOR ALL JOBS TO COMPLETE
    # ========================================
    @flyte.trace  # Creates another checkpoint after this phase completes
    async def wait_phase(job_mapping: Dict[int, str]) -> List[int]:
        """
        Poll all submitted jobs until completion.

        This function:
        1. Takes the checkpointed job_mapping from submit_phase
        2. Polls all jobs concurrently
        3. Handles polling errors gracefully
        4. Returns final results

        WHY @flyte.trace HERE:
        - If polling fails partway through, we resume with cached job_mapping
        - Don't re-submit jobs that were already submitted
        - Each successful poll is checkpointed

        ERROR HANDLING:
        - Jobs that failed in submit_phase (None) are skipped
        - Polling failures are caught and marked as -1
        - The batch continues even if some items fail
        """
        # Poll ALL jobs concurrently
        results = await asyncio.gather(
            *(
                poll_job_status(job_id=job_id, request_id=request_id)
                if job_id is not None  # Only poll successfully submitted jobs
                else asyncio.sleep(0)   # Skip failed submissions
                for request_id, job_id in job_mapping.items()
            ),
            return_exceptions=True  # Don't stop on individual failures
        )

        # Process results and handle errors
        processed_results = []
        for request_id, result in zip(job_mapping.keys(), results):
            if isinstance(result, Exception):
                print(f"[ERROR] Wait failed for {request_id}: {result}")
                processed_results.append(-1)  # Mark as failed
            else:
                processed_results.append(result)

        return processed_results

    # ========================================
    # EXECUTE BOTH PHASES SEQUENTIALLY
    # ========================================
    # Create the list of items for this batch
    items = list(range(batch_start, batch_end))

    # Phase 1: Submit all items and get job IDs (checkpointed)
    job_mapping = await submit_phase(items)

    # Phase 2: Wait for all jobs to complete (checkpointed)
    results = await wait_phase(job_mapping)

    # Log batch completion stats
    successful = len([r for r in results if r != -1])
    print(f"Batch {batch_start}-{batch_end}: {successful}/{len(results)} successful")

    return results

# ========================================
# CHECKPOINT & RECOVERY BEHAVIOR
# ========================================
#
# Scenario 1: Task fails during submit_phase
# → Retries resume from last checkpoint
#
# Scenario 2: Task fails after submit_phase completes
# → Resumes directly to wait_phase with cached job_mapping
# → No re-submissions!
#
# Scenario 3: Task fails during wait_phase
# → Resumes wait_phase with cached job_mapping
# → Already-polled jobs are not polled again (Flyte makes operations idempotent)

```

#### Understanding @flyte.trace

**Why use it for both phases:**
- Submit phase checkpoint = "These jobs were submitted successfully"
- Wait phase checkpoint = "These results were retrieved successfully"
- Without it: A failure in submit or wait phase would re-submit or re-poll everything

**Best Practices:**
- Use `@flyte.trace` for non-deterministic operations (API calls, random operations)
- Don't use it for pure, deterministic functions (unnecessary overhead)
- Ensure traced functions are idempotent when possible
- Keep traced function signatures simple (serializable inputs/outputs)

See the [Traces](/docs/v2/byoc//user-guide/task-programming/traces/) docs for more details on how it works

### Step 6: Implement the Orchestrator Workflow

The orchestrator is the top-level task that:
1. Splits the total workload into batches
2. Launches all batches in parallel
3. Aggregates results from all batches
4. Reports overall statistics

**This is where the magic happens:** All batches run concurrently, limited only by your reusable container pool configuration.

```python
@orchestrator_env.task  # Runs in the orchestrator environment (no reuse)
async def microbatch_workflow(
    total_items: int = NUMBER_OF_INPUTS,
    batch_size: int = BATCH_SIZE,
) -> List[int]:
    """
    Main task orchestrating the entire micro-batching process.

    This task:
    1. Calculates optimal batch distribution
    2. Launches all batch tasks in parallel
    3. Aggregates results from completed batches
    4. Provides comprehensive execution statistics

    Args:
        total_items: Total number of items to process (default: 1M)
        batch_size: Number of items per batch (default: 1K)

    Returns:
        Aggregated results from all batches (list of processed values)

    Execution Flow:
        1M items → 1,000 batches → Parallel execution → Aggregated results

    Resource Usage:
        - This task: 4Gi memory, 1 CPU (orchestration only)
        - Each batch task: 2Gi memory, 1 CPU (from batch_env)
        - Reusable containers handle actual processing
    """

    # ========================================
    # STEP 1: CALCULATE BATCH DISTRIBUTION
    # ========================================
    # Split total items into batch ranges: [(0, 1000), (1000, 2000), ...]
    batches = [
        (start, min(start + batch_size, total_items))
        for start in range(0, total_items, batch_size)
    ]

    print(f"Processing {total_items:,} items in {len(batches):,} batches of size {batch_size:,}")
    print(f"Expected parallelism: {batch_env.reusable.replicas[0]}-{batch_env.reusable.replicas[1]} replicas")
    print(f"Concurrency per replica: {batch_env.reusable.concurrency}")
    print(f"Max simultaneous batches: {batch_env.reusable.replicas[1] * batch_env.reusable.concurrency}")

    # ========================================
    # STEP 2: LAUNCH ALL BATCHES IN PARALLEL
    # ========================================
    # This is the key to massive parallelism:
    # - Creates as many async tasks as concurrent operations your API supports
    # - All execute concurrently within container pool limits
    # - Reusable containers handle the workload efficiently
    # - return_exceptions=True prevents one batch failure from stopping all

    print(f"\n Launching {len(batches):,} parallel batch tasks...")

    # Rate limiter to control API throughput
    max_concurrent_batches = 10  # Adjust based on API rate limits
    semaphore = asyncio.Semaphore(max_concurrent_batches)

    async def rate_limited_batch(start: int, end: int):
        """Wrapper to enforce rate limiting on batch processing."""
        async with semaphore:
            return await process_batch(batch_start=start, batch_end=end)

    batch_results = await asyncio.gather(
        *(rate_limited_batch(start, end) for start, end in batches),
        return_exceptions=True  # Isolated failure handling per batch
    )
    # ========================================
    # STEP 3: AGGREGATE RESULTS & STATISTICS
    # ========================================
    all_results = []
    failed_batches = 0
    failed_items = 0

    for i, batch_result in enumerate(batch_results):
        if isinstance(batch_result, Exception):
            # Entire batch failed (task-level failure)
            print(f"[ERROR] Batch {i} failed completely: {batch_result}")
            failed_batches += 1
        else:
            # Batch completed, but individual items may have failed
            all_results.extend(batch_result)
            failed_items += len([r for r in batch_result if r == -1])

    # Calculate final statistics
    success_count = len([r for r in all_results if r != -1])
    total_processed = len(all_results)

    # ========================================
    # STEP 4: REPORT EXECUTION SUMMARY
    # ========================================
    print(f"\n{'=' * 60}")
    print(f" Execution summary")
    print(f"{'=' * 60}")
    print(f"Total items requested:    {total_items:,}")
    print(f"Total batches:            {len(batches):,}")
    print(f"Batch size:               {batch_size:,}")
    print(f"")
    print(f" Successful items:       {success_count:,}")
    print(f" Failed items:           {failed_items:,}")
    print(f" Failed batches:         {failed_batches}")
    print(f"")
    print(f" Success rate:           {success_count / total_items * 100:.2f}%")
    print(f" Items processed:        {total_processed:,} / {total_items:,}")
    print(f"{'=' * 60}\n")

    return all_results

# ========================================
# EXECUTION BEHAVIOR & OPTIMIZATION
# ========================================
#
# Parallel Execution Pattern:
# ┌─────────────────────────────────────────────────┐
# │ Orchestrator Task (1 pod, 4Gi, 1 CPU)         │
# │                                                 │
# │ Launches 1,000 process_batch() invocations     │
# └─────────────────┬───────────────────────────────┘
#                   │
#           ┌───────┴────────┐
#           ▼                ▼
#   ┌──────────────┐  ┌──────────────┐
#   │ Replica 1    │  │ Replica 2    │  ... up to 10 replicas
#   │ 2Gi, 1 CPU   │  │ 2Gi, 1 CPU   │
#   │              │  │              │
#   │ Concurrency: │  │ Concurrency: │
#   │ 5 batches    │  │ 5 batches    │
#   └──────────────┘  └──────────────┘
#
# With 10 replicas × 5 concurrency = 50 batches processing simultaneously
# Time to complete 1,000 batches ≈ 1,000 / 50 = 20 waves
#
# Optimization Tips:
# 1. Increase replicas for more parallelism (if cluster allows)
# 2. Adjust concurrency based on task I/O vs CPU profile
# 3. Tune batch_size to balance granularity vs overhead
# 4. Monitor actual execution to find bottlenecks
# 5. Use Flyte UI to visualize execution patterns
```

### Step 7: Execute the Workflow

Now let's run the entire workflow remotely on your Union cluster.

**Execution Options:**
- **Remote execution** (shown below): Runs on the Union cluster
- **Local execution**: Use `flyte.with_runcontext(mode="local").run()` for testing

**What happens during execution:**
1. Flyte builds the container image (if needed)
2. Creates the orchestrator pod
3. Orchestrator calculates batches and launches batch tasks
4. Reusable container pool starts spinning up (min: 3 replicas in this example)
5. Batches are distributed across available replicas
6. Pool scales up to max replicas (10 in this example) as needed
7. Results are aggregated and returned

```python
if __name__ == "__main__":
    print("=" * 60)
    print(" STARTING MICRO-BATCHING WORKFLOW")
    print("=" * 60)
    print(f"Total items to process: {NUMBER_OF_INPUTS:,}")
    print(f"Batch size: {BATCH_SIZE:,}")
    print(f"Expected batches: {NUMBER_OF_INPUTS // BATCH_SIZE:,}")
    print("=" * 60)
    print()

    # Launch the workflow remotely (runs on Flyte cluster)
    # The 'await' is needed because flyte.run.aio() is async
    r = await flyte.run.aio(microbatch_workflow)

    # Print execution details
    print(f"\n{'=' * 60}")
    print(f" EXECUTION STARTED")
    print(f"{'=' * 60}")
    # print(f"Run name: {r.name}")  # Internal run identifier
    print(f"🔗 Execution URL: {r.url}")
    print(f"\n💡 Visit the URL above to:")
    print(f"   • View the execution graph and task timeline")
    print(f"   • Monitor progress in real-time")
    print(f"   • See trace checkpoints in action")
    print(f"   • Inspect logs for each batch")
    print(f"   • Analyze resource utilization")
    print(f"{'=' * 60}\n")

# ========================================
# MONITORING AND DEBUGGING TIPS
# ========================================
#
# 1. View Execution in UI:
#    - Click the execution URL printed above
#    - See visual graph of all batch tasks
#    - Monitor which batches are running/completed/failed
#
# 2. Check Logs:
#    - Click on individual batch tasks in the graph
#    - View stdout/stderr for debugging
#    - See checkpoint/recovery messages
#
# 3. Resource Utilization:
#    - Navigate to Resources tab in UI
#    - Monitor CPU/memory usage per task
#    - Identify bottlenecks or over-provisioning
#
# 4. Trace Visualization:
#    - Expand batch tasks to see trace checkpoints
#    - Verify submit_phase and wait_phase separately
#    - Understand recovery points on failures
#
# 5. Performance Analysis:
#    - Check task durations in timeline view
#    - Identify slow batches or stragglers
#    - Optimize batch_size or concurrency based on results
```

On execution, this is what this example looks like at the Kubernetes level:

![](./images/reusable-containers-k8s.png)

This is, 10 replicas (as defined in the `TaskEnvironment`) and the driver Pod that runs the parent task (`a0`). [Learn more about the parent task](/docs/v2/byoc//user-guide/considerations/#driver-pod-requirements).

## Batch Size Selection

**Finding the optimal batch size:**
- **Too small:** More overhead from task management, less efficient
- **Too large:** Longer recovery time on failures, higher memory usage

**Factors to consider:**
- Item processing time (longer = larger batches)
- Memory consumption per item (higher = smaller batches)
- Failure tolerance (critical = smaller batches for faster recovery)
- Total workload size (larger total = can use larger batches)

Read the [Optimization strategies](/docs/v2/byoc//user-guide/run-scaling/scale-your-workflows/#2-batch-workloads-to-reduce-overhead) page to understand the overheads associated with an execution and how to choose the appropiate batch size.

## Summary

This notebook demonstrated a production-ready micro-batching pattern for Flyte v2 that combines:

1. **Reusable Containers** for efficiency
2. **@flyte.trace** for checkpointing and recovery
3. **Massive parallelism** via async/await
4. **Robust error handling** for resilience

**Key Takeaways:**
- Use `@flyte.trace` for non-deterministic operations
- Monitor resource usage and optimize incrementally
- Choose the right pattern for your specific use case

**Next Steps:**
- Adapt this pattern to your specific use case
- Replace mock functions with real API calls
- Test with your actual dataset
- Monitor and optimize based on production metrics


=== PAGE: https://www.union.ai/docs/v2/union/tutorials/deep-research ===

# Deep research

> [!NOTE]
> Code available [here](https://github.com/unionai/unionai-examples/tree/main/v2/tutorials/deep_research_agent); based on work by [Together AI](https://github.com/togethercomputer/open_deep_research).

This example demonstrates how to build an agentic workflow for deep research—a multi-step reasoning system that mirrors how a human researcher explores, analyzes, and synthesizes information from the web.

Deep research refers to the iterative process of thoroughly investigating a topic: identifying relevant sources, evaluating their usefulness, refining the research direction, and ultimately producing a well-structured summary or report. It's a long-running task that requires the agent to reason over time, adapt its strategy, and chain multiple steps together, making it an ideal fit for an agentic architecture.

In this example, we use:

- [Tavily](https://www.tavily.com/) to search for and retrieve high-quality online resources.
- [LiteLLM](https://litellm.ai/) to route LLM calls that perform reasoning, evaluation, and synthesis.

The agent executes a multi-step trajectory:

- Parallel search across multiple queries.
- Evaluation of retrieved results.
- Adaptive iteration: If results are insufficient, it formulates new research queries and repeats the search-evaluate cycle.
- Synthesis: After a fixed number of iterations, it produces a comprehensive research report.

What makes this workflow compelling is its dynamic, evolving nature. The agent isn't just following a fixed plan; it's making decisions in context, using multiple prompts and reasoning steps to steer the process.

Flyte is uniquely well-suited for this kind of system. It provides:

- Structured composition of dynamic reasoning steps
- Built-in parallelism for faster search and evaluation
- Traceability and observability into each step and iteration
- Scalability for long-running or compute-intensive workloads

![Result](https://raw.githubusercontent.com/unionai/unionai-docs-static/main/gifs/tutorials/deep-research/result.gif)

Throughout this guide, we'll show how to design this workflow using the Flyte SDK, and how to unlock the full potential of agentic development with tools you already know and trust.

## Setting up the environment

Let's begin by setting up the task environment. We define the following components:

- Secrets for Together and Tavily API keys
- A custom image with required Python packages and apt dependencies (`pandoc`, `texlive-xetex`)
- External YAML file with all LLM prompts baked into the container

```
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "pydantic==2.11.5",
#    "litellm==1.72.2",
#    "tavily-python==0.7.5",
#    "together==1.5.24",
#    "markdown==3.8.2",
#    "pymdown-extensions==10.16.1",
# ]
# main = "main"
# params = ""
# ///

# {{docs-fragment env}}
import asyncio
import json
from pathlib import Path

import flyte
import yaml
from flyte.io._file import File
from libs.utils.data_types import (
    DeepResearchResult,
    DeepResearchResults,
    ResearchPlan,
    SourceList,
)
from libs.utils.generation import generate_html, generate_toc_image
from libs.utils.llms import asingle_shot_llm_call
from libs.utils.log import AgentLogger
from libs.utils.tavily_search import atavily_search_results

TIME_LIMIT_MULTIPLIER = 5
MAX_COMPLETION_TOKENS = 4096

logging = AgentLogger("together.open_deep_research")

env = flyte.TaskEnvironment(
    name="deep-researcher",
    secrets=[
        flyte.Secret(key="together_api_key", as_env_var="TOGETHER_API_KEY"),
        flyte.Secret(key="tavily_api_key", as_env_var="TAVILY_API_KEY"),
    ],
    image=flyte.Image.from_uv_script(__file__, name="deep-research-agent", pre=True)
    .with_apt_packages("pandoc", "texlive-xetex")
    .with_source_file(Path("prompts.yaml"), "/root"),
    resources=flyte.Resources(cpu=1),
)
# {{/docs-fragment env}}

# {{docs-fragment generate_research_queries}}
@env.task
async def generate_research_queries(
    topic: str,
    planning_model: str,
    json_model: str,
    prompts_file: File,
) -> list[str]:
    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    prompts = yaml.safe_load(yaml_contents)
    PLANNING_PROMPT = prompts["planning_prompt"]

    plan = ""
    logging.info(f"\n\nGenerated deep research plan for topic: {topic}\n\nPlan:")
    async for chunk in asingle_shot_llm_call(
        model=planning_model,
        system_prompt=PLANNING_PROMPT,
        message=f"Research Topic: {topic}",
        response_format=None,
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        plan += chunk
        print(chunk, end="", flush=True)

    SEARCH_PROMPT = prompts["plan_parsing_prompt"]

    response_json = ""
    async for chunk in asingle_shot_llm_call(
        model=json_model,
        system_prompt=SEARCH_PROMPT,
        message=f"Plan to be parsed: {plan}",
        response_format={
            "type": "json_object",
            "schema": ResearchPlan.model_json_schema(),
        },
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        response_json += chunk

    plan = json.loads(response_json)
    return plan["queries"]
# {{/docs-fragment generate_research_queries}}

async def _summarize_content_async(
    raw_content: str,
    query: str,
    prompt: str,
    summarization_model: str,
) -> str:
    """Summarize content asynchronously using the LLM"""
    logging.info("Summarizing content asynchronously using the LLM")

    result = ""
    async for chunk in asingle_shot_llm_call(
        model=summarization_model,
        system_prompt=prompt,
        message=f"<Raw Content>{raw_content}</Raw Content>\n\n<Research Topic>{query}</Research Topic>",
        response_format=None,
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        result += chunk
    return result

# {{docs-fragment search_and_summarize}}
@env.task
async def search_and_summarize(
    query: str,
    prompts_file: File,
    summarization_model: str,
) -> DeepResearchResults:
    """Perform search for a single query"""

    if len(query) > 400:
        # NOTE: we are truncating the query to 400 characters to avoid Tavily Search issues
        query = query[:400]
        logging.info(f"Truncated query to 400 characters: {query}")

    response = await atavily_search_results(query)

    logging.info("Tavily Search Called.")

    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    prompts = yaml.safe_load(yaml_contents)
    RAW_CONTENT_SUMMARIZER_PROMPT = prompts["raw_content_summarizer_prompt"]

    with flyte.group("summarize-content"):
        # Create tasks for summarization
        summarization_tasks = []
        result_info = []
        for result in response.results:
            if result.raw_content is None:
                continue

            task = _summarize_content_async(
                result.raw_content,
                query,
                RAW_CONTENT_SUMMARIZER_PROMPT,
                summarization_model,
            )
            summarization_tasks.append(task)
            result_info.append(result)

        # Use return_exceptions=True to prevent exceptions from propagating
        summarized_contents = await asyncio.gather(
            *summarization_tasks, return_exceptions=True
        )

    # Filter out exceptions
    summarized_contents = [
        result for result in summarized_contents if not isinstance(result, Exception)
    ]

    formatted_results = []
    for result, summarized_content in zip(result_info, summarized_contents):
        formatted_results.append(
            DeepResearchResult(
                title=result.title,
                link=result.link,
                content=result.content,
                raw_content=result.raw_content,
                filtered_raw_content=summarized_content,
            )
        )
    return DeepResearchResults(results=formatted_results)
# {{/docs-fragment search_and_summarize}}

@env.task
async def search_all_queries(
    queries: list[str], summarization_model: str, prompts_file: File
) -> DeepResearchResults:
    """Execute searches for all queries in parallel"""
    tasks = []
    results_list = []

    tasks = [
        search_and_summarize(query, prompts_file, summarization_model)
        for query in queries
    ]

    if tasks:
        res_list = await asyncio.gather(*tasks)

    results_list.extend(res_list)

    # Combine all results
    combined_results = DeepResearchResults(results=[])
    for results in results_list:
        combined_results = combined_results + results

    return combined_results

# {{docs-fragment evaluate_research_completeness}}
@env.task
async def evaluate_research_completeness(
    topic: str,
    results: DeepResearchResults,
    queries: list[str],
    prompts_file: File,
    planning_model: str,
    json_model: str,
) -> list[str]:
    """
    Evaluate if the current search results are sufficient or if more research is needed.
    Returns an empty list if research is complete, or a list of additional queries if more research is needed.
    """

    # Format the search results for the LLM
    formatted_results = str(results)

    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    prompts = yaml.safe_load(yaml_contents)

    EVALUATION_PROMPT = prompts["evaluation_prompt"]

    logging.info("\nEvaluation: ")
    evaluation = ""
    async for chunk in asingle_shot_llm_call(
        model=planning_model,
        system_prompt=EVALUATION_PROMPT,
        message=(
            f"<Research Topic>{topic}</Research Topic>\n\n"
            f"<Search Queries Used>{queries}</Search Queries Used>\n\n"
            f"<Current Search Results>{formatted_results}</Current Search Results>"
        ),
        response_format=None,
        max_completion_tokens=None,
    ):
        evaluation += chunk
        print(chunk, end="", flush=True)

    EVALUATION_PARSING_PROMPT = prompts["evaluation_parsing_prompt"]

    response_json = ""
    async for chunk in asingle_shot_llm_call(
        model=json_model,
        system_prompt=EVALUATION_PARSING_PROMPT,
        message=f"Evaluation to be parsed: {evaluation}",
        response_format={
            "type": "json_object",
            "schema": ResearchPlan.model_json_schema(),
        },
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        response_json += chunk

    evaluation = json.loads(response_json)
    return evaluation["queries"]
# {{/docs-fragment evaluate_research_completeness}}

# {{docs-fragment filter_results}}
@env.task
async def filter_results(
    topic: str,
    results: DeepResearchResults,
    prompts_file: File,
    planning_model: str,
    json_model: str,
    max_sources: int,
) -> DeepResearchResults:
    """Filter the search results based on the research plan"""

    # Format the search results for the LLM, without the raw content
    formatted_results = str(results)

    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    prompts = yaml.safe_load(yaml_contents)
    FILTER_PROMPT = prompts["filter_prompt"]

    logging.info("\nFilter response: ")
    filter_response = ""
    async for chunk in asingle_shot_llm_call(
        model=planning_model,
        system_prompt=FILTER_PROMPT,
        message=(
            f"<Research Topic>{topic}</Research Topic>\n\n"
            f"<Current Search Results>{formatted_results}</Current Search Results>"
        ),
        response_format=None,
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        filter_response += chunk
        print(chunk, end="", flush=True)

    logging.info(f"Filter response: {filter_response}")

    FILTER_PARSING_PROMPT = prompts["filter_parsing_prompt"]

    response_json = ""
    async for chunk in asingle_shot_llm_call(
        model=json_model,
        system_prompt=FILTER_PARSING_PROMPT,
        message=f"Filter response to be parsed: {filter_response}",
        response_format={
            "type": "json_object",
            "schema": SourceList.model_json_schema(),
        },
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        response_json += chunk

    sources = json.loads(response_json)["sources"]

    logging.info(f"Filtered sources: {sources}")

    if max_sources != -1:
        sources = sources[:max_sources]

    # Filter the results based on the source list
    filtered_results = [
        results.results[i - 1] for i in sources if i - 1 < len(results.results)
    ]

    return DeepResearchResults(results=filtered_results)
# {{/docs-fragment filter_results}}

def _remove_thinking_tags(answer: str) -> str:
    """Remove content within <think> tags"""
    while "<think>" in answer and "</think>" in answer:
        start = answer.find("<think>")
        end = answer.find("</think>") + len("</think>")
        answer = answer[:start] + answer[end:]
    return answer

# {{docs-fragment generate_research_answer}}
@env.task
async def generate_research_answer(
    topic: str,
    results: DeepResearchResults,
    remove_thinking_tags: bool,
    prompts_file: File,
    answer_model: str,
) -> str:
    """
    Generate a comprehensive answer to the research topic based on the search results.
    Returns a detailed response that synthesizes information from all search results.
    """

    formatted_results = str(results)
    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    prompts = yaml.safe_load(yaml_contents)
    ANSWER_PROMPT = prompts["answer_prompt"]

    answer = ""
    async for chunk in asingle_shot_llm_call(
        model=answer_model,
        system_prompt=ANSWER_PROMPT,
        message=f"Research Topic: {topic}\n\nSearch Results:\n{formatted_results}",
        response_format=None,
        # NOTE: This is the max_token parameter for the LLM call on Together AI,
        # may need to be changed for other providers
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        answer += chunk

    # this is just to avoid typing complaints
    if answer is None or not isinstance(answer, str):
        logging.error("No answer generated")
        return "No answer generated"

    if remove_thinking_tags:
        # Remove content within <think> tags
        answer = _remove_thinking_tags(answer)

    # Remove markdown code block markers if they exist at the beginning
    if answer.lstrip().startswith("```"):
        # Find the first line break after the opening backticks
        first_linebreak = answer.find("\n", answer.find("```"))
        if first_linebreak != -1:
            # Remove everything up to and including the first line break
            answer = answer[first_linebreak + 1 :]

        # Remove closing code block if it exists
        if answer.rstrip().endswith("```"):
            answer = answer.rstrip()[:-3].rstrip()

    return answer.strip()
# {{/docs-fragment generate_research_answer}}

# {{docs-fragment research_topic}}
@env.task(retries=flyte.RetryStrategy(count=3, backoff=10, backoff_factor=2))
async def research_topic(
    topic: str,
    budget: int = 3,
    remove_thinking_tags: bool = True,
    max_queries: int = 5,
    answer_model: str = "together_ai/deepseek-ai/DeepSeek-V3",
    planning_model: str = "together_ai/Qwen/Qwen2.5-72B-Instruct-Turbo",
    json_model: str = "together_ai/meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo",
    max_sources: int = 40,
    summarization_model: str = "together_ai/meta-llama/Llama-3.3-70B-Instruct-Turbo",
    prompts_file: File | str = "prompts.yaml",
) -> str:
    """Main method to conduct research on a topic. Will be used for weave evals."""
    if isinstance(prompts_file, str):
        prompts_file = await File.from_local(prompts_file)

    # Step 1: Generate initial queries
    queries = await generate_research_queries(
        topic=topic,
        planning_model=planning_model,
        json_model=json_model,
        prompts_file=prompts_file,
    )
    queries = [topic, *queries[: max_queries - 1]]
    all_queries = queries.copy()
    logging.info(f"Initial queries: {queries}")

    if len(queries) == 0:
        logging.error("No initial queries generated")
        return "No initial queries generated"

    # Step 2: Perform initial search
    results = await search_all_queries(queries, summarization_model, prompts_file)
    logging.info(f"Initial search complete, found {len(results.results)} results")

    # Step 3: Conduct iterative research within budget
    for iteration in range(budget):
        with flyte.group(f"eval_iteration_{iteration}"):
            # Evaluate if more research is needed
            additional_queries = await evaluate_research_completeness(
                topic=topic,
                results=results,
                queries=all_queries,
                prompts_file=prompts_file,
                planning_model=planning_model,
                json_model=json_model,
            )

            # Filter out empty strings and check if any queries remain
            additional_queries = [q for q in additional_queries if q]
            if not additional_queries:
                logging.info("No need for additional research")
                break

            # for debugging purposes we limit the number of queries
            additional_queries = additional_queries[:max_queries]
            logging.info(f"Additional queries: {additional_queries}")

            # Expand research with new queries
            new_results = await search_all_queries(
                additional_queries, summarization_model, prompts_file
            )
            logging.info(
                f"Follow-up search complete, found {len(new_results.results)} results"
            )

            results = results + new_results
            all_queries.extend(additional_queries)

    # Step 4: Generate final answer
    logging.info(f"Generating final answer for topic: {topic}")
    results = results.dedup()
    logging.info(f"Deduplication complete, kept {len(results.results)} results")
    filtered_results = await filter_results(
        topic=topic,
        results=results,
        prompts_file=prompts_file,
        planning_model=planning_model,
        json_model=json_model,
        max_sources=max_sources,
    )
    logging.info(
        f"LLM Filtering complete, kept {len(filtered_results.results)} results"
    )

    # Generate final answer
    answer = await generate_research_answer(
        topic=topic,
        results=filtered_results,
        remove_thinking_tags=remove_thinking_tags,
        prompts_file=prompts_file,
        answer_model=answer_model,
    )

    return answer
# {{/docs-fragment research_topic}}

# {{docs-fragment main}}
@env.task(report=True)
async def main(
    topic: str = (
        "List the essential requirements for a developer-focused agent orchestration system."
    ),
    prompts_file: File | str = "/root/prompts.yaml",
    budget: int = 2,
    remove_thinking_tags: bool = True,
    max_queries: int = 3,
    answer_model: str = "together_ai/deepseek-ai/DeepSeek-V3",
    planning_model: str = "together_ai/Qwen/Qwen2.5-72B-Instruct-Turbo",
    json_model: str = "together_ai/meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo",
    max_sources: int = 10,
    summarization_model: str = "together_ai/meta-llama/Llama-3.3-70B-Instruct-Turbo",
) -> str:
    if isinstance(prompts_file, str):
        prompts_file = await File.from_local(prompts_file)

    answer = await research_topic(
        topic=topic,
        budget=budget,
        remove_thinking_tags=remove_thinking_tags,
        max_queries=max_queries,
        answer_model=answer_model,
        planning_model=planning_model,
        json_model=json_model,
        max_sources=max_sources,
        summarization_model=summarization_model,
        prompts_file=prompts_file,
    )

    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    toc_image_url = await generate_toc_image(
        yaml.safe_load(yaml_contents)["data_visualization_prompt"],
        planning_model,
        topic,
    )

    html_content = await generate_html(answer, toc_image_url)
    await flyte.report.replace.aio(html_content, do_flush=True)
    await flyte.report.flush.aio()

    return html_content
# {{/docs-fragment main}}

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/deep_research_agent/agent.py*

The Python packages are declared at the top of the file using the `uv` script style:

CODE2

## Generate research queries

This task converts a user prompt into a list of focused queries. It makes two LLM calls to generate a high-level research plan and parse that plan into atomic search queries.

CODE3"):
        # Find the first line break after the opening backticks
        first_linebreak = answer.find("\n", answer.find("CODE4"):
            answer = answer.rstrip()[:-3].rstrip()

    return answer.strip()
# {{/docs-fragment generate_research_answer}}

# {{docs-fragment research_topic}}
@env.task(retries=flyte.RetryStrategy(count=3, backoff=10, backoff_factor=2))
async def research_topic(
    topic: str,
    budget: int = 3,
    remove_thinking_tags: bool = True,
    max_queries: int = 5,
    answer_model: str = "together_ai/deepseek-ai/DeepSeek-V3",
    planning_model: str = "together_ai/Qwen/Qwen2.5-72B-Instruct-Turbo",
    json_model: str = "together_ai/meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo",
    max_sources: int = 40,
    summarization_model: str = "together_ai/meta-llama/Llama-3.3-70B-Instruct-Turbo",
    prompts_file: File | str = "prompts.yaml",
) -> str:
    """Main method to conduct research on a topic. Will be used for weave evals."""
    if isinstance(prompts_file, str):
        prompts_file = await File.from_local(prompts_file)

    # Step 1: Generate initial queries
    queries = await generate_research_queries(
        topic=topic,
        planning_model=planning_model,
        json_model=json_model,
        prompts_file=prompts_file,
    )
    queries = [topic, *queries[: max_queries - 1]]
    all_queries = queries.copy()
    logging.info(f"Initial queries: {queries}")

    if len(queries) == 0:
        logging.error("No initial queries generated")
        return "No initial queries generated"

    # Step 2: Perform initial search
    results = await search_all_queries(queries, summarization_model, prompts_file)
    logging.info(f"Initial search complete, found {len(results.results)} results")

    # Step 3: Conduct iterative research within budget
    for iteration in range(budget):
        with flyte.group(f"eval_iteration_{iteration}"):
            # Evaluate if more research is needed
            additional_queries = await evaluate_research_completeness(
                topic=topic,
                results=results,
                queries=all_queries,
                prompts_file=prompts_file,
                planning_model=planning_model,
                json_model=json_model,
            )

            # Filter out empty strings and check if any queries remain
            additional_queries = [q for q in additional_queries if q]
            if not additional_queries:
                logging.info("No need for additional research")
                break

            # for debugging purposes we limit the number of queries
            additional_queries = additional_queries[:max_queries]
            logging.info(f"Additional queries: {additional_queries}")

            # Expand research with new queries
            new_results = await search_all_queries(
                additional_queries, summarization_model, prompts_file
            )
            logging.info(
                f"Follow-up search complete, found {len(new_results.results)} results"
            )

            results = results + new_results
            all_queries.extend(additional_queries)

    # Step 4: Generate final answer
    logging.info(f"Generating final answer for topic: {topic}")
    results = results.dedup()
    logging.info(f"Deduplication complete, kept {len(results.results)} results")
    filtered_results = await filter_results(
        topic=topic,
        results=results,
        prompts_file=prompts_file,
        planning_model=planning_model,
        json_model=json_model,
        max_sources=max_sources,
    )
    logging.info(
        f"LLM Filtering complete, kept {len(filtered_results.results)} results"
    )

    # Generate final answer
    answer = await generate_research_answer(
        topic=topic,
        results=filtered_results,
        remove_thinking_tags=remove_thinking_tags,
        prompts_file=prompts_file,
        answer_model=answer_model,
    )

    return answer
# {{/docs-fragment research_topic}}

# {{docs-fragment main}}
@env.task(report=True)
async def main(
    topic: str = (
        "List the essential requirements for a developer-focused agent orchestration system."
    ),
    prompts_file: File | str = "/root/prompts.yaml",
    budget: int = 2,
    remove_thinking_tags: bool = True,
    max_queries: int = 3,
    answer_model: str = "together_ai/deepseek-ai/DeepSeek-V3",
    planning_model: str = "together_ai/Qwen/Qwen2.5-72B-Instruct-Turbo",
    json_model: str = "together_ai/meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo",
    max_sources: int = 10,
    summarization_model: str = "together_ai/meta-llama/Llama-3.3-70B-Instruct-Turbo",
) -> str:
    if isinstance(prompts_file, str):
        prompts_file = await File.from_local(prompts_file)

    answer = await research_topic(
        topic=topic,
        budget=budget,
        remove_thinking_tags=remove_thinking_tags,
        max_queries=max_queries,
        answer_model=answer_model,
        planning_model=planning_model,
        json_model=json_model,
        max_sources=max_sources,
        summarization_model=summarization_model,
        prompts_file=prompts_file,
    )

    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    toc_image_url = await generate_toc_image(
        yaml.safe_load(yaml_contents)["data_visualization_prompt"],
        planning_model,
        topic,
    )

    html_content = await generate_html(answer, toc_image_url)
    await flyte.report.replace.aio(html_content, do_flush=True)
    await flyte.report.flush.aio()

    return html_content
# {{/docs-fragment main}}

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/deep_research_agent/agent.py*

LLM calls use LiteLLM, and each is wrapped with `flyte.trace` for observability:

CODE5

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/deep_research_agent/libs/utils/llms.py*

> [!NOTE]
> We use `flyte.trace` to track intermediate steps within a task, like LLM calls or specific function executions. This lightweight decorator adds observability with minimal overhead and is especially useful for inspecting reasoning chains during task execution.

## Search and summarize

We submit each research query to Tavily and summarize the results using an LLM. We run all summarization tasks with `asyncio.gather`, which signals to Flyte that these tasks can be distributed across separate compute resources.

CODE6"):
        # Find the first line break after the opening backticks
        first_linebreak = answer.find("\n", answer.find("CODE7"):
            answer = answer.rstrip()[:-3].rstrip()

    return answer.strip()
# {{/docs-fragment generate_research_answer}}

# {{docs-fragment research_topic}}
@env.task(retries=flyte.RetryStrategy(count=3, backoff=10, backoff_factor=2))
async def research_topic(
    topic: str,
    budget: int = 3,
    remove_thinking_tags: bool = True,
    max_queries: int = 5,
    answer_model: str = "together_ai/deepseek-ai/DeepSeek-V3",
    planning_model: str = "together_ai/Qwen/Qwen2.5-72B-Instruct-Turbo",
    json_model: str = "together_ai/meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo",
    max_sources: int = 40,
    summarization_model: str = "together_ai/meta-llama/Llama-3.3-70B-Instruct-Turbo",
    prompts_file: File | str = "prompts.yaml",
) -> str:
    """Main method to conduct research on a topic. Will be used for weave evals."""
    if isinstance(prompts_file, str):
        prompts_file = await File.from_local(prompts_file)

    # Step 1: Generate initial queries
    queries = await generate_research_queries(
        topic=topic,
        planning_model=planning_model,
        json_model=json_model,
        prompts_file=prompts_file,
    )
    queries = [topic, *queries[: max_queries - 1]]
    all_queries = queries.copy()
    logging.info(f"Initial queries: {queries}")

    if len(queries) == 0:
        logging.error("No initial queries generated")
        return "No initial queries generated"

    # Step 2: Perform initial search
    results = await search_all_queries(queries, summarization_model, prompts_file)
    logging.info(f"Initial search complete, found {len(results.results)} results")

    # Step 3: Conduct iterative research within budget
    for iteration in range(budget):
        with flyte.group(f"eval_iteration_{iteration}"):
            # Evaluate if more research is needed
            additional_queries = await evaluate_research_completeness(
                topic=topic,
                results=results,
                queries=all_queries,
                prompts_file=prompts_file,
                planning_model=planning_model,
                json_model=json_model,
            )

            # Filter out empty strings and check if any queries remain
            additional_queries = [q for q in additional_queries if q]
            if not additional_queries:
                logging.info("No need for additional research")
                break

            # for debugging purposes we limit the number of queries
            additional_queries = additional_queries[:max_queries]
            logging.info(f"Additional queries: {additional_queries}")

            # Expand research with new queries
            new_results = await search_all_queries(
                additional_queries, summarization_model, prompts_file
            )
            logging.info(
                f"Follow-up search complete, found {len(new_results.results)} results"
            )

            results = results + new_results
            all_queries.extend(additional_queries)

    # Step 4: Generate final answer
    logging.info(f"Generating final answer for topic: {topic}")
    results = results.dedup()
    logging.info(f"Deduplication complete, kept {len(results.results)} results")
    filtered_results = await filter_results(
        topic=topic,
        results=results,
        prompts_file=prompts_file,
        planning_model=planning_model,
        json_model=json_model,
        max_sources=max_sources,
    )
    logging.info(
        f"LLM Filtering complete, kept {len(filtered_results.results)} results"
    )

    # Generate final answer
    answer = await generate_research_answer(
        topic=topic,
        results=filtered_results,
        remove_thinking_tags=remove_thinking_tags,
        prompts_file=prompts_file,
        answer_model=answer_model,
    )

    return answer
# {{/docs-fragment research_topic}}

# {{docs-fragment main}}
@env.task(report=True)
async def main(
    topic: str = (
        "List the essential requirements for a developer-focused agent orchestration system."
    ),
    prompts_file: File | str = "/root/prompts.yaml",
    budget: int = 2,
    remove_thinking_tags: bool = True,
    max_queries: int = 3,
    answer_model: str = "together_ai/deepseek-ai/DeepSeek-V3",
    planning_model: str = "together_ai/Qwen/Qwen2.5-72B-Instruct-Turbo",
    json_model: str = "together_ai/meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo",
    max_sources: int = 10,
    summarization_model: str = "together_ai/meta-llama/Llama-3.3-70B-Instruct-Turbo",
) -> str:
    if isinstance(prompts_file, str):
        prompts_file = await File.from_local(prompts_file)

    answer = await research_topic(
        topic=topic,
        budget=budget,
        remove_thinking_tags=remove_thinking_tags,
        max_queries=max_queries,
        answer_model=answer_model,
        planning_model=planning_model,
        json_model=json_model,
        max_sources=max_sources,
        summarization_model=summarization_model,
        prompts_file=prompts_file,
    )

    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    toc_image_url = await generate_toc_image(
        yaml.safe_load(yaml_contents)["data_visualization_prompt"],
        planning_model,
        topic,
    )

    html_content = await generate_html(answer, toc_image_url)
    await flyte.report.replace.aio(html_content, do_flush=True)
    await flyte.report.flush.aio()

    return html_content
# {{/docs-fragment main}}

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
CODE8
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "pydantic==2.11.5",
#    "litellm==1.72.2",
#    "tavily-python==0.7.5",
#    "together==1.5.24",
#    "markdown==3.8.2",
#    "pymdown-extensions==10.16.1",
# ]
# main = "main"
# params = ""
# ///

# {{docs-fragment env}}
import asyncio
import json
from pathlib import Path

import flyte
import yaml
from flyte.io._file import File
from libs.utils.data_types import (
    DeepResearchResult,
    DeepResearchResults,
    ResearchPlan,
    SourceList,
)
from libs.utils.generation import generate_html, generate_toc_image
from libs.utils.llms import asingle_shot_llm_call
from libs.utils.log import AgentLogger
from libs.utils.tavily_search import atavily_search_results

TIME_LIMIT_MULTIPLIER = 5
MAX_COMPLETION_TOKENS = 4096

logging = AgentLogger("together.open_deep_research")

env = flyte.TaskEnvironment(
    name="deep-researcher",
    secrets=[
        flyte.Secret(key="together_api_key", as_env_var="TOGETHER_API_KEY"),
        flyte.Secret(key="tavily_api_key", as_env_var="TAVILY_API_KEY"),
    ],
    image=flyte.Image.from_uv_script(__file__, name="deep-research-agent", pre=True)
    .with_apt_packages("pandoc", "texlive-xetex")
    .with_source_file(Path("prompts.yaml"), "/root"),
    resources=flyte.Resources(cpu=1),
)
# {{/docs-fragment env}}

# {{docs-fragment generate_research_queries}}
@env.task
async def generate_research_queries(
    topic: str,
    planning_model: str,
    json_model: str,
    prompts_file: File,
) -> list[str]:
    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    prompts = yaml.safe_load(yaml_contents)
    PLANNING_PROMPT = prompts["planning_prompt"]

    plan = ""
    logging.info(f"\n\nGenerated deep research plan for topic: {topic}\n\nPlan:")
    async for chunk in asingle_shot_llm_call(
        model=planning_model,
        system_prompt=PLANNING_PROMPT,
        message=f"Research Topic: {topic}",
        response_format=None,
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        plan += chunk
        print(chunk, end="", flush=True)

    SEARCH_PROMPT = prompts["plan_parsing_prompt"]

    response_json = ""
    async for chunk in asingle_shot_llm_call(
        model=json_model,
        system_prompt=SEARCH_PROMPT,
        message=f"Plan to be parsed: {plan}",
        response_format={
            "type": "json_object",
            "schema": ResearchPlan.model_json_schema(),
        },
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        response_json += chunk

    plan = json.loads(response_json)
    return plan["queries"]
# {{/docs-fragment generate_research_queries}}

async def _summarize_content_async(
    raw_content: str,
    query: str,
    prompt: str,
    summarization_model: str,
) -> str:
    """Summarize content asynchronously using the LLM"""
    logging.info("Summarizing content asynchronously using the LLM")

    result = ""
    async for chunk in asingle_shot_llm_call(
        model=summarization_model,
        system_prompt=prompt,
        message=f"<Raw Content>{raw_content}</Raw Content>\n\n<Research Topic>{query}</Research Topic>",
        response_format=None,
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        result += chunk
    return result

# {{docs-fragment search_and_summarize}}
@env.task
async def search_and_summarize(
    query: str,
    prompts_file: File,
    summarization_model: str,
) -> DeepResearchResults:
    """Perform search for a single query"""

    if len(query) > 400:
        # NOTE: we are truncating the query to 400 characters to avoid Tavily Search issues
        query = query[:400]
        logging.info(f"Truncated query to 400 characters: {query}")

    response = await atavily_search_results(query)

    logging.info("Tavily Search Called.")

    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    prompts = yaml.safe_load(yaml_contents)
    RAW_CONTENT_SUMMARIZER_PROMPT = prompts["raw_content_summarizer_prompt"]

    with flyte.group("summarize-content"):
        # Create tasks for summarization
        summarization_tasks = []
        result_info = []
        for result in response.results:
            if result.raw_content is None:
                continue

            task = _summarize_content_async(
                result.raw_content,
                query,
                RAW_CONTENT_SUMMARIZER_PROMPT,
                summarization_model,
            )
            summarization_tasks.append(task)
            result_info.append(result)

        # Use return_exceptions=True to prevent exceptions from propagating
        summarized_contents = await asyncio.gather(
            *summarization_tasks, return_exceptions=True
        )

    # Filter out exceptions
    summarized_contents = [
        result for result in summarized_contents if not isinstance(result, Exception)
    ]

    formatted_results = []
    for result, summarized_content in zip(result_info, summarized_contents):
        formatted_results.append(
            DeepResearchResult(
                title=result.title,
                link=result.link,
                content=result.content,
                raw_content=result.raw_content,
                filtered_raw_content=summarized_content,
            )
        )
    return DeepResearchResults(results=formatted_results)
# {{/docs-fragment search_and_summarize}}

@env.task
async def search_all_queries(
    queries: list[str], summarization_model: str, prompts_file: File
) -> DeepResearchResults:
    """Execute searches for all queries in parallel"""
    tasks = []
    results_list = []

    tasks = [
        search_and_summarize(query, prompts_file, summarization_model)
        for query in queries
    ]

    if tasks:
        res_list = await asyncio.gather(*tasks)

    results_list.extend(res_list)

    # Combine all results
    combined_results = DeepResearchResults(results=[])
    for results in results_list:
        combined_results = combined_results + results

    return combined_results

# {{docs-fragment evaluate_research_completeness}}
@env.task
async def evaluate_research_completeness(
    topic: str,
    results: DeepResearchResults,
    queries: list[str],
    prompts_file: File,
    planning_model: str,
    json_model: str,
) -> list[str]:
    """
    Evaluate if the current search results are sufficient or if more research is needed.
    Returns an empty list if research is complete, or a list of additional queries if more research is needed.
    """

    # Format the search results for the LLM
    formatted_results = str(results)

    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    prompts = yaml.safe_load(yaml_contents)

    EVALUATION_PROMPT = prompts["evaluation_prompt"]

    logging.info("\nEvaluation: ")
    evaluation = ""
    async for chunk in asingle_shot_llm_call(
        model=planning_model,
        system_prompt=EVALUATION_PROMPT,
        message=(
            f"<Research Topic>{topic}</Research Topic>\n\n"
            f"<Search Queries Used>{queries}</Search Queries Used>\n\n"
            f"<Current Search Results>{formatted_results}</Current Search Results>"
        ),
        response_format=None,
        max_completion_tokens=None,
    ):
        evaluation += chunk
        print(chunk, end="", flush=True)

    EVALUATION_PARSING_PROMPT = prompts["evaluation_parsing_prompt"]

    response_json = ""
    async for chunk in asingle_shot_llm_call(
        model=json_model,
        system_prompt=EVALUATION_PARSING_PROMPT,
        message=f"Evaluation to be parsed: {evaluation}",
        response_format={
            "type": "json_object",
            "schema": ResearchPlan.model_json_schema(),
        },
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        response_json += chunk

    evaluation = json.loads(response_json)
    return evaluation["queries"]
# {{/docs-fragment evaluate_research_completeness}}

# {{docs-fragment filter_results}}
@env.task
async def filter_results(
    topic: str,
    results: DeepResearchResults,
    prompts_file: File,
    planning_model: str,
    json_model: str,
    max_sources: int,
) -> DeepResearchResults:
    """Filter the search results based on the research plan"""

    # Format the search results for the LLM, without the raw content
    formatted_results = str(results)

    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    prompts = yaml.safe_load(yaml_contents)
    FILTER_PROMPT = prompts["filter_prompt"]

    logging.info("\nFilter response: ")
    filter_response = ""
    async for chunk in asingle_shot_llm_call(
        model=planning_model,
        system_prompt=FILTER_PROMPT,
        message=(
            f"<Research Topic>{topic}</Research Topic>\n\n"
            f"<Current Search Results>{formatted_results}</Current Search Results>"
        ),
        response_format=None,
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        filter_response += chunk
        print(chunk, end="", flush=True)

    logging.info(f"Filter response: {filter_response}")

    FILTER_PARSING_PROMPT = prompts["filter_parsing_prompt"]

    response_json = ""
    async for chunk in asingle_shot_llm_call(
        model=json_model,
        system_prompt=FILTER_PARSING_PROMPT,
        message=f"Filter response to be parsed: {filter_response}",
        response_format={
            "type": "json_object",
            "schema": SourceList.model_json_schema(),
        },
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        response_json += chunk

    sources = json.loads(response_json)["sources"]

    logging.info(f"Filtered sources: {sources}")

    if max_sources != -1:
        sources = sources[:max_sources]

    # Filter the results based on the source list
    filtered_results = [
        results.results[i - 1] for i in sources if i - 1 < len(results.results)
    ]

    return DeepResearchResults(results=filtered_results)
# {{/docs-fragment filter_results}}

def _remove_thinking_tags(answer: str) -> str:
    """Remove content within <think> tags"""
    while "<think>" in answer and "</think>" in answer:
        start = answer.find("<think>")
        end = answer.find("</think>") + len("</think>")
        answer = answer[:start] + answer[end:]
    return answer

# {{docs-fragment generate_research_answer}}
@env.task
async def generate_research_answer(
    topic: str,
    results: DeepResearchResults,
    remove_thinking_tags: bool,
    prompts_file: File,
    answer_model: str,
) -> str:
    """
    Generate a comprehensive answer to the research topic based on the search results.
    Returns a detailed response that synthesizes information from all search results.
    """

    formatted_results = str(results)
    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    prompts = yaml.safe_load(yaml_contents)
    ANSWER_PROMPT = prompts["answer_prompt"]

    answer = ""
    async for chunk in asingle_shot_llm_call(
        model=answer_model,
        system_prompt=ANSWER_PROMPT,
        message=f"Research Topic: {topic}\n\nSearch Results:\n{formatted_results}",
        response_format=None,
        # NOTE: This is the max_token parameter for the LLM call on Together AI,
        # may need to be changed for other providers
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        answer += chunk

    # this is just to avoid typing complaints
    if answer is None or not isinstance(answer, str):
        logging.error("No answer generated")
        return "No answer generated"

    if remove_thinking_tags:
        # Remove content within <think> tags
        answer = _remove_thinking_tags(answer)

    # Remove markdown code block markers if they exist at the beginning
    if answer.lstrip().startswith("CODE9"))
        if first_linebreak != -1:
            # Remove everything up to and including the first line break
            answer = answer[first_linebreak + 1 :]

        # Remove closing code block if it exists
        if answer.rstrip().endswith("CODE10

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/deep_research_agent/agent.py*

## Filter results

In this step, we evaluate the relevance of search results and rank them. This task returns the most useful sources for the final synthesis.

CODE11"):
        # Find the first line break after the opening backticks
        first_linebreak = answer.find("\n", answer.find("CODE12"):
            answer = answer.rstrip()[:-3].rstrip()

    return answer.strip()
# {{/docs-fragment generate_research_answer}}

# {{docs-fragment research_topic}}
@env.task(retries=flyte.RetryStrategy(count=3, backoff=10, backoff_factor=2))
async def research_topic(
    topic: str,
    budget: int = 3,
    remove_thinking_tags: bool = True,
    max_queries: int = 5,
    answer_model: str = "together_ai/deepseek-ai/DeepSeek-V3",
    planning_model: str = "together_ai/Qwen/Qwen2.5-72B-Instruct-Turbo",
    json_model: str = "together_ai/meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo",
    max_sources: int = 40,
    summarization_model: str = "together_ai/meta-llama/Llama-3.3-70B-Instruct-Turbo",
    prompts_file: File | str = "prompts.yaml",
) -> str:
    """Main method to conduct research on a topic. Will be used for weave evals."""
    if isinstance(prompts_file, str):
        prompts_file = await File.from_local(prompts_file)

    # Step 1: Generate initial queries
    queries = await generate_research_queries(
        topic=topic,
        planning_model=planning_model,
        json_model=json_model,
        prompts_file=prompts_file,
    )
    queries = [topic, *queries[: max_queries - 1]]
    all_queries = queries.copy()
    logging.info(f"Initial queries: {queries}")

    if len(queries) == 0:
        logging.error("No initial queries generated")
        return "No initial queries generated"

    # Step 2: Perform initial search
    results = await search_all_queries(queries, summarization_model, prompts_file)
    logging.info(f"Initial search complete, found {len(results.results)} results")

    # Step 3: Conduct iterative research within budget
    for iteration in range(budget):
        with flyte.group(f"eval_iteration_{iteration}"):
            # Evaluate if more research is needed
            additional_queries = await evaluate_research_completeness(
                topic=topic,
                results=results,
                queries=all_queries,
                prompts_file=prompts_file,
                planning_model=planning_model,
                json_model=json_model,
            )

            # Filter out empty strings and check if any queries remain
            additional_queries = [q for q in additional_queries if q]
            if not additional_queries:
                logging.info("No need for additional research")
                break

            # for debugging purposes we limit the number of queries
            additional_queries = additional_queries[:max_queries]
            logging.info(f"Additional queries: {additional_queries}")

            # Expand research with new queries
            new_results = await search_all_queries(
                additional_queries, summarization_model, prompts_file
            )
            logging.info(
                f"Follow-up search complete, found {len(new_results.results)} results"
            )

            results = results + new_results
            all_queries.extend(additional_queries)

    # Step 4: Generate final answer
    logging.info(f"Generating final answer for topic: {topic}")
    results = results.dedup()
    logging.info(f"Deduplication complete, kept {len(results.results)} results")
    filtered_results = await filter_results(
        topic=topic,
        results=results,
        prompts_file=prompts_file,
        planning_model=planning_model,
        json_model=json_model,
        max_sources=max_sources,
    )
    logging.info(
        f"LLM Filtering complete, kept {len(filtered_results.results)} results"
    )

    # Generate final answer
    answer = await generate_research_answer(
        topic=topic,
        results=filtered_results,
        remove_thinking_tags=remove_thinking_tags,
        prompts_file=prompts_file,
        answer_model=answer_model,
    )

    return answer
# {{/docs-fragment research_topic}}

# {{docs-fragment main}}
@env.task(report=True)
async def main(
    topic: str = (
        "List the essential requirements for a developer-focused agent orchestration system."
    ),
    prompts_file: File | str = "/root/prompts.yaml",
    budget: int = 2,
    remove_thinking_tags: bool = True,
    max_queries: int = 3,
    answer_model: str = "together_ai/deepseek-ai/DeepSeek-V3",
    planning_model: str = "together_ai/Qwen/Qwen2.5-72B-Instruct-Turbo",
    json_model: str = "together_ai/meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo",
    max_sources: int = 10,
    summarization_model: str = "together_ai/meta-llama/Llama-3.3-70B-Instruct-Turbo",
) -> str:
    if isinstance(prompts_file, str):
        prompts_file = await File.from_local(prompts_file)

    answer = await research_topic(
        topic=topic,
        budget=budget,
        remove_thinking_tags=remove_thinking_tags,
        max_queries=max_queries,
        answer_model=answer_model,
        planning_model=planning_model,
        json_model=json_model,
        max_sources=max_sources,
        summarization_model=summarization_model,
        prompts_file=prompts_file,
    )

    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    toc_image_url = await generate_toc_image(
        yaml.safe_load(yaml_contents)["data_visualization_prompt"],
        planning_model,
        topic,
    )

    html_content = await generate_html(answer, toc_image_url)
    await flyte.report.replace.aio(html_content, do_flush=True)
    await flyte.report.flush.aio()

    return html_content
# {{/docs-fragment main}}

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
CODE13
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "pydantic==2.11.5",
#    "litellm==1.72.2",
#    "tavily-python==0.7.5",
#    "together==1.5.24",
#    "markdown==3.8.2",
#    "pymdown-extensions==10.16.1",
# ]
# main = "main"
# params = ""
# ///

# {{docs-fragment env}}
import asyncio
import json
from pathlib import Path

import flyte
import yaml
from flyte.io._file import File
from libs.utils.data_types import (
    DeepResearchResult,
    DeepResearchResults,
    ResearchPlan,
    SourceList,
)
from libs.utils.generation import generate_html, generate_toc_image
from libs.utils.llms import asingle_shot_llm_call
from libs.utils.log import AgentLogger
from libs.utils.tavily_search import atavily_search_results

TIME_LIMIT_MULTIPLIER = 5
MAX_COMPLETION_TOKENS = 4096

logging = AgentLogger("together.open_deep_research")

env = flyte.TaskEnvironment(
    name="deep-researcher",
    secrets=[
        flyte.Secret(key="together_api_key", as_env_var="TOGETHER_API_KEY"),
        flyte.Secret(key="tavily_api_key", as_env_var="TAVILY_API_KEY"),
    ],
    image=flyte.Image.from_uv_script(__file__, name="deep-research-agent", pre=True)
    .with_apt_packages("pandoc", "texlive-xetex")
    .with_source_file(Path("prompts.yaml"), "/root"),
    resources=flyte.Resources(cpu=1),
)
# {{/docs-fragment env}}

# {{docs-fragment generate_research_queries}}
@env.task
async def generate_research_queries(
    topic: str,
    planning_model: str,
    json_model: str,
    prompts_file: File,
) -> list[str]:
    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    prompts = yaml.safe_load(yaml_contents)
    PLANNING_PROMPT = prompts["planning_prompt"]

    plan = ""
    logging.info(f"\n\nGenerated deep research plan for topic: {topic}\n\nPlan:")
    async for chunk in asingle_shot_llm_call(
        model=planning_model,
        system_prompt=PLANNING_PROMPT,
        message=f"Research Topic: {topic}",
        response_format=None,
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        plan += chunk
        print(chunk, end="", flush=True)

    SEARCH_PROMPT = prompts["plan_parsing_prompt"]

    response_json = ""
    async for chunk in asingle_shot_llm_call(
        model=json_model,
        system_prompt=SEARCH_PROMPT,
        message=f"Plan to be parsed: {plan}",
        response_format={
            "type": "json_object",
            "schema": ResearchPlan.model_json_schema(),
        },
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        response_json += chunk

    plan = json.loads(response_json)
    return plan["queries"]
# {{/docs-fragment generate_research_queries}}

async def _summarize_content_async(
    raw_content: str,
    query: str,
    prompt: str,
    summarization_model: str,
) -> str:
    """Summarize content asynchronously using the LLM"""
    logging.info("Summarizing content asynchronously using the LLM")

    result = ""
    async for chunk in asingle_shot_llm_call(
        model=summarization_model,
        system_prompt=prompt,
        message=f"<Raw Content>{raw_content}</Raw Content>\n\n<Research Topic>{query}</Research Topic>",
        response_format=None,
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        result += chunk
    return result

# {{docs-fragment search_and_summarize}}
@env.task
async def search_and_summarize(
    query: str,
    prompts_file: File,
    summarization_model: str,
) -> DeepResearchResults:
    """Perform search for a single query"""

    if len(query) > 400:
        # NOTE: we are truncating the query to 400 characters to avoid Tavily Search issues
        query = query[:400]
        logging.info(f"Truncated query to 400 characters: {query}")

    response = await atavily_search_results(query)

    logging.info("Tavily Search Called.")

    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    prompts = yaml.safe_load(yaml_contents)
    RAW_CONTENT_SUMMARIZER_PROMPT = prompts["raw_content_summarizer_prompt"]

    with flyte.group("summarize-content"):
        # Create tasks for summarization
        summarization_tasks = []
        result_info = []
        for result in response.results:
            if result.raw_content is None:
                continue

            task = _summarize_content_async(
                result.raw_content,
                query,
                RAW_CONTENT_SUMMARIZER_PROMPT,
                summarization_model,
            )
            summarization_tasks.append(task)
            result_info.append(result)

        # Use return_exceptions=True to prevent exceptions from propagating
        summarized_contents = await asyncio.gather(
            *summarization_tasks, return_exceptions=True
        )

    # Filter out exceptions
    summarized_contents = [
        result for result in summarized_contents if not isinstance(result, Exception)
    ]

    formatted_results = []
    for result, summarized_content in zip(result_info, summarized_contents):
        formatted_results.append(
            DeepResearchResult(
                title=result.title,
                link=result.link,
                content=result.content,
                raw_content=result.raw_content,
                filtered_raw_content=summarized_content,
            )
        )
    return DeepResearchResults(results=formatted_results)
# {{/docs-fragment search_and_summarize}}

@env.task
async def search_all_queries(
    queries: list[str], summarization_model: str, prompts_file: File
) -> DeepResearchResults:
    """Execute searches for all queries in parallel"""
    tasks = []
    results_list = []

    tasks = [
        search_and_summarize(query, prompts_file, summarization_model)
        for query in queries
    ]

    if tasks:
        res_list = await asyncio.gather(*tasks)

    results_list.extend(res_list)

    # Combine all results
    combined_results = DeepResearchResults(results=[])
    for results in results_list:
        combined_results = combined_results + results

    return combined_results

# {{docs-fragment evaluate_research_completeness}}
@env.task
async def evaluate_research_completeness(
    topic: str,
    results: DeepResearchResults,
    queries: list[str],
    prompts_file: File,
    planning_model: str,
    json_model: str,
) -> list[str]:
    """
    Evaluate if the current search results are sufficient or if more research is needed.
    Returns an empty list if research is complete, or a list of additional queries if more research is needed.
    """

    # Format the search results for the LLM
    formatted_results = str(results)

    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    prompts = yaml.safe_load(yaml_contents)

    EVALUATION_PROMPT = prompts["evaluation_prompt"]

    logging.info("\nEvaluation: ")
    evaluation = ""
    async for chunk in asingle_shot_llm_call(
        model=planning_model,
        system_prompt=EVALUATION_PROMPT,
        message=(
            f"<Research Topic>{topic}</Research Topic>\n\n"
            f"<Search Queries Used>{queries}</Search Queries Used>\n\n"
            f"<Current Search Results>{formatted_results}</Current Search Results>"
        ),
        response_format=None,
        max_completion_tokens=None,
    ):
        evaluation += chunk
        print(chunk, end="", flush=True)

    EVALUATION_PARSING_PROMPT = prompts["evaluation_parsing_prompt"]

    response_json = ""
    async for chunk in asingle_shot_llm_call(
        model=json_model,
        system_prompt=EVALUATION_PARSING_PROMPT,
        message=f"Evaluation to be parsed: {evaluation}",
        response_format={
            "type": "json_object",
            "schema": ResearchPlan.model_json_schema(),
        },
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        response_json += chunk

    evaluation = json.loads(response_json)
    return evaluation["queries"]
# {{/docs-fragment evaluate_research_completeness}}

# {{docs-fragment filter_results}}
@env.task
async def filter_results(
    topic: str,
    results: DeepResearchResults,
    prompts_file: File,
    planning_model: str,
    json_model: str,
    max_sources: int,
) -> DeepResearchResults:
    """Filter the search results based on the research plan"""

    # Format the search results for the LLM, without the raw content
    formatted_results = str(results)

    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    prompts = yaml.safe_load(yaml_contents)
    FILTER_PROMPT = prompts["filter_prompt"]

    logging.info("\nFilter response: ")
    filter_response = ""
    async for chunk in asingle_shot_llm_call(
        model=planning_model,
        system_prompt=FILTER_PROMPT,
        message=(
            f"<Research Topic>{topic}</Research Topic>\n\n"
            f"<Current Search Results>{formatted_results}</Current Search Results>"
        ),
        response_format=None,
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        filter_response += chunk
        print(chunk, end="", flush=True)

    logging.info(f"Filter response: {filter_response}")

    FILTER_PARSING_PROMPT = prompts["filter_parsing_prompt"]

    response_json = ""
    async for chunk in asingle_shot_llm_call(
        model=json_model,
        system_prompt=FILTER_PARSING_PROMPT,
        message=f"Filter response to be parsed: {filter_response}",
        response_format={
            "type": "json_object",
            "schema": SourceList.model_json_schema(),
        },
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        response_json += chunk

    sources = json.loads(response_json)["sources"]

    logging.info(f"Filtered sources: {sources}")

    if max_sources != -1:
        sources = sources[:max_sources]

    # Filter the results based on the source list
    filtered_results = [
        results.results[i - 1] for i in sources if i - 1 < len(results.results)
    ]

    return DeepResearchResults(results=filtered_results)
# {{/docs-fragment filter_results}}

def _remove_thinking_tags(answer: str) -> str:
    """Remove content within <think> tags"""
    while "<think>" in answer and "</think>" in answer:
        start = answer.find("<think>")
        end = answer.find("</think>") + len("</think>")
        answer = answer[:start] + answer[end:]
    return answer

# {{docs-fragment generate_research_answer}}
@env.task
async def generate_research_answer(
    topic: str,
    results: DeepResearchResults,
    remove_thinking_tags: bool,
    prompts_file: File,
    answer_model: str,
) -> str:
    """
    Generate a comprehensive answer to the research topic based on the search results.
    Returns a detailed response that synthesizes information from all search results.
    """

    formatted_results = str(results)
    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    prompts = yaml.safe_load(yaml_contents)
    ANSWER_PROMPT = prompts["answer_prompt"]

    answer = ""
    async for chunk in asingle_shot_llm_call(
        model=answer_model,
        system_prompt=ANSWER_PROMPT,
        message=f"Research Topic: {topic}\n\nSearch Results:\n{formatted_results}",
        response_format=None,
        # NOTE: This is the max_token parameter for the LLM call on Together AI,
        # may need to be changed for other providers
        max_completion_tokens=MAX_COMPLETION_TOKENS,
    ):
        answer += chunk

    # this is just to avoid typing complaints
    if answer is None or not isinstance(answer, str):
        logging.error("No answer generated")
        return "No answer generated"

    if remove_thinking_tags:
        # Remove content within <think> tags
        answer = _remove_thinking_tags(answer)

    # Remove markdown code block markers if they exist at the beginning
    if answer.lstrip().startswith("CODE14"))
        if first_linebreak != -1:
            # Remove everything up to and including the first line break
            answer = answer[first_linebreak + 1 :]

        # Remove closing code block if it exists
        if answer.rstrip().endswith("CODE15

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/deep_research_agent/agent.py*

## Orchestration

Next, we define a `research_topic` task to orchestrate the entire deep research workflow. It runs the core stages in sequence: generating research queries, performing search and summarization, evaluating the completeness of results, and producing the final report.

CODE16"):
        # Find the first line break after the opening backticks
        first_linebreak = answer.find("\n", answer.find("CODE17"):
            answer = answer.rstrip()[:-3].rstrip()

    return answer.strip()
# {{/docs-fragment generate_research_answer}}

# {{docs-fragment research_topic}}
@env.task(retries=flyte.RetryStrategy(count=3, backoff=10, backoff_factor=2))
async def research_topic(
    topic: str,
    budget: int = 3,
    remove_thinking_tags: bool = True,
    max_queries: int = 5,
    answer_model: str = "together_ai/deepseek-ai/DeepSeek-V3",
    planning_model: str = "together_ai/Qwen/Qwen2.5-72B-Instruct-Turbo",
    json_model: str = "together_ai/meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo",
    max_sources: int = 40,
    summarization_model: str = "together_ai/meta-llama/Llama-3.3-70B-Instruct-Turbo",
    prompts_file: File | str = "prompts.yaml",
) -> str:
    """Main method to conduct research on a topic. Will be used for weave evals."""
    if isinstance(prompts_file, str):
        prompts_file = await File.from_local(prompts_file)

    # Step 1: Generate initial queries
    queries = await generate_research_queries(
        topic=topic,
        planning_model=planning_model,
        json_model=json_model,
        prompts_file=prompts_file,
    )
    queries = [topic, *queries[: max_queries - 1]]
    all_queries = queries.copy()
    logging.info(f"Initial queries: {queries}")

    if len(queries) == 0:
        logging.error("No initial queries generated")
        return "No initial queries generated"

    # Step 2: Perform initial search
    results = await search_all_queries(queries, summarization_model, prompts_file)
    logging.info(f"Initial search complete, found {len(results.results)} results")

    # Step 3: Conduct iterative research within budget
    for iteration in range(budget):
        with flyte.group(f"eval_iteration_{iteration}"):
            # Evaluate if more research is needed
            additional_queries = await evaluate_research_completeness(
                topic=topic,
                results=results,
                queries=all_queries,
                prompts_file=prompts_file,
                planning_model=planning_model,
                json_model=json_model,
            )

            # Filter out empty strings and check if any queries remain
            additional_queries = [q for q in additional_queries if q]
            if not additional_queries:
                logging.info("No need for additional research")
                break

            # for debugging purposes we limit the number of queries
            additional_queries = additional_queries[:max_queries]
            logging.info(f"Additional queries: {additional_queries}")

            # Expand research with new queries
            new_results = await search_all_queries(
                additional_queries, summarization_model, prompts_file
            )
            logging.info(
                f"Follow-up search complete, found {len(new_results.results)} results"
            )

            results = results + new_results
            all_queries.extend(additional_queries)

    # Step 4: Generate final answer
    logging.info(f"Generating final answer for topic: {topic}")
    results = results.dedup()
    logging.info(f"Deduplication complete, kept {len(results.results)} results")
    filtered_results = await filter_results(
        topic=topic,
        results=results,
        prompts_file=prompts_file,
        planning_model=planning_model,
        json_model=json_model,
        max_sources=max_sources,
    )
    logging.info(
        f"LLM Filtering complete, kept {len(filtered_results.results)} results"
    )

    # Generate final answer
    answer = await generate_research_answer(
        topic=topic,
        results=filtered_results,
        remove_thinking_tags=remove_thinking_tags,
        prompts_file=prompts_file,
        answer_model=answer_model,
    )

    return answer
# {{/docs-fragment research_topic}}

# {{docs-fragment main}}
@env.task(report=True)
async def main(
    topic: str = (
        "List the essential requirements for a developer-focused agent orchestration system."
    ),
    prompts_file: File | str = "/root/prompts.yaml",
    budget: int = 2,
    remove_thinking_tags: bool = True,
    max_queries: int = 3,
    answer_model: str = "together_ai/deepseek-ai/DeepSeek-V3",
    planning_model: str = "together_ai/Qwen/Qwen2.5-72B-Instruct-Turbo",
    json_model: str = "together_ai/meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo",
    max_sources: int = 10,
    summarization_model: str = "together_ai/meta-llama/Llama-3.3-70B-Instruct-Turbo",
) -> str:
    if isinstance(prompts_file, str):
        prompts_file = await File.from_local(prompts_file)

    answer = await research_topic(
        topic=topic,
        budget=budget,
        remove_thinking_tags=remove_thinking_tags,
        max_queries=max_queries,
        answer_model=answer_model,
        planning_model=planning_model,
        json_model=json_model,
        max_sources=max_sources,
        summarization_model=summarization_model,
        prompts_file=prompts_file,
    )

    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    toc_image_url = await generate_toc_image(
        yaml.safe_load(yaml_contents)["data_visualization_prompt"],
        planning_model,
        topic,
    )

    html_content = await generate_html(answer, toc_image_url)
    await flyte.report.replace.aio(html_content, do_flush=True)
    await flyte.report.flush.aio()

    return html_content
# {{/docs-fragment main}}

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/deep_research_agent/agent.py*

The `main` task wraps this entire pipeline and adds report generation in HTML format as the final step.
It also serves as the main entry point to the workflow, allowing us to pass in all configuration parameters, including which LLMs to use at each stage.
This flexibility lets us mix and match models for planning, summarization, and final synthesis, helping us optimize for both cost and quality.

CODE18"):
        # Find the first line break after the opening backticks
        first_linebreak = answer.find("\n", answer.find("CODE19"):
            answer = answer.rstrip()[:-3].rstrip()

    return answer.strip()
# {{/docs-fragment generate_research_answer}}

# {{docs-fragment research_topic}}
@env.task(retries=flyte.RetryStrategy(count=3, backoff=10, backoff_factor=2))
async def research_topic(
    topic: str,
    budget: int = 3,
    remove_thinking_tags: bool = True,
    max_queries: int = 5,
    answer_model: str = "together_ai/deepseek-ai/DeepSeek-V3",
    planning_model: str = "together_ai/Qwen/Qwen2.5-72B-Instruct-Turbo",
    json_model: str = "together_ai/meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo",
    max_sources: int = 40,
    summarization_model: str = "together_ai/meta-llama/Llama-3.3-70B-Instruct-Turbo",
    prompts_file: File | str = "prompts.yaml",
) -> str:
    """Main method to conduct research on a topic. Will be used for weave evals."""
    if isinstance(prompts_file, str):
        prompts_file = await File.from_local(prompts_file)

    # Step 1: Generate initial queries
    queries = await generate_research_queries(
        topic=topic,
        planning_model=planning_model,
        json_model=json_model,
        prompts_file=prompts_file,
    )
    queries = [topic, *queries[: max_queries - 1]]
    all_queries = queries.copy()
    logging.info(f"Initial queries: {queries}")

    if len(queries) == 0:
        logging.error("No initial queries generated")
        return "No initial queries generated"

    # Step 2: Perform initial search
    results = await search_all_queries(queries, summarization_model, prompts_file)
    logging.info(f"Initial search complete, found {len(results.results)} results")

    # Step 3: Conduct iterative research within budget
    for iteration in range(budget):
        with flyte.group(f"eval_iteration_{iteration}"):
            # Evaluate if more research is needed
            additional_queries = await evaluate_research_completeness(
                topic=topic,
                results=results,
                queries=all_queries,
                prompts_file=prompts_file,
                planning_model=planning_model,
                json_model=json_model,
            )

            # Filter out empty strings and check if any queries remain
            additional_queries = [q for q in additional_queries if q]
            if not additional_queries:
                logging.info("No need for additional research")
                break

            # for debugging purposes we limit the number of queries
            additional_queries = additional_queries[:max_queries]
            logging.info(f"Additional queries: {additional_queries}")

            # Expand research with new queries
            new_results = await search_all_queries(
                additional_queries, summarization_model, prompts_file
            )
            logging.info(
                f"Follow-up search complete, found {len(new_results.results)} results"
            )

            results = results + new_results
            all_queries.extend(additional_queries)

    # Step 4: Generate final answer
    logging.info(f"Generating final answer for topic: {topic}")
    results = results.dedup()
    logging.info(f"Deduplication complete, kept {len(results.results)} results")
    filtered_results = await filter_results(
        topic=topic,
        results=results,
        prompts_file=prompts_file,
        planning_model=planning_model,
        json_model=json_model,
        max_sources=max_sources,
    )
    logging.info(
        f"LLM Filtering complete, kept {len(filtered_results.results)} results"
    )

    # Generate final answer
    answer = await generate_research_answer(
        topic=topic,
        results=filtered_results,
        remove_thinking_tags=remove_thinking_tags,
        prompts_file=prompts_file,
        answer_model=answer_model,
    )

    return answer
# {{/docs-fragment research_topic}}

# {{docs-fragment main}}
@env.task(report=True)
async def main(
    topic: str = (
        "List the essential requirements for a developer-focused agent orchestration system."
    ),
    prompts_file: File | str = "/root/prompts.yaml",
    budget: int = 2,
    remove_thinking_tags: bool = True,
    max_queries: int = 3,
    answer_model: str = "together_ai/deepseek-ai/DeepSeek-V3",
    planning_model: str = "together_ai/Qwen/Qwen2.5-72B-Instruct-Turbo",
    json_model: str = "together_ai/meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo",
    max_sources: int = 10,
    summarization_model: str = "together_ai/meta-llama/Llama-3.3-70B-Instruct-Turbo",
) -> str:
    if isinstance(prompts_file, str):
        prompts_file = await File.from_local(prompts_file)

    answer = await research_topic(
        topic=topic,
        budget=budget,
        remove_thinking_tags=remove_thinking_tags,
        max_queries=max_queries,
        answer_model=answer_model,
        planning_model=planning_model,
        json_model=json_model,
        max_sources=max_sources,
        summarization_model=summarization_model,
        prompts_file=prompts_file,
    )

    async with prompts_file.open() as fh:
        data = await fh.read()
        yaml_contents = str(data, "utf-8")

    toc_image_url = await generate_toc_image(
        yaml.safe_load(yaml_contents)["data_visualization_prompt"],
        planning_model,
        topic,
    )

    html_content = await generate_html(answer, toc_image_url)
    await flyte.report.replace.aio(html_content, do_flush=True)
    await flyte.report.flush.aio()

    return html_content
# {{/docs-fragment main}}

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
CODE20
flyte create secret TOGETHER_API_KEY <>
flyte create secret TAVILY_API_KEY <>
CODE21
uv run agent.py
CODE22
brew install pandoc
brew install basictex # restart your terminal after install

export TOGETHER_API_KEY=<>
export TAVILY_API_KEY=<>

uv run agent.py
CODE23
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "weave==0.51.51",
#    "datasets==3.6.0",
#    "huggingface-hub==0.32.6",
#    "litellm==1.72.2",
#    "tavily-python==0.7.5",
# ]
# ///

import os

import weave
from agent import research_topic
from datasets import load_dataset
from huggingface_hub import login
from libs.utils.log import AgentLogger
from litellm import completion

import flyte

logging = AgentLogger()

weave.init(project_name="deep-researcher")

env = flyte.TaskEnvironment(name="deep-researcher-eval")

@weave.op
def llm_as_a_judge_scoring(answer: str, output: str, question: str) -> bool:
    prompt = f"""
    Given the following question and answer, evaluate the answer against the correct answer:

    <question>
    {question}
    </question>

    <agent_answer>
    {output}
    </agent_answer>

    <correct_answer>
    {answer}
    </correct_answer>

    Note that the agent answer might be a long text containing a lot of information or it might be a short answer.

    You should read the entire text and think if the agent answers the question somewhere
    in the text. You should try to be flexible with the answer but careful.

    For example, answering with names instead of name and surname is fine.

    The important thing is that the answer of the agent either contains the correct answer or is equal to
    the correct answer.

    <reasoning>
    The agent answer is correct because I can read that ....
    </reasoning>

    <answer>
    1
    </answer>

    Otherwise, return

    <reasoning>
    The agent answer is incorrect because there is ...
    </reasoning>

    <answer>
    0
    </answer>

    """

    messages = [
        {
            "role": "system",
            "content": "You are an helpful assistant that returns a number between 0 and 1.",
        },
        {"role": "user", "content": prompt},
    ]
    answer = (
        completion(
            model="together_ai/meta-llama/Llama-3.3-70B-Instruct-Turbo",
            messages=messages,
            max_tokens=1000,
            temperature=0.0,
        )
        .choices[0]  # type: ignore
        .message["content"]  # type: ignore
    )

    return bool(int(answer.split("<answer>")[1].split("</answer>")[0].strip()))

def authenticate_huggingface():
    """Authenticate with Hugging Face Hub using token from environment variable."""
    token = os.getenv("HUGGINGFACE_TOKEN")
    if not token:
        raise ValueError(
            "HUGGINGFACE_TOKEN environment variable not set. "
            "Please set it with your token from https://huggingface.co/settings/tokens"
        )

    try:
        login(token=token)
        print("Successfully authenticated with Hugging Face Hub")
    except Exception as e:
        raise RuntimeError(f"Failed to authenticate with Hugging Face Hub: {e!s}")

@env.task
async def load_questions(
    dataset_names: list[str] | None = None,
) -> list[dict[str, str]]:
    """
    Load questions from the specified Hugging Face dataset configurations.

    Args:
        dataset_names: List of dataset configurations to load
                      Options:
                          "smolagents:simpleqa",
                          "hotpotqa",
                          "simpleqa",
                          "together-search-bench"
                      If None, all available configurations except hotpotqa will be loaded

    Returns:
        List of question-answer pairs
    """
    if dataset_names is None:
        dataset_names = ["smolagents:simpleqa"]

    all_questions = []

    # Authenticate with Hugging Face Hub (once and for all)
    authenticate_huggingface()

    for dataset_name in dataset_names:
        print(f"Loading dataset: {dataset_name}")

        try:
            if dataset_name == "together-search-bench":
                # Load Together-Search-Bench dataset
                dataset_path = "togethercomputer/together-search-bench"
                ds = load_dataset(dataset_path)
                if "test" in ds:
                    split_data = ds["test"]
                else:
                    print(f"No 'test' split found in dataset at {dataset_path}")
                    continue

                for i in range(len(split_data)):
                    item = split_data[i]
                    question_data = {
                        "question": item["question"],
                        "answer": item["answer"],
                        "dataset": item.get("dataset", "together-search-bench"),
                    }
                    all_questions.append(question_data)

                print(f"Loaded {len(split_data)} questions from together-search-bench dataset")
                continue

            elif dataset_name == "hotpotqa":
                # Load HotpotQA dataset (using distractor version for validation)
                ds = load_dataset("hotpotqa/hotpot_qa", "distractor", trust_remote_code=True)
                split_name = "validation"
            elif dataset_name == "simpleqa":
                ds = load_dataset("basicv8vc/SimpleQA")
                split_name = "test"
            else:
                # Strip "smolagents:" prefix when loading the dataset
                actual_dataset = dataset_name.split(":")[-1]
                ds = load_dataset("smolagents/benchmark-v1", actual_dataset)
                split_name = "test"

        except Exception as e:
            print(f"Failed to load dataset {dataset_name}: {e!s}")
            continue  # Skip this dataset if it fails to load

        print(f"Dataset structure for {dataset_name}: {ds}")
        print(f"Available splits: {list(ds)}")

        split_data = ds[split_name]  # type: ignore

        for i in range(len(split_data)):
            item = split_data[i]

            if dataset_name == "hotpotqa":
                # we remove questions that are easy or medium (if any) just to reduce the number of questions
                if item["level"] != "hard":
                    continue

                question_data = {
                    "question": item["question"],
                    "answer": item["answer"],
                    "dataset": dataset_name,
                }
            elif dataset_name == "simpleqa":
                # Handle SimpleQA dataset format
                question_data = {
                    "question": item["problem"],
                    "answer": item["answer"],
                    "dataset": dataset_name,
                }
            else:
                question_data = {
                    "question": item["question"],
                    "answer": item["true_answer"],
                    "dataset": dataset_name,
                }

            all_questions.append(question_data)

    print(f"Loaded {len(all_questions)} questions in total")
    return all_questions

@weave.op
async def predict(question: str):
    return await research_topic(topic=str(question))

@env.task
async def main(datasets: list[str] = ["together-search-bench"], limit: int | None = 1):
    questions = await load_questions(datasets)

    if limit is not None:
        questions = questions[:limit]
        print(f"Limited to {len(questions)} question(s)")

    evaluation = weave.Evaluation(dataset=questions, scorers=[llm_as_a_judge_scoring])
    await evaluation.evaluate(predict)

if __name__ == "__main__":
    flyte.init_from_config()
    flyte.with_runcontext(raw_data_path="data").run(main)
CODE24
export HUGGINGFACE_TOKEN=<> # https://huggingface.co/settings/tokens
export WANDB_API_KEY=<> # https://wandb.ai/settings

uv run weave_evals.py
```

The script will run all tasks in the pipeline and log the evaluation results to Weights & Biases.
While you can also evaluate individual tasks, this script focuses on end-to-end evaluation of the end-to-end deep research workflow.

![Weave evaluations](https://raw.githubusercontent.com/unionai/unionai-docs-static/main/images/tutorials/deep-research/weave_evals.png)


=== PAGE: https://www.union.ai/docs/v2/union/tutorials/hpo ===

# Hyperparameter optimization

> [!NOTE]
> Code available [here](https://github.com/unionai/unionai-examples/tree/main/v2/tutorials/ml/optimizer.py).

Hyperparameter Optimization (HPO) is a critical step in the machine learning (ML) lifecycle. Hyperparameters are the knobs and dials of a model—values such as learning rates, tree depths, or dropout rates that significantly impact performance but cannot be learned during training. Instead, we must select them manually or optimize them through guided search.

Model developers often enjoy the flexibility of choosing from a wide variety of model types, whether gradient boosted machines (GBMs), generalized linear models (GLMs), deep learning architectures, or dozens of others. A common challenge across all these options is the need to systematically explore model performance across hyperparameter configurations tailored to the specific dataset and task.

Thankfully, this exploration can be automated. Frameworks like [Optuna](https://optuna.org/), [Hyperopt](https://hyperopt.github.io/hyperopt/), and [Ray Tune](https://docs.ray.io/en/latest/tune/index.html) use advanced sampling algorithms to efficiently search the hyperparameter space and identify optimal configurations. HPO may be executed in two distinct ways:

- **Serial HPO** runs one trial at a time, which is easy to set up but can be painfully slow.
- **Parallel HPO** distributes trials across multiple processes. It typically follows a pattern with two parameters: **_N_**, the total number of trials to run, and **_C_**, the maximum number of trials that can run concurrently. Trials are executed asynchronously, and new ones are scheduled based on the results and status of completed or in-progress ones.

However, parallel HPO introduces a new complexity: the need for a centralized state that tracks:

- All past trials (successes and failures)
- All ongoing trials

This state is essential so that the optimization algorithm can make informed decisions about which hyperparameters to try next.

## A better way to run HPO

This is where Flyte shines.

- There's no need to manage a separate centralized database for state tracking, as every objective run is **cached**, **recorded**, and **recoverable** via Flyte's execution engine.
- The entire HPO process is observable in the UI with full lineage and metadata for each trial.
- Each objective is seeded for reproducibility, enabling deterministic trial results.
- If the main optimization task crashes or is terminated, **Flyte can resume from the last successful or failed trial, making the experiment highly fault-tolerant**.
- Trial functions can be strongly typed, enabling rich, flexible hyperparameter spaces while maintaining strict type safety across trials.

In this example, we combine Flyte with Optuna to optimize a `RandomForestClassifier` on the Iris dataset. Each trial runs in an isolated task, and the optimization process is orchestrated asynchronously, with Flyte handling the underlying scheduling, retries, and caching.

## Declare dependencies

We start by declaring a Python environment using Python 3.13 and specifying our runtime dependencies.

```
# /// script
requires-python = "==3.13"
dependencies = [
   "optuna>=4.0.0,<5.0.0",
   "flyte>=2.0.0b0",
   "scikit-learn==1.7.0",
]
# ///
```

With the environment defined, we begin by importing standard library and third-party modules necessary for both the ML task and distributed execution.

```
import asyncio
import typing
from collections import Counter
from typing import Optional, Union
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/ml/optimizer.py*

These standard library imports are essential for asynchronous execution (`asyncio`), type annotations (`typing`, `Optional`, `Union`), and aggregating trial state counts (`Counter`).

```
import optuna
from optuna import Trial
from sklearn.datasets import load_iris
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import cross_val_score
from sklearn.utils import shuffle
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/ml/optimizer.py*

We use Optuna for hyperparameter optimization and several utilities from scikit-learn to prepare data (`load_iris`), define the model (`RandomForestClassifier`), evaluate it (`cross_val_score`), and shuffle the dataset for randomness (`shuffle`).

```
import flyte
import flyte.errors
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/ml/optimizer.py*

Flyte is our orchestration framework. We use it to define tasks, manage resources, and recover from execution errors.

## Define the task environment

We define a Flyte task environment called `driver`, which encapsulates metadata, compute resources, the container image context needed for remote execution, and caching behavior.

```
driver = flyte.TaskEnvironment(
    name="driver",
    resources=flyte.Resources(cpu=1, memory="250Mi"),
    image=flyte.Image.from_uv_script(__file__, name="optimizer"),
    cache="auto",
)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/ml/optimizer.py*

This environment specifies that the tasks will run with 1 CPU and 250Mi of memory, the image is built using the current script (`__file__`), and caching is enabled.

<p>
  You can configure the Flyte task environment to reuse containers across multiple executions by setting the
  <code>reusable</code> field to
  <code>flyte.ReusePolicy(replicas=..., idle_ttl=...)</code>. This is especially useful when the final objective
  computations are short-lived, as it avoids unnecessary container spin-up costs. Learn more about reusable containers
  <a href="../../user-guide/reusable-containers/">here</a>.
</p>

## Define the optimizer

Next, we define an `Optimizer` class that handles parallel execution of Optuna trials using async coroutines. This class abstracts the full optimization loop and supports concurrent trial execution with live logging.

```
class Optimizer:
    def __init__(
        self,
        objective: callable,
        n_trials: int,
        concurrency: int = 1,
        delay: float = 0.1,
        study: Optional[optuna.Study] = None,
        log_delay: float = 0.1,
    ):
        self.n_trials: int = n_trials
        self.concurrency: int = concurrency
        self.objective: typing.Callable = objective
        self.delay: float = delay
        self.log_delay = log_delay

        self.study = study if study else optuna.create_study()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/ml/optimizer.py*

We pass the `objective` function, number of trials to run (`n_trials`), and maximum parallel trials (`concurrency`). The optional delay throttles execution between trials, while `log_delay` controls how often logging runs. If no existing Optuna Study is provided, a new one is created automatically.

```
    async def log(self):
        while True:
            await asyncio.sleep(self.log_delay)

            counter = Counter()

            for trial in self.study.trials:
                counter[trial.state.name.lower()] += 1

            counts = dict(counter, queued=self.n_trials - len(self))

            # print items in dictionary in a readable format
            formatted = [f"{name}: {count}" for name, count in counts.items()]
            print(f"{'    '.join(formatted)}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/ml/optimizer.py*

This method periodically prints the number of trials in each state (e.g., running, complete, fail). It keeps users informed of ongoing optimization progress and is invoked as a background task when logging is enabled.

![Optuna logging](https://raw.githubusercontent.com/unionai/unionai-docs-static/main/images/tutorials/hpo/logging.png)
_Logs are streamed live as the execution progresses._

```
    async def spawn(self, semaphore: asyncio.Semaphore):
        async with semaphore:
            trial: Trial = self.study.ask()

            try:
                print("Starting trial", trial.number)

                params = {
                    "n_estimators": trial.suggest_int("n_estimators", 10, 200),
                    "max_depth": trial.suggest_int("max_depth", 2, 20),
                    "min_samples_split": trial.suggest_float(
                        "min_samples_split", 0.1, 1.0
                    ),
                }

                output = await self.objective(params)

                self.study.tell(trial, output, state=optuna.trial.TrialState.COMPLETE)
            except flyte.errors.RuntimeUserError as e:
                print(f"Trial {trial.number} failed: {e}")

                self.study.tell(trial, state=optuna.trial.TrialState.FAIL)

            await asyncio.sleep(self.delay)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/ml/optimizer.py*

Each call to `spawn` runs a single Optuna trial. The `semaphore` ensures that only a fixed number of concurrent trials are active at once, respecting the `concurrency` parameter. We first ask Optuna for a new trial and generate a parameter dictionary by querying the trial object for suggested hyperparameters. The trial is then evaluated by the objective function. If successful, we mark it as `COMPLETE`. If the trial fails due to a `RuntimeUserError` from Flyte, we log and record the failure in the Optuna study.

```
    async def __call__(self):
        # create semaphore to manage concurrency
        semaphore = asyncio.Semaphore(self.concurrency)

        # create list of async trials
        trials = [self.spawn(semaphore) for _ in range(self.n_trials)]

        logger: Optional[asyncio.Task] = None
        if self.log_delay:
            logger = asyncio.create_task(self.log())

        # await all trials to complete
        await asyncio.gather(*trials)

        if self.log_delay and logger:
            logger.cancel()
            try:
                await logger
            except asyncio.CancelledError:
                pass
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/ml/optimizer.py*

The `__call__` method defines the overall async optimization routine. It creates the semaphore, spawns `n_trials` coroutines, and optionally starts the background logging task. All trials are awaited with `asyncio.gather`.

```
    def __len__(self) -> int:
        """Return the number of trials in history."""
        return len(self.study.trials)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/ml/optimizer.py*

This method simply allows us to query the number of trials already associated with the study.

## Define the objective function

The objective task defines how we evaluate a particular set of hyperparameters. It's an async task, allowing for caching, tracking, and recoverability across executions.

```
@driver.task
async def objective(params: dict[str, Union[int, float]]) -> float:
    data = load_iris()
    X, y = shuffle(data.data, data.target, random_state=42)

    clf = RandomForestClassifier(
        n_estimators=params["n_estimators"],
        max_depth=params["max_depth"],
        min_samples_split=params["min_samples_split"],
        random_state=42,
        n_jobs=-1,
    )

    # Use cross-validation to evaluate performance
    score = cross_val_score(clf, X, y, cv=3, scoring="accuracy").mean()

    return score.item()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/ml/optimizer.py*

We use the Iris dataset as a toy classification problem. The input params dictionary contains the trial's hyperparameters, which we unpack into a `RandomForestClassifier`. We shuffle the dataset for randomness, and compute a 3-fold cross-validation accuracy.

## Define the main optimization loop

The optimize task is the main driver of our optimization experiment. It creates the `Optimizer` instance and invokes it.

```
@driver.task
async def optimize(
    n_trials: int = 20,
    concurrency: int = 5,
    delay: float = 0.05,
    log_delay: float = 0.1,
) -> dict[str, Union[int, float]]:
    optimizer = Optimizer(
        objective=objective,
        n_trials=n_trials,
        concurrency=concurrency,
        delay=delay,
        log_delay=log_delay,
        study=optuna.create_study(
            direction="maximize", sampler=optuna.samplers.TPESampler(seed=42)
        ),
    )

    await optimizer()

    best = optimizer.study.best_trial

    print("✅ Best Trial")
    print("  Number :", best.number)
    print("  Params :", best.params)
    print("  Score  :", best.value)

    return best.params
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/ml/optimizer.py*

We configure a `TPESampler` for Optuna and `seed` it for determinism. After running all trials, we extract the best-performing trial and print its parameters and score. Returning the best params allows downstream tasks or clients to use the tuned model.

## Run the experiment

Finally, we include an executable entry point to run this optimization using `flyte.run`.

```
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(optimize, 100, 10)
    print(run.url)
    run.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/tutorials/ml/optimizer.py*

We load Flyte config from `config.yaml`, launch the optimize task with 100 trials and concurrency of 10, and print a link to view the execution in the Flyte UI.

![HPO execution](https://raw.githubusercontent.com/unionai/unionai-docs-static/main/images/tutorials/hpo/execution.png)
_Each objective run is cached, recorded, and recoverable. With concurrency set to 10, only 10 trials execute in parallel at any given time._


=== PAGE: https://www.union.ai/docs/v2/union/integrations ===

# Integrations

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

Flyte 2 is designed to be extensible by default. While the core platform covers the most common orchestration needs, many production workloads require specialized infrastructure, external services or execution semantics that go beyond the core runtime.

Flyte 2 exposes these capabilities through integrations.

Under the hood, integrations are implemented using Flyte 2's plugin system, which provides a consistent way to extend the platform without modifying core execution logic.

An integration allows you to declaratively enable new capabilities such as distributed compute frameworks or third-party services without manually managing infrastructure. You specify what you need, and Flyte takes care of how it is provisioned, used and cleaned up.

This page covers:

- The types of integrations Flyte 2 supports today
- How integrations fit into Flyte 2's execution model
- How to use integrations in your tasks
- The integrations available out of the box

If you need functionality that doesn't exist yet, Flyte 2's plugin system is intentionally open-ended. You can build and register your own integrations using the same architecture described here.

## Integration categories

Flyte 2 integrations fall into the following categories:

1. **Distributed compute**: Provision transient compute clusters to run tasks across multiple nodes, with automatic lifecycle management.
2. **Agentic AI**: Support for various common aspects of agentic AI applications.
3. **Experiment tracking**: Integrate with experiment tracking platforms for logging metrics, parameters, and artifacts.
4. **Connectors**: Stateless, long-running services that receive execution requests via gRPC and then submit work to external (or internal) systems.
5. **LLM Serving**: Deploy and serve large language models with an OpenAI-compatible API.

## Distributed compute

Distributed compute integrations allow tasks to run on dynamically provisioned clusters. These clusters are created just-in-time, scoped to the task execution and torn down automatically when the task completes.

This enables large-scale parallelism without requiring users to operate or maintain long-running infrastructure.

### Supported distributed compute integrations

| Plugin               | Description                                      | Common use cases                                       |
| -------------------- | ------------------------------------------------ | ------------------------------------------------------ |
| [Ray](./ray/_index)         | Provisions Ray clusters via KubeRay              | Distributed Python, ML training, hyperparameter tuning |
| [Spark](./spark/_index)     | Provisions Spark clusters via Spark Operator     | Large-scale data processing, ETL pipelines             |
| [Dask](./dask/_index)       | Provisions Dask clusters via Dask Operator       | Parallel Python workloads, dataframe operations        |
| [PyTorch](./pytorch/_index) | Distributed PyTorch training with elastic launch | Single-node and multi-node training                    |

Each plugin encapsulates:

- Cluster provisioning
- Resource configuration
- Networking and service discovery
- Lifecycle management and teardown

From the task author's perspective, these details are abstracted away.

### How the plugin system works

At a high level, Flyte 2's distributed compute plugin architecture follows a simple and consistent pattern.

#### 1. Registration

Each plugin registers itself with Flyte 2's core plugin registry:

- **`TaskPluginRegistry`**: The central registry for all distributed compute plugins
- Each plugin declares:
  - Its configuration schema
  - How that configuration maps to execution behavior

This registration step makes the plugin discoverable by the runtime.

#### 2. Task environments and plugin configuration

Integrations are activated through a `TaskEnvironment`.

A `TaskEnvironment` bundles:

- A container image
- Execution settings
- A plugin configuration object enabled with `plugin_config`

The plugin configuration describes _what_ infrastructure or integration the task requires.

#### 3. Automatic provisioning and execution

When a task associated with a `TaskEnvironment` runs:

1. Flyte inspects the environment's plugin configuration
2. The plugin provisions the required infrastructure or integration
3. The task executes with access to that capability
4. Flyte cleans up all transient resources after completion

### Example: Using the Dask plugin

Below is a complete example showing how a task gains access to a Dask cluster simply by running inside an environment configured with the Dask plugin.

```python
from flyteplugins.dask import Dask, WorkerGroup
import flyte

# Define the Dask cluster configuration
dask_config = Dask(
    workers=WorkerGroup(number_of_workers=4)
)

# Create a task environment that enables Dask
env = flyte.TaskEnvironment(
    name="dask_env",
    plugin_config=dask_config,
    image=image,
)

# Any task in this environment has access to the Dask cluster
@env.task
async def process_data(data: list) -> list:
    from distributed import Client

    client = Client()  # Automatically connects to the provisioned cluster
    futures = client.map(transform, data)
    return client.gather(futures)
```

When `process_data` executes, Flyte performs the following steps:

1. Provisions a Dask cluster with 4 workers
2. Executes the task with network access to the cluster
3. Tears down the cluster once the task completes

No cluster management logic appears in the task code. The task only expresses intent.

### Key design principle

All distributed compute integrations follow the same mental model:

- You declare the required capability via configuration
- You attach that configuration to a task environment
- Tasks decorated with that environment automatically gain access to the capability

This makes it easy to swap execution backends or introduce distributed compute incrementally without rewriting workflows.

## Agentic AI

Agentic AI integrations provide drop-in replacements for LLM provider SDKs. They let you use Flyte tasks as agent tools so that tool calls run with full Flyte observability, retries, and caching.

### Supported agentic AI integrations

| Plugin                              | Description                                                  | Common use cases                     |
| ----------------------------------- | ------------------------------------------------------------ | ------------------------------------ |
| [OpenAI](./openai/_index)           | Drop-in replacement for OpenAI Agents SDK `function_tool`    | Agentic workflows with OpenAI models |
| [Anthropic](./anthropic/_index)     | Agent loop and `function_tool` for the Anthropic Claude SDK  | Agentic workflows with Claude        |
| [Gemini](./gemini/_index)           | Agent loop and `function_tool` for the Google Gemini SDK     | Agentic workflows with Gemini        |
| [Code generation](./codegen/_index) | LLM-driven code generation with automatic testing in sandboxes | Data processing, ETL, analysis pipelines |

## Experiment tracking

Experiment tracking integrations let you log metrics, parameters, and artifacts to external tracking platforms during Flyte task execution.

### Supported experiment tracking integrations

| Plugin                               | Description                  | Common use cases                              |
| ------------------------------------ | ---------------------------- | --------------------------------------------- |
| [MLflow](./mlflow/_index)            | MLflow experiment tracking   | Experiment tracking, autologging, model registry |
| [Weights and Biases](./wandb/_index) | Weights & Biases integration | Experiment tracking and hyperparameter tuning |

## Connectors

Connectors are stateless, long‑running services that receive execution requests via gRPC and then submit work to external (or internal) systems. Each connector runs as its own Kubernetes deployment, and is triggered when a Flyte task of the matching type is executed.

Although they normally run inside the control plane, you can also run connectors locally as long as the required secrets/credentials are present locally. This is useful because connectors are just Python services that can be spawned in‑process.

Connectors are designed to scale horizontally and reduce load on the core Flyte backend because they execute _outside_ the core system. This decoupling makes connectors efficient, resilient, and easy to iterate on. You can even test them locally without modifying backend configuration, which reduces friction during development.

### Supported connectors

| Connector                          | Description                                    | Common use cases                         |
| ---------------------------------- | ---------------------------------------------- | ---------------------------------------- |
| [Snowflake](./snowflake/_index)    | Run SQL queries on Snowflake asynchronously    | Data warehousing, ETL, analytics queries |
| [BigQuery](./bigquery/_index)      | Run SQL queries on Google BigQuery             | Data warehousing, ETL, analytics queries |
| [Databricks](./databricks/_index)  | Run PySpark jobs on Databricks clusters        | Large-scale data processing, Spark ETL   |

### Creating a new connector

If none of the existing connectors meet your needs, you can build your own.

> [!NOTE]
> Connectors communicate via Protobuf, so in theory they can be implemented in any language.
> Today, only **Python** connectors are supported.

### Async connector interface

To implement a new async connector, extend `AsyncConnector` and implement the following methods, all of which must be idempotent:

| Method   | Purpose                                                     |
| -------- | ----------------------------------------------------------- |
| `create` | Launch the external job (via REST, gRPC, SDK, or other API) |
| `get`    | Fetch current job state (return job status or output)       |
| `delete` | Delete / cancel the external job                            |

To test the connector locally, the connector task should inherit from
[AsyncConnectorExecutorMixin](https://github.com/flyteorg/flyte-sdk/blob/1d49299294cd5e15385fe8c48089b3454b7a4cd1/src/flyte/connectors/_connector.py#L206). This mixin simulates how the Flyte 2 system executes asynchronous connector tasks, making it easier to validate your connector implementation before deploying it.

### Example: Model training connector

The following example implements a connector that launches a model training job on an external training service.

```python
import typing
from dataclasses import dataclass

import httpx
from flyte.connectors import AsyncConnector, Resource, ResourceMeta
from flyteidl2.core.execution_pb2 import TaskExecution, TaskLog
from flyteidl2.core.tasks_pb2 import TaskTemplate
from google.protobuf import json_format

@dataclass
class ModelTrainJobMeta(ResourceMeta):
    job_id: str
    endpoint: str

class ModelTrainingConnector(AsyncConnector):
    """
    Example connector that launches a ML model training job on an external training service.

    POST → launch training job
    GET  → poll training progress
    DELETE → cancel training job
    """

    name = "Model Training Connector"
    task_type_name = "external_model_training"
    metadata_type = ModelTrainJobMeta

    async def create(
        self,
        task_template: TaskTemplate,
        inputs: typing.Optional[typing.Dict[str, typing.Any]],
        **kwargs,
    ) -> ModelTrainJobMeta:
        """
        Submit training job via POST.
        Response returns job_id we later use in get().
        """
        custom = json_format.MessageToDict(task_template.custom) if task_template.custom else None
        async with httpx.AsyncClient() as client:
            r = await client.post(
                custom["endpoint"],
                json={"dataset_uri": inputs["dataset_uri"], "epochs": inputs["epochs"]},
            )
        r.raise_for_status()
        return ModelTrainJobMeta(job_id=r.json()["job_id"], endpoint=custom["endpoint"])

    async def get(self, resource_meta: ModelTrainJobMeta, **kwargs) -> Resource:
        """
        Poll external API until training job finishes.
        Must be safe to call repeatedly.
        """
        async with httpx.AsyncClient() as client:
            r = await client.get(f"{resource_meta.endpoint}/{resource_meta.job_id}")

        data = r.json()

        if data["status"] == "finished":
            return Resource(
                phase=TaskExecution.SUCCEEDED,
                log_links=[TaskLog(name="training-dashboard", uri=f"https://example-mltrain.com/train/{resource_meta.job_id}")],
                outputs={"results": data["results"]},
            )

        return Resource(phase=TaskExecution.RUNNING)

    async def delete(self, resource_meta: ModelTrainJobMeta, **kwargs):
        """
        Optionally call DELETE on external API.
        Safe even if job already completed.
        """
        async with httpx.AsyncClient() as client:
            await client.delete(f"{resource_meta.endpoint}/{resource_meta.job_id}")
```

To use this connector, you should define a task whose `task_type` matches the connector.

```python
import flyte.io
from typing import Any, Dict, Optional

from flyte.extend import TaskTemplate
from flyte.connectors import AsyncConnectorExecutorMixin
from flyte.models import NativeInterface, SerializationContext

class ModelTrainTask(AsyncConnectorExecutorMixin, TaskTemplate):
    _TASK_TYPE = "external_model_training"

    def __init__(
        self,
        name: str,
        endpoint: str,
        **kwargs,
    ):
        super().__init__(
            name=name,
            interface=NativeInterface(
                inputs={"epochs": int, "dataset_uri": str},
                outputs={"results": flyte.io.File},
            ),
            task_type=self._TASK_TYPE,
            **kwargs,
        )
        self.endpoint = endpoint

    def custom_config(self, sctx: SerializationContext) -> Optional[Dict[str, Any]]:
        return {"endpoint": self.endpoint}
```

Here is an example of how to use the `ModelTrainTask`:

```python
import flyte
from flyteplugins.model_training import ModelTrainTask

model_train_task = ModelTrainTask(
    name="model_train",
    endpoint="https://example-mltrain.com",
)

model_train_env = flyte.TaskEnvironment.from_task("model_train_env", model_train_task)

env = flyte.TaskEnvironment(
    name="hello_world",
    resources=flyte.Resources(memory="250Mi"),
    image=flyte.Image.from_debian_base(name="model_training").with_pip_packages(
        "flyteplugins-model-training", pre=True
    ),
    depends_on=[model_train_env],
)

@env.task
def data_prep() -> str:
    return "gs://my-bucket/dataset.csv"

@env.task
def train_model(epochs: int) -> flyte.io.File:
    dataset_uri = data_prep()
    return model_train_task(epochs=epochs, dataset_uri=dataset_uri)
```

### Build a custom connector image

Build a custom image when you're ready to deploy your connector to your cluster.
To build the Docker image for your connector, run the following script:

```python
import asyncio
from flyte import Image
from flyte.extend import ImageBuildEngine

async def build_flyte_connector_bigquery_image(registry: str, name: str, builder: str = "local"):
    """
    Build the SDK default connector image optionally overriding
    the container registry and image name.

    Args:
        registry: e.g. "ghcr.io/my-org" or "123456789012.dkr.ecr.us-west-2.amazonaws.com".
        name:     e.g. "my-connector".
        builder:  e.g. "local" or "remote".
    """

    default_image = Image.from_debian_base(
        registry=registry, name=name
    ).with_pip_packages("flyteintegrations-bigquery", pre=True)
    await ImageBuildEngine.build(default_image, builder=builder)

if __name__ == "__main__":
    print("Building connector image...")
    asyncio.run(
        build_flyte_connector_bigquery_image(
            registry="<YOUR_REGISTRY>", name="flyte-bigquery", builder="local"
        )
    )
```

## LLM Serving

LLM serving integrations let you deploy and serve large language models as Flyte apps with an OpenAI-compatible API. They handle model loading, GPU management, and autoscaling.

### Supported LLM serving integrations

| Plugin                                                            | Description                                           | Common use cases                     |
| ----------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------ |
| **Build apps > SGLang app**  | Deploy models with SGLang's high-throughput runtime   | LLM inference, model serving         |
| **Build apps > vLLM app**      | Deploy models with vLLM's PagedAttention engine       | LLM inference, model serving         |

For full setup instructions including multi-GPU deployment, model prefetching, and autoscaling, see the **Build apps > SGLang app** and **Build apps > vLLM app** pages.

## Subpages
- **Anthropic**
- **BigQuery**
- **Dask**
- **Databricks**
- **Gemini**
- **OpenAI**
- **PyTorch**
- **Ray**
- **Snowflake**
- **Spark**
- **Weights & Biases**
- **Code generation**
- **MLflow**


=== PAGE: https://www.union.ai/docs/v2/union/integrations/anthropic ===

# Anthropic

The Anthropic plugin lets you build agentic workflows with [Claude](https://www.anthropic.com/) on Flyte. It provides a `function_tool` decorator that wraps Flyte tasks as tools that Claude can call, and a `run_agent` function that drives the agent conversation loop.

When Claude calls a tool, the call executes as a Flyte task with full observability, retries, and caching.

## Installation

```bash
pip install flyteplugins-anthropic
```

Requires `anthropic >= 0.40.0`.

## Quick start

```python
import flyte
from flyteplugins.anthropic import function_tool, run_agent

env = flyte.TaskEnvironment(
    name="claude-agent",
    resources=flyte.Resources(cpu=1, memory="250Mi"),
    image=flyte.Image.from_uv_script(__file__, name="anthropic_agent"),
    secrets=flyte.Secret("anthropic_api_key", as_env_var="ANTHROPIC_API_KEY"),
)

@function_tool
@env.task
async def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"The weather in {city} is sunny, 72F"

@env.task
async def main(prompt: str) -> str:
    tools = [get_weather]
    return await run_agent(prompt=prompt, tools=tools)
```

## API

### `function_tool`

Converts a Flyte task, `@flyte.trace`-decorated function, or plain callable into a tool that Claude can invoke.

```python
@function_tool
@env.task
async def my_tool(param: str) -> str:
    """Tool description sent to Claude."""
    ...
```

Can also be called with optional overrides:

```python
@function_tool(name="custom_name", description="Custom description")
@env.task
async def my_tool(param: str) -> str:
    ...
```

Parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| `func` | callable | The function to wrap |
| `name` | `str` | Override the tool name (defaults to the function name) |
| `description` | `str` | Override the tool description (defaults to the docstring) |

> [!NOTE]
> The docstring on each `@function_tool` task is sent to Claude as the tool description. Write clear, concise docstrings.

### `Agent`

A dataclass for bundling agent configuration:

```python
from flyteplugins.anthropic import Agent

agent = Agent(
    name="my-agent",
    instructions="You are a helpful assistant.",
    model="claude-sonnet-4-20250514",
    tools=[get_weather],
    max_tokens=4096,
    max_iterations=10,
)
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `name` | `str` | `"assistant"` | Agent name |
| `instructions` | `str` | `"You are a helpful assistant."` | System prompt |
| `model` | `str` | `"claude-sonnet-4-20250514"` | Claude model ID |
| `tools` | `list[FunctionTool]` | `[]` | Tools available to the agent |
| `max_tokens` | `int` | `4096` | Maximum tokens per response |
| `max_iterations` | `int` | `10` | Maximum tool-call loop iterations |

### `run_agent`

Runs a Claude conversation loop, dispatching tool calls to Flyte tasks until Claude returns a final response.

```python
result = await run_agent(
    prompt="What's the weather in Tokyo?",
    tools=[get_weather],
    model="claude-sonnet-4-20250514",
)
```

You can also pass an `Agent` object:

```python
result = await run_agent(prompt="What's the weather?", agent=agent)
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | `str` | required | User message |
| `tools` | `list[FunctionTool]` | `None` | Tools available to the agent |
| `agent` | `Agent` | `None` | Agent config (overrides individual params) |
| `model` | `str` | `"claude-sonnet-4-20250514"` | Claude model ID |
| `system` | `str` | `None` | System prompt |
| `max_tokens` | `int` | `4096` | Maximum tokens per response |
| `max_iterations` | `int` | `10` | Maximum iterations (prevents infinite loops) |
| `api_key` | `str` | `None` | API key (falls back to `ANTHROPIC_API_KEY` env var) |

## Secrets

Store your Anthropic API key as a Flyte secret and expose it as an environment variable:

```python
secrets=flyte.Secret("anthropic_api_key", as_env_var="ANTHROPIC_API_KEY")
```

## API reference

See the [Anthropic API reference](../../api-reference/integrations/anthropic/_index) for full details.


=== PAGE: https://www.union.ai/docs/v2/union/integrations/bigquery ===

# BigQuery

The BigQuery connector lets you run SQL queries against [Google BigQuery](https://cloud.google.com/bigquery) directly from Flyte tasks. Queries are submitted asynchronously via the BigQuery Jobs API and polled for completion, so they don't block a worker while waiting for results.

The connector supports:

- Parameterized SQL queries with typed inputs
- Google Cloud service account authentication
- Returns query results as DataFrames
- Query cancellation on task abort

## Installation

```bash
pip install flyteplugins-bigquery
```

This installs the Google Cloud BigQuery client libraries.

## Quick start

Here's a minimal example that runs a SQL query on BigQuery:

```python
from flyte.io import DataFrame
from flyteplugins.bigquery import BigQueryConfig, BigQueryTask

config = BigQueryConfig(
    ProjectID="my-gcp-project",
    Location="US",
)

count_users = BigQueryTask(
    name="count_users",
    query_template="SELECT COUNT(*) FROM dataset.users",
    plugin_config=config,
    output_dataframe_type=DataFrame,
)
```

This defines a task called `count_users` that runs the query on the configured BigQuery instance. When executed, the connector:

1. Connects to BigQuery using the provided configuration
2. Submits the query asynchronously via the Jobs API
3. Polls until the query completes or fails

To run the task, create a `TaskEnvironment` from it and execute it locally or remotely:

```python
import flyte

bigquery_env = flyte.TaskEnvironment.from_task("bigquery_env", count_users)

if __name__ == "__main__":
    flyte.init_from_config()

    # Run locally (connector runs in-process, requires credentials locally)
    run = flyte.with_runcontext(mode="local").run(count_users)

    # Run remotely (connector runs on the control plane)
    run = flyte.with_runcontext(mode="remote").run(count_users)

    print(run.url)
```

> [!NOTE]
> The `TaskEnvironment` created by `from_task` does not need an image or pip packages. BigQuery tasks are connector tasks, which means the query executes on the connector service, not in your task container. In `local` mode, the connector runs in-process and requires `flyteplugins-bigquery` and credentials to be available on your machine.

## Configuration

### `BigQueryConfig` parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ProjectID` | `str` | Yes | GCP project ID |
| `Location` | `str` | No | BigQuery region (e.g., `"US"`, `"EU"`) |
| `QueryJobConfig` | `bigquery.QueryJobConfig` | No | Native BigQuery [QueryJobConfig](https://cloud.google.com/python/docs/reference/bigquery/latest/google.cloud.bigquery.job.QueryJobConfig) object for advanced settings |

### `BigQueryTask` parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | `str` | Unique task name |
| `query_template` | `str` | SQL query (whitespace is normalized before execution) |
| `plugin_config` | `BigQueryConfig` | Connection configuration |
| `inputs` | `Dict[str, Type]` | Named typed inputs bound as query parameters |
| `output_dataframe_type` | `Type[DataFrame]` | If set, query results are returned as a `DataFrame` |
| `google_application_credentials` | `str` | Name of the Flyte secret containing the GCP service account JSON key |

## Authentication

Pass the name of a Flyte secret containing your GCP service account JSON key:

```python
query = BigQueryTask(
    name="secure_query",
    query_template="SELECT * FROM dataset.sensitive_data",
    plugin_config=config,
    google_application_credentials="my-gcp-sa-key",
)
```

## Query templating

Use the `inputs` parameter to define typed inputs for your query. Input values are bound as BigQuery `ScalarQueryParameter` values.

### Supported input types

| Python type | BigQuery type |
|-------------|---------------|
| `int` | `INT64` |
| `float` | `FLOAT64` |
| `str` | `STRING` |
| `bool` | `BOOL` |
| `bytes` | `BYTES` |
| `datetime` | `DATETIME` |
| `list` | `ARRAY` |

### Parameterized query example

```python
from flyte.io import DataFrame

events_by_region = BigQueryTask(
    name="events_by_region",
    query_template="SELECT * FROM dataset.events WHERE region = @region AND score > @min_score",
    plugin_config=config,
    inputs={"region": str, "min_score": float},
    output_dataframe_type=DataFrame,
)
```

> [!NOTE]
> The query template is normalized before execution: newlines and tabs are replaced with spaces and consecutive whitespace is collapsed. You can format your queries across multiple lines for readability without affecting execution.

## Retrieving query results

Set `output_dataframe_type` to capture results as a DataFrame:

```python
from flyte.io import DataFrame

top_customers = BigQueryTask(
    name="top_customers",
    query_template="""
        SELECT customer_id, SUM(amount) AS total_spend
        FROM dataset.orders
        GROUP BY customer_id
        ORDER BY total_spend DESC
        LIMIT 100
    """,
    plugin_config=config,
    output_dataframe_type=DataFrame,
)
```

If you don't need query results (for example, DDL statements or INSERT queries), omit `output_dataframe_type`.

## API reference

See the [BigQuery API reference](../../api-reference/integrations/bigquery/_index) for full details.


=== PAGE: https://www.union.ai/docs/v2/union/integrations/dask ===

# Dask

The Dask plugin lets you run [Dask](https://www.dask.org/) jobs natively on Kubernetes. Flyte provisions a transient Dask cluster for each task execution using the [Dask Kubernetes Operator](https://kubernetes.dask.org/en/latest/operator.html) and tears it down on completion.

## When to use this plugin

- Parallel Python workloads that outgrow a single machine
- Distributed DataFrame operations on large datasets
- Workloads that use Dask's task scheduler for arbitrary computation graphs
- Jobs that need to scale NumPy, pandas, or scikit-learn workflows across multiple nodes

## Installation

```bash
pip install flyteplugins-dask
```

Your task image must also include the Dask distributed scheduler:

```python
image = flyte.Image.from_debian_base(name="dask").with_pip_packages("flyteplugins-dask")
```

## Configuration

Create a `Dask` configuration and pass it as `plugin_config` to a `TaskEnvironment`:

```python
from flyteplugins.dask import Dask, Scheduler, WorkerGroup

dask_config = Dask(
    scheduler=Scheduler(),
    workers=WorkerGroup(number_of_workers=4),
)

dask_env = flyte.TaskEnvironment(
    name="dask_env",
    plugin_config=dask_config,
    image=image,
)
```

### `Dask` parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `scheduler` | `Scheduler` | Scheduler pod configuration (defaults to `Scheduler()`) |
| `workers` | `WorkerGroup` | Worker group configuration (defaults to `WorkerGroup()`) |

### `Scheduler` parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `image` | `str` | Custom scheduler image (must include `dask[distributed]`) |
| `resources` | `Resources` | Resource requests for the scheduler pod |

### `WorkerGroup` parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `number_of_workers` | `int` | Number of worker pods (default: `1`) |
| `image` | `str` | Custom worker image (must include `dask[distributed]`) |
| `resources` | `Resources` | Resource requests per worker pod |

> [!NOTE]
> The scheduler and all workers should use the same Python environment to avoid serialization issues.

### Accessing the Dask client

Inside a Dask task, create a `distributed.Client()` with no arguments. It automatically connects to the provisioned cluster:

```python
from distributed import Client

@dask_env.task
async def my_dask_task(n: int) -> list:
    client = Client()
    futures = client.map(lambda x: x + 1, range(n))
    return client.gather(futures)
```

## Example

```python
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-dask",
#    "distributed"
# ]
# main = "hello_dask_nested"
# params = ""
# ///

import asyncio
import typing

from distributed import Client
from flyteplugins.dask import Dask, Scheduler, WorkerGroup

import flyte.remote
import flyte.storage
from flyte import Resources

image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages("flyteplugins-dask")

dask_config = Dask(
    scheduler=Scheduler(),
    workers=WorkerGroup(number_of_workers=4),
)

task_env = flyte.TaskEnvironment(
    name="hello_dask", resources=Resources(cpu=(1, 2), memory=("400Mi", "1000Mi")), image=image
)
dask_env = flyte.TaskEnvironment(
    name="dask_env",
    plugin_config=dask_config,
    image=image,
    resources=Resources(cpu="1", memory="1Gi"),
    depends_on=[task_env],
)

@task_env.task()
async def hello_dask():
    await asyncio.sleep(5)
    print("Hello from the Dask task!")

@dask_env.task
async def hello_dask_nested(n: int = 3) -> typing.List[int]:
    print("running dask task")
    t = asyncio.create_task(hello_dask())
    client = Client()
    futures = client.map(lambda x: x + 1, range(n))
    res = client.gather(futures)
    await t
    return res

if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(hello_dask_nested)
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/integrations/flyte-plugins/dask/dask_example.py*

## API reference

See the [Dask API reference](../../api-reference/integrations/dask/_index) for full details.


=== PAGE: https://www.union.ai/docs/v2/union/integrations/databricks ===

# Databricks

The Databricks plugin lets you run PySpark jobs on [Databricks](https://www.databricks.com/) clusters directly from Flyte tasks. You write normal PySpark code in a Flyte task, and the plugin submits it to Databricks via the [Jobs API 2.1](https://docs.databricks.com/api/workspace/jobs/submit). The connector handles job submission, polling, and cancellation.

The plugin supports:

- Running PySpark tasks on new or existing Databricks clusters
- Full Spark configuration (driver/executor memory, cores, instances)
- Databricks cluster auto-scaling
- API token-based authentication

## Installation

```bash
pip install flyteplugins-databricks
```

This also installs `flyteplugins-spark` as a dependency, since the Databricks plugin extends the Spark plugin.

## Quick start

Create a `Databricks` configuration and pass it as `plugin_config` to a `TaskEnvironment`:

```python
from flyteplugins.databricks import Databricks
import flyte

image = (
    flyte.Image.from_base("databricksruntime/standard:16.4-LTS")
    .clone(name="spark", registry="ghcr.io/flyteorg", extendable=True)
    .with_env_vars({"UV_PYTHON": "/databricks/python3/bin/python"})
    .with_pip_packages("flyteplugins-databricks", pre=True)
)

databricks_conf = Databricks(
    spark_conf={
        "spark.driver.memory": "2000M",
        "spark.executor.memory": "1000M",
        "spark.executor.cores": "1",
        "spark.executor.instances": "2",
        "spark.driver.cores": "1",
    },
    executor_path="/databricks/python3/bin/python",
    databricks_conf={
        "run_name": "flyte databricks plugin",
        "new_cluster": {
            "spark_version": "13.3.x-scala2.12",
            "node_type_id": "m6i.large",
            "autoscale": {"min_workers": 1, "max_workers": 2},
        },
        "timeout_seconds": 3600,
        "max_retries": 1,
    },
    databricks_instance="myaccount.cloud.databricks.com",
    databricks_token="DATABRICKS_TOKEN",
)

databricks_env = flyte.TaskEnvironment(
    name="databricks_env",
    resources=flyte.Resources(cpu=(1, 2), memory=("3000Mi", "5000Mi")),
    plugin_config=databricks_conf,
    image=image,
)
```

Then use the environment to decorate your task:

```python
@databricks_env.task
async def hello_databricks() -> float:
    spark = flyte.ctx().data["spark_session"]
    # Use spark as a normal SparkSession
    count = spark.sparkContext.parallelize(range(100)).count()
    return float(count)
```

## Configuration

The `Databricks` config extends the [Spark](../spark/_index) config with Databricks-specific fields.

### Spark fields (inherited)

| Parameter | Type | Description |
|-----------|------|-------------|
| `spark_conf` | `Dict[str, str]` | Spark configuration key-value pairs |
| `hadoop_conf` | `Dict[str, str]` | Hadoop configuration key-value pairs |
| `executor_path` | `str` | Path to the Python binary on the Databricks cluster (e.g., `/databricks/python3/bin/python`) |
| `applications_path` | `str` | Path to the main application file |

### Databricks-specific fields

| Parameter | Type | Description |
|-----------|------|-------------|
| `databricks_conf` | `Dict[str, Union[str, dict]]` | Databricks [run-submit](https://docs.databricks.com/api/workspace/jobs/submit) job configuration. Must contain either `existing_cluster_id` or `new_cluster` |
| `databricks_instance` | `str` | Your workspace domain (e.g., `myaccount.cloud.databricks.com`). Can also be set via the `FLYTE_DATABRICKS_INSTANCE` env var on the connector |
| `databricks_token` | `str` | Name of the Flyte secret containing the Databricks API token |

### `databricks_conf` structure

The `databricks_conf` dict maps to the Databricks run-submit API payload. Key fields:

| Field | Description |
|-------|-------------|
| `new_cluster` | Cluster spec with `spark_version`, `node_type_id`, `autoscale`, etc. |
| `existing_cluster_id` | ID of an existing cluster to use instead of creating a new one |
| `run_name` | Display name in the Databricks UI |
| `timeout_seconds` | Maximum job duration |
| `max_retries` | Number of retries before marking the job as failed |

The connector automatically injects the Docker image, Spark configuration, and environment variables from the task container into the cluster spec.

## Authentication

Store your Databricks API token as a Flyte secret. The `databricks_token` parameter specifies the secret name:

```python
databricks_conf = Databricks(
    # ...
    databricks_token="DATABRICKS_TOKEN",
)
```

## Accessing the Spark session

Inside a Databricks task, the `SparkSession` is available through the task context, just like the [Spark plugin](../spark/_index):

```python
@databricks_env.task
async def my_databricks_task() -> float:
    spark = flyte.ctx().data["spark_session"]
    df = spark.read.parquet("s3://my-bucket/data.parquet")
    return float(df.count())
```

## API reference

See the [Databricks API reference](../../api-reference/integrations/databricks/_index) for full details.


=== PAGE: https://www.union.ai/docs/v2/union/integrations/gemini ===

# Gemini

The Gemini plugin lets you build agentic workflows with [Gemini](https://ai.google.dev/) on Flyte. It provides a `function_tool` decorator that wraps Flyte tasks as tools that Gemini can call, and a `run_agent` function that drives the agent conversation loop.

When Gemini calls a tool, the call executes as a Flyte task with full observability, retries, and caching. Gemini's native parallel function calling is supported: multiple tool calls in a single turn are all dispatched and their results bundled into one response.

## Installation

```bash
pip install flyteplugins-gemini
```

Requires `google-genai >= 1.0.0`.

## Quick start

```python
import flyte
from flyteplugins.gemini import function_tool, run_agent

env = flyte.TaskEnvironment(
    name="gemini-agent",
    resources=flyte.Resources(cpu=1, memory="250Mi"),
    image=flyte.Image.from_uv_script(__file__, name="gemini_agent"),
    secrets=flyte.Secret("google_api_key", as_env_var="GOOGLE_API_KEY"),
)

@function_tool
@env.task
async def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"The weather in {city} is sunny, 72F"

@env.task
async def main(prompt: str) -> str:
    tools = [get_weather]
    return await run_agent(prompt=prompt, tools=tools)
```

## API

### `function_tool`

Converts a Flyte task, `@flyte.trace`-decorated function, or plain callable into a tool that Gemini can invoke.

```python
@function_tool
@env.task
async def my_tool(param: str) -> str:
    """Tool description sent to Gemini."""
    ...
```

Can also be called with optional overrides:

```python
@function_tool(name="custom_name", description="Custom description")
@env.task
async def my_tool(param: str) -> str:
    ...
```

Parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| `func` | callable | The function to wrap |
| `name` | `str` | Override the tool name (defaults to the function name) |
| `description` | `str` | Override the tool description (defaults to the docstring) |

> [!NOTE]
> The docstring on each `@function_tool` task is sent to Gemini as the tool description. Write clear, concise docstrings.

### `Agent`

A dataclass for bundling agent configuration:

```python
from flyteplugins.gemini import Agent

agent = Agent(
    name="my-agent",
    instructions="You are a helpful assistant.",
    model="gemini-2.5-flash",
    tools=[get_weather],
    max_output_tokens=8192,
    max_iterations=10,
)
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `name` | `str` | `"assistant"` | Agent name |
| `instructions` | `str` | `"You are a helpful assistant."` | System prompt |
| `model` | `str` | `"gemini-2.5-flash"` | Gemini model ID |
| `tools` | `list[FunctionTool]` | `[]` | Tools available to the agent |
| `max_output_tokens` | `int` | `8192` | Maximum tokens per response |
| `max_iterations` | `int` | `10` | Maximum tool-call loop iterations |

### `run_agent`

Runs a Gemini conversation loop, dispatching tool calls to Flyte tasks until Gemini returns a final response.

```python
result = await run_agent(
    prompt="What's the weather in Tokyo?",
    tools=[get_weather],
    model="gemini-2.5-flash",
)
```

You can also pass an `Agent` object:

```python
result = await run_agent(prompt="What's the weather?", agent=agent)
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | `str` | required | User message |
| `tools` | `list[FunctionTool]` | `None` | Tools available to the agent |
| `agent` | `Agent` | `None` | Agent config (overrides individual params) |
| `model` | `str` | `"gemini-2.5-flash"` | Gemini model ID |
| `system` | `str` | `None` | System prompt |
| `max_output_tokens` | `int` | `8192` | Maximum tokens per response |
| `max_iterations` | `int` | `10` | Maximum iterations (prevents infinite loops) |
| `api_key` | `str` | `None` | API key (falls back to `GOOGLE_API_KEY` env var) |

## Secrets

Store your Google API key as a Flyte secret and expose it as an environment variable:

```python
secrets=flyte.Secret("google_api_key", as_env_var="GOOGLE_API_KEY")
```

## API reference

See the [Gemini API reference](../../api-reference/integrations/gemini/_index) for full details.


=== PAGE: https://www.union.ai/docs/v2/union/integrations/openai ===

# OpenAI

The OpenAI plugin provides a drop-in replacement for the [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/) `function_tool` decorator. It lets you use Flyte tasks as tools in agentic workflows so that tool calls run as tracked, reproducible Flyte task executions.

## When to use this plugin

- Building agentic workflows with the OpenAI Agents SDK on Flyte
- You want tool calls to run as Flyte tasks with full observability, retries, and caching
- You want to combine LLM agents with existing Flyte pipelines

## Installation

```bash
pip install flyteplugins-openai
```

Requires `openai-agents >= 0.2.4`.

## Usage

The plugin provides a single decorator, `function_tool`, that wraps Flyte tasks as OpenAI agent tools.

### `function_tool`

When applied to a Flyte task (a function decorated with `@env.task`), `function_tool` makes that task available as an OpenAI `FunctionTool`. The agent can call it like any other tool, and the call executes as a Flyte task.

When applied to a regular function or a `@flyte.trace`-decorated function, it delegates directly to the OpenAI Agents SDK's built-in `function_tool`.

### Basic pattern

1. Define a `TaskEnvironment` with your image and secrets
2. Decorate your task functions with `@function_tool` and `@env.task`
3. Pass the tools to an `Agent`
4. Run the agent from another Flyte task

```python
from agents import Agent, Runner
from flyteplugins.openai.agents import function_tool

env = flyte.TaskEnvironment(
    name="openai_agents",
    resources=flyte.Resources(cpu=1, memory="250Mi"),
    image=flyte.Image.from_uv_script(__file__, name="openai_agents_image"),
    secrets=flyte.Secret("openai_api_key", as_env_var="OPENAI_API_KEY"),
)

@function_tool
@env.task
async def get_weather(city: str) -> Weather:
    """Get the weather for a given city."""
    return Weather(city=city, temperature_range="14-20C", conditions="Sunny")

agent = Agent(
    name="Weather Agent",
    instructions="You are a helpful agent.",
    tools=[get_weather],
)

@env.task
async def main() -> str:
    result = await Runner.run(agent, input="What's the weather in Tokyo?")
    return result.final_output
```

> [!NOTE]
> The docstring on each `@function_tool` task is sent to the LLM as the tool description. Write clear, concise docstrings that describe what the tool does and what its parameters mean.

### Secrets

Store your OpenAI API key as a Flyte secret and expose it as an environment variable:

```python
secrets=flyte.Secret("openai_api_key", as_env_var="OPENAI_API_KEY")
```

## Example

```python
"""OpenAI Agents with Flyte, basic tool example.

Usage:

Create secret:

```
flyte create secret openai_api_key
uv run agents_tools.py
```
"""
# {{docs-fragment uv-script}}

# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-openai>=2.0.0b7",
#    "openai-agents>=0.2.4",
#    "pydantic>=2.10.6",
# ]
# main = "main"
# params = ""
# ///

# {{/docs-fragment uv-script}}

# {{docs-fragment imports-task-env}}
from agents import Agent, Runner
from pydantic import BaseModel

import flyte
from flyteplugins.openai.agents import function_tool

env = flyte.TaskEnvironment(
    name="openai_agents_tools",
    resources=flyte.Resources(cpu=1, memory="250Mi"),
    image=flyte.Image.from_uv_script(__file__, name="openai_agents_image"),
    secrets=flyte.Secret("openai_api_key", as_env_var="OPENAI_API_KEY"),
)

# {{/docs-fragment imports-task-env}}

# {{docs-fragment tools}}
class Weather(BaseModel):
    city: str
    temperature_range: str
    conditions: str

@function_tool
@env.task
async def get_weather(city: str) -> Weather:
    """Get the weather for a given city."""
    return Weather(city=city, temperature_range="14-20C", conditions="Sunny with wind.")

# {{/docs-fragment tools}}

# {{docs-fragment agent}}
agent = Agent(
    name="Hello world",
    instructions="You are a helpful agent.",
    tools=[get_weather],
)

@env.task
async def main() -> str:
    result = await Runner.run(agent, input="What's the weather in Tokyo?")
    print(result.final_output)
    return result.final_output

# {{/docs-fragment agent}}

# {{docs-fragment main}}
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
    run.wait()
# {{/docs-fragment main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/integrations/flyte-plugins/openai/openai/agents_tools.py*

## API reference

See the [OpenAI API reference](../../api-reference/integrations/openai/_index) for full details.

## Subpages
- **OpenAI > Agent tools**


=== PAGE: https://www.union.ai/docs/v2/union/integrations/openai/agent_tools ===

# Agent tools

In this example, we will use the `openai-agents` library to create a simple agent that can use tools to perform tasks.
This example is based on the [basic tools example](https://github.com/openai/openai-agents-python/blob/main/examples/basic/tools.py) example from the `openai-agents-python` repo.

First, create an OpenAI API key, which you can get from the [OpenAI website](https://platform.openai.com/account/api-keys).
Then, create a secret on your Flyte cluster with:

```
flyte create secret OPENAI_API_KEY --value <your-api-key>
```

Then, we'll use `uv script` to specify our dependencies.

```
"""OpenAI Agents with Flyte, basic tool example.

Usage:

Create secret:

```
flyte create secret openai_api_key
uv run agents_tools.py
```
"""
# {{docs-fragment uv-script}}

# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-openai>=2.0.0b7",
#    "openai-agents>=0.2.4",
#    "pydantic>=2.10.6",
# ]
# main = "main"
# params = ""
# ///

# {{/docs-fragment uv-script}}

# {{docs-fragment imports-task-env}}
from agents import Agent, Runner
from pydantic import BaseModel

import flyte
from flyteplugins.openai.agents import function_tool

env = flyte.TaskEnvironment(
    name="openai_agents_tools",
    resources=flyte.Resources(cpu=1, memory="250Mi"),
    image=flyte.Image.from_uv_script(__file__, name="openai_agents_image"),
    secrets=flyte.Secret("openai_api_key", as_env_var="OPENAI_API_KEY"),
)

# {{/docs-fragment imports-task-env}}

# {{docs-fragment tools}}
class Weather(BaseModel):
    city: str
    temperature_range: str
    conditions: str

@function_tool
@env.task
async def get_weather(city: str) -> Weather:
    """Get the weather for a given city."""
    return Weather(city=city, temperature_range="14-20C", conditions="Sunny with wind.")

# {{/docs-fragment tools}}

# {{docs-fragment agent}}
agent = Agent(
    name="Hello world",
    instructions="You are a helpful agent.",
    tools=[get_weather],
)

@env.task
async def main() -> str:
    result = await Runner.run(agent, input="What's the weather in Tokyo?")
    print(result.final_output)
    return result.final_output

# {{/docs-fragment agent}}

# {{docs-fragment main}}
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
    run.wait()
# {{/docs-fragment main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/integrations/flyte-plugins/openai/openai/agents_tools.py*

Next, we'll import the libraries and create a `TaskEnvironment`, which we need to run the example:

```
"""OpenAI Agents with Flyte, basic tool example.

Usage:

Create secret:

```
flyte create secret openai_api_key
uv run agents_tools.py
```
"""
# {{docs-fragment uv-script}}

# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-openai>=2.0.0b7",
#    "openai-agents>=0.2.4",
#    "pydantic>=2.10.6",
# ]
# main = "main"
# params = ""
# ///

# {{/docs-fragment uv-script}}

# {{docs-fragment imports-task-env}}
from agents import Agent, Runner
from pydantic import BaseModel

import flyte
from flyteplugins.openai.agents import function_tool

env = flyte.TaskEnvironment(
    name="openai_agents_tools",
    resources=flyte.Resources(cpu=1, memory="250Mi"),
    image=flyte.Image.from_uv_script(__file__, name="openai_agents_image"),
    secrets=flyte.Secret("openai_api_key", as_env_var="OPENAI_API_KEY"),
)

# {{/docs-fragment imports-task-env}}

# {{docs-fragment tools}}
class Weather(BaseModel):
    city: str
    temperature_range: str
    conditions: str

@function_tool
@env.task
async def get_weather(city: str) -> Weather:
    """Get the weather for a given city."""
    return Weather(city=city, temperature_range="14-20C", conditions="Sunny with wind.")

# {{/docs-fragment tools}}

# {{docs-fragment agent}}
agent = Agent(
    name="Hello world",
    instructions="You are a helpful agent.",
    tools=[get_weather],
)

@env.task
async def main() -> str:
    result = await Runner.run(agent, input="What's the weather in Tokyo?")
    print(result.final_output)
    return result.final_output

# {{/docs-fragment agent}}

# {{docs-fragment main}}
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
    run.wait()
# {{/docs-fragment main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/integrations/flyte-plugins/openai/openai/agents_tools.py*

## Define the tools

We'll define a tool that can get weather information for a
given city. In this case, we'll use a toy function that returns a hard-coded `Weather` object.

```
"""OpenAI Agents with Flyte, basic tool example.

Usage:

Create secret:

```
flyte create secret openai_api_key
uv run agents_tools.py
```
"""
# {{docs-fragment uv-script}}

# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-openai>=2.0.0b7",
#    "openai-agents>=0.2.4",
#    "pydantic>=2.10.6",
# ]
# main = "main"
# params = ""
# ///

# {{/docs-fragment uv-script}}

# {{docs-fragment imports-task-env}}
from agents import Agent, Runner
from pydantic import BaseModel

import flyte
from flyteplugins.openai.agents import function_tool

env = flyte.TaskEnvironment(
    name="openai_agents_tools",
    resources=flyte.Resources(cpu=1, memory="250Mi"),
    image=flyte.Image.from_uv_script(__file__, name="openai_agents_image"),
    secrets=flyte.Secret("openai_api_key", as_env_var="OPENAI_API_KEY"),
)

# {{/docs-fragment imports-task-env}}

# {{docs-fragment tools}}
class Weather(BaseModel):
    city: str
    temperature_range: str
    conditions: str

@function_tool
@env.task
async def get_weather(city: str) -> Weather:
    """Get the weather for a given city."""
    return Weather(city=city, temperature_range="14-20C", conditions="Sunny with wind.")

# {{/docs-fragment tools}}

# {{docs-fragment agent}}
agent = Agent(
    name="Hello world",
    instructions="You are a helpful agent.",
    tools=[get_weather],
)

@env.task
async def main() -> str:
    result = await Runner.run(agent, input="What's the weather in Tokyo?")
    print(result.final_output)
    return result.final_output

# {{/docs-fragment agent}}

# {{docs-fragment main}}
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
    run.wait()
# {{/docs-fragment main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/integrations/flyte-plugins/openai/openai/agents_tools.py*

In this code snippet, the `@function_tool` decorator is imported from `flyteplugins.openai.agents`, which is a drop-in replacement for the `@function_tool` decorator from `openai-agents` library.

## Define the agent

Then, we'll define the agent, which calls the tool:

```
"""OpenAI Agents with Flyte, basic tool example.

Usage:

Create secret:

```
flyte create secret openai_api_key
uv run agents_tools.py
```
"""
# {{docs-fragment uv-script}}

# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-openai>=2.0.0b7",
#    "openai-agents>=0.2.4",
#    "pydantic>=2.10.6",
# ]
# main = "main"
# params = ""
# ///

# {{/docs-fragment uv-script}}

# {{docs-fragment imports-task-env}}
from agents import Agent, Runner
from pydantic import BaseModel

import flyte
from flyteplugins.openai.agents import function_tool

env = flyte.TaskEnvironment(
    name="openai_agents_tools",
    resources=flyte.Resources(cpu=1, memory="250Mi"),
    image=flyte.Image.from_uv_script(__file__, name="openai_agents_image"),
    secrets=flyte.Secret("openai_api_key", as_env_var="OPENAI_API_KEY"),
)

# {{/docs-fragment imports-task-env}}

# {{docs-fragment tools}}
class Weather(BaseModel):
    city: str
    temperature_range: str
    conditions: str

@function_tool
@env.task
async def get_weather(city: str) -> Weather:
    """Get the weather for a given city."""
    return Weather(city=city, temperature_range="14-20C", conditions="Sunny with wind.")

# {{/docs-fragment tools}}

# {{docs-fragment agent}}
agent = Agent(
    name="Hello world",
    instructions="You are a helpful agent.",
    tools=[get_weather],
)

@env.task
async def main() -> str:
    result = await Runner.run(agent, input="What's the weather in Tokyo?")
    print(result.final_output)
    return result.final_output

# {{/docs-fragment agent}}

# {{docs-fragment main}}
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
    run.wait()
# {{/docs-fragment main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/integrations/flyte-plugins/openai/openai/agents_tools.py*

## Run the agent

Finally, we'll run the agent. Create `config.yaml` file, which the `flyte.init_from_config()` function will use to connect to
the Flyte cluster:

```bash
flyte create config \
--output ~/.flyte/config.yaml \
--endpoint demo.hosted.unionai.cloud/ \
--project flytesnacks \
--domain development \
--builder remote
```

```
"""OpenAI Agents with Flyte, basic tool example.

Usage:

Create secret:

```
flyte create secret openai_api_key
uv run agents_tools.py
```
"""
# {{docs-fragment uv-script}}

# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-openai>=2.0.0b7",
#    "openai-agents>=0.2.4",
#    "pydantic>=2.10.6",
# ]
# main = "main"
# params = ""
# ///

# {{/docs-fragment uv-script}}

# {{docs-fragment imports-task-env}}
from agents import Agent, Runner
from pydantic import BaseModel

import flyte
from flyteplugins.openai.agents import function_tool

env = flyte.TaskEnvironment(
    name="openai_agents_tools",
    resources=flyte.Resources(cpu=1, memory="250Mi"),
    image=flyte.Image.from_uv_script(__file__, name="openai_agents_image"),
    secrets=flyte.Secret("openai_api_key", as_env_var="OPENAI_API_KEY"),
)

# {{/docs-fragment imports-task-env}}

# {{docs-fragment tools}}
class Weather(BaseModel):
    city: str
    temperature_range: str
    conditions: str

@function_tool
@env.task
async def get_weather(city: str) -> Weather:
    """Get the weather for a given city."""
    return Weather(city=city, temperature_range="14-20C", conditions="Sunny with wind.")

# {{/docs-fragment tools}}

# {{docs-fragment agent}}
agent = Agent(
    name="Hello world",
    instructions="You are a helpful agent.",
    tools=[get_weather],
)

@env.task
async def main() -> str:
    result = await Runner.run(agent, input="What's the weather in Tokyo?")
    print(result.final_output)
    return result.final_output

# {{/docs-fragment agent}}

# {{docs-fragment main}}
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main)
    print(run.url)
    run.wait()
# {{/docs-fragment main}}
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/integrations/flyte-plugins/openai/openai/agents_tools.py*

## Conclusion

In this example, we've seen how to use the `openai-agents` library to create a simple agent that can use tools to perform tasks.

The full code is available [here](https://github.com/unionai/unionai-examples/tree/main/v2/integrations/flyte-plugins/openai/openai).


=== PAGE: https://www.union.ai/docs/v2/union/integrations/pytorch ===

# PyTorch

The PyTorch plugin lets you run distributed [PyTorch](https://pytorch.org/) training jobs natively on Kubernetes. It uses the [Kubeflow Training Operator](https://github.com/kubeflow/training-operator) to manage multi-node training with PyTorch's elastic launch (`torchrun`).

## When to use this plugin

- Single-node or multi-node distributed training with `DistributedDataParallel` (DDP)
- Elastic training that can scale up and down during execution
- Any workload that uses `torch.distributed` for data-parallel or model-parallel training

## Installation

```bash
pip install flyteplugins-pytorch
```

## Configuration

Create an `Elastic` configuration and pass it as `plugin_config` to a `TaskEnvironment`:

```python
from flyteplugins.pytorch import Elastic

torch_env = flyte.TaskEnvironment(
    name="torch_env",
    resources=flyte.Resources(cpu=(1, 2), memory=("1Gi", "2Gi")),
    plugin_config=Elastic(
        nnodes=2,
        nproc_per_node=1,
    ),
    image=image,
)
```

### `Elastic` parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `nnodes` | `int` or `str` | **Required.** Number of nodes. Use an int for a fixed count or a range string (e.g., `"2:4"`) for elastic training |
| `nproc_per_node` | `int` | **Required.** Number of processes (workers) per node |
| `rdzv_backend` | `str` | Rendezvous backend: `"c10d"` (default), `"etcd"`, or `"etcd-v2"` |
| `max_restarts` | `int` | Maximum worker group restarts (default: `3`) |
| `monitor_interval` | `int` | Agent health check interval in seconds (default: `3`) |
| `run_policy` | `RunPolicy` | Job run policy (cleanup, TTL, deadlines, retries) |

### `RunPolicy` parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `clean_pod_policy` | `str` | Pod cleanup policy: `"None"`, `"all"`, or `"Running"` |
| `ttl_seconds_after_finished` | `int` | Seconds to keep pods after job completion |
| `active_deadline_seconds` | `int` | Maximum time the job can run (seconds) |
| `backoff_limit` | `int` | Number of retries before marking the job as failed |

### NCCL tuning parameters

The plugin includes built-in NCCL timeout tuning to reduce failure-detection latency (PyTorch defaults to 1800 seconds):

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `nccl_heartbeat_timeout_sec` | `int` | `300` | NCCL heartbeat timeout (seconds) |
| `nccl_async_error_handling` | `bool` | `False` | Enable async NCCL error handling |
| `nccl_collective_timeout_sec` | `int` | `None` | Timeout for NCCL collective operations |
| `nccl_enable_monitoring` | `bool` | `True` | Enable NCCL monitoring |

### Writing a distributed training task

Tasks using this plugin do not need to be `async`. Initialize the process group and use `DistributedDataParallel` as you normally would with `torchrun`:

```python
import torch
import torch.distributed
from torch.nn.parallel import DistributedDataParallel as DDP

@torch_env.task
def train(epochs: int) -> float:
    torch.distributed.init_process_group("gloo")
    model = DDP(MyModel())
    # ... training loop ...
    return final_loss
```

> [!NOTE]
> When `nnodes=1`, the task runs as a regular Python task (no Kubernetes training job is created). Set `nnodes >= 2` for multi-node distributed training.

## Example

```python
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-pytorch",
#    "torch"
# ]
# main = "torch_distributed_train"
# params = "3"
# ///

import typing

import torch
import torch.distributed
import torch.nn as nn
import torch.optim as optim
from flyteplugins.pytorch.task import Elastic
from torch.nn.parallel import DistributedDataParallel as DDP
from torch.utils.data import DataLoader, DistributedSampler, TensorDataset

import flyte

image = flyte.Image.from_debian_base(name="torch").with_pip_packages("flyteplugins-pytorch", pre=True)

torch_env = flyte.TaskEnvironment(
    name="torch_env",
    resources=flyte.Resources(cpu=(1, 2), memory=("1Gi", "2Gi")),
    plugin_config=Elastic(
        nproc_per_node=1,
        # if you want to do local testing set nnodes=1
        nnodes=2,
    ),
    image=image,
)

class LinearRegressionModel(nn.Module):
    def __init__(self):
        super().__init__()
        self.linear = nn.Linear(1, 1)

    def forward(self, x):
        return self.linear(x)

def prepare_dataloader(rank: int, world_size: int, batch_size: int = 2) -> DataLoader:
    """
    Prepare a DataLoader with a DistributedSampler so each rank
    gets a shard of the dataset.
    """
    # Dummy dataset
    x_train = torch.tensor([[1.0], [2.0], [3.0], [4.0]])
    y_train = torch.tensor([[3.0], [5.0], [7.0], [9.0]])
    dataset = TensorDataset(x_train, y_train)

    # Distributed-aware sampler
    sampler = DistributedSampler(dataset, num_replicas=world_size, rank=rank, shuffle=True)

    return DataLoader(dataset, batch_size=batch_size, sampler=sampler)

def train_loop(epochs: int = 3) -> float:
    """
    A simple training loop for linear regression.
    """
    torch.distributed.init_process_group("gloo")
    model = DDP(LinearRegressionModel())

    rank = torch.distributed.get_rank()
    world_size = torch.distributed.get_world_size()

    dataloader = prepare_dataloader(
        rank=rank,
        world_size=world_size,
        batch_size=64,
    )

    criterion = nn.MSELoss()
    optimizer = optim.SGD(model.parameters(), lr=0.01)

    final_loss = 0.0

    for _ in range(epochs):
        for x, y in dataloader:
            outputs = model(x)
            loss = criterion(outputs, y)

            optimizer.zero_grad()
            loss.backward()
            optimizer.step()

            final_loss = loss.item()
        if torch.distributed.get_rank() == 0:
            print(f"Loss: {final_loss}")

    return final_loss

@torch_env.task
def torch_distributed_train(epochs: int) -> typing.Optional[float]:
    """
    A nested task that sets up a simple distributed training job using PyTorch's
    """
    print("starting launcher")
    loss = train_loop(epochs=epochs)
    print("Training complete")
    return loss

if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(torch_distributed_train, epochs=3)
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/integrations/flyte-plugins/pytorch/pytorch_example.py*

## API reference

See the [PyTorch API reference](../../api-reference/integrations/pytorch/_index) for full details.


=== PAGE: https://www.union.ai/docs/v2/union/integrations/ray ===

# Ray

The Ray plugin lets you run [Ray](https://www.ray.io/) jobs natively on Kubernetes. Flyte provisions a transient Ray cluster for each task execution using [KubeRay](https://github.com/ray-project/kuberay) and tears it down on completion.

## When to use this plugin

- Distributed Python workloads (parallel computation, data processing)
- ML training with Ray Train or hyperparameter tuning with Ray Tune
- Ray Serve inference workloads
- Any workload that benefits from Ray's actor model or task parallelism

## Installation

```bash
pip install flyteplugins-ray
```

Your task image must also include a compatible version of Ray:

```python
image = (
    flyte.Image.from_debian_base(name="ray")
    .with_pip_packages("ray[default]==2.46.0", "flyteplugins-ray")
)
```

## Configuration

Create a `RayJobConfig` and pass it as `plugin_config` to a `TaskEnvironment`:

```python
from flyteplugins.ray import HeadNodeConfig, RayJobConfig, WorkerNodeConfig

ray_config = RayJobConfig(
    head_node_config=HeadNodeConfig(ray_start_params={"log-color": "True"}),
    worker_node_config=[WorkerNodeConfig(group_name="ray-group", replicas=2)],
    runtime_env={"pip": ["numpy", "pandas"]},
    enable_autoscaling=False,
    shutdown_after_job_finishes=True,
    ttl_seconds_after_finished=300,
)

ray_env = flyte.TaskEnvironment(
    name="ray_env",
    plugin_config=ray_config,
    image=image,
)
```

### `RayJobConfig` parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `worker_node_config` | `List[WorkerNodeConfig]` | **Required.** List of worker group configurations |
| `head_node_config` | `HeadNodeConfig` | Head node configuration (optional) |
| `enable_autoscaling` | `bool` | Enable Ray autoscaler (default: `False`) |
| `runtime_env` | `dict` | Ray runtime environment (pip packages, env vars, etc.) |
| `address` | `str` | Connect to an existing Ray cluster instead of provisioning one |
| `shutdown_after_job_finishes` | `bool` | Shut down the cluster after the job completes (default: `False`) |
| `ttl_seconds_after_finished` | `int` | Seconds to keep the cluster after completion before cleanup |

### `WorkerNodeConfig` parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `group_name` | `str` | **Required.** Name of this worker group |
| `replicas` | `int` | **Required.** Number of worker replicas |
| `min_replicas` | `int` | Minimum replicas (for autoscaling) |
| `max_replicas` | `int` | Maximum replicas (for autoscaling) |
| `ray_start_params` | `Dict[str, str]` | Ray start parameters for workers |
| `requests` | `Resources` | Resource requests per worker |
| `limits` | `Resources` | Resource limits per worker |
| `pod_template` | `PodTemplate` | Full pod template (mutually exclusive with `requests`/`limits`) |

### `HeadNodeConfig` parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `ray_start_params` | `Dict[str, str]` | Ray start parameters for the head node |
| `requests` | `Resources` | Resource requests for the head node |
| `limits` | `Resources` | Resource limits for the head node |
| `pod_template` | `PodTemplate` | Full pod template (mutually exclusive with `requests`/`limits`) |

### Connecting to an existing cluster

To connect to an existing Ray cluster instead of provisioning a new one, set the `address` parameter:

```python
ray_config = RayJobConfig(
    worker_node_config=[WorkerNodeConfig(group_name="ray-group", replicas=2)],
    address="ray://existing-cluster:10001",
)
```

## Examples

The following example shows how to configure Ray in a `TaskEnvironment`. Flyte automatically provisions a Ray cluster for each task using this configuration:

```python
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-ray",
#    "ray[default]==2.46.0"
# ]
# main = "hello_ray_nested"
# params = "3"
# ///

import asyncio
import typing

import ray
from flyteplugins.ray.task import HeadNodeConfig, RayJobConfig, WorkerNodeConfig

import flyte.remote
import flyte.storage

@ray.remote
def f(x):
    return x * x

ray_config = RayJobConfig(
    head_node_config=HeadNodeConfig(ray_start_params={"log-color": "True"}),
    worker_node_config=[WorkerNodeConfig(group_name="ray-group", replicas=2)],
    runtime_env={"pip": ["numpy", "pandas"]},
    enable_autoscaling=False,
    shutdown_after_job_finishes=True,
    ttl_seconds_after_finished=300,
)

image = (
    flyte.Image.from_debian_base(name="ray")
    .with_apt_packages("wget")
    .with_pip_packages("ray[default]==2.46.0", "flyteplugins-ray", "pip", "mypy")
)

task_env = flyte.TaskEnvironment(
    name="hello_ray", resources=flyte.Resources(cpu=(1, 2), memory=("400Mi", "1000Mi")), image=image
)
ray_env = flyte.TaskEnvironment(
    name="ray_env",
    plugin_config=ray_config,
    image=image,
    resources=flyte.Resources(cpu=(3, 4), memory=("3000Mi", "5000Mi")),
    depends_on=[task_env],
)

@task_env.task()
async def hello_ray():
    await asyncio.sleep(20)
    print("Hello from the Ray task!")

@ray_env.task
async def hello_ray_nested(n: int = 3) -> typing.List[int]:
    print("running ray task")
    t = asyncio.create_task(hello_ray())
    futures = [f.remote(i) for i in range(n)]
    res = ray.get(futures)
    await t
    return res

if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(hello_ray_nested)
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/integrations/flyte-plugins/ray/ray_example.py*

The next example demonstrates how Flyte can create ephemeral Ray clusters and run a subtask that connects to an existing Ray cluster:

```python
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-ray",
#    "ray[default]==2.46.0"
# ]
# main = "create_ray_cluster"
# params = ""
# ///

import os
import typing

import ray
from flyteplugins.ray.task import HeadNodeConfig, RayJobConfig, WorkerNodeConfig

import flyte.storage

@ray.remote
def f(x):
    return x * x

ray_config = RayJobConfig(
    head_node_config=HeadNodeConfig(ray_start_params={"log-color": "True"}),
    worker_node_config=[WorkerNodeConfig(group_name="ray-group", replicas=2)],
    enable_autoscaling=False,
    shutdown_after_job_finishes=True,
    ttl_seconds_after_finished=3600,
)

image = (
    flyte.Image.from_debian_base(name="ray")
    .with_apt_packages("wget")
    .with_pip_packages("ray[default]==2.46.0", "flyteplugins-ray")
)

task_env = flyte.TaskEnvironment(
    name="ray_client", resources=flyte.Resources(cpu=(1, 2), memory=("400Mi", "1000Mi")), image=image
)
ray_env = flyte.TaskEnvironment(
    name="ray_cluster",
    plugin_config=ray_config,
    image=image,
    resources=flyte.Resources(cpu=(2, 4), memory=("2000Mi", "4000Mi")),
    depends_on=[task_env],
)

@task_env.task()
async def hello_ray(cluster_ip: str) -> typing.List[int]:
    """
    Run a simple Ray task that connects to an existing Ray cluster.
    """
    ray.init(address=f"ray://{cluster_ip}:10001")
    futures = [f.remote(i) for i in range(5)]
    res = ray.get(futures)
    return res

@ray_env.task
async def create_ray_cluster() -> str:
    """
    Create a Ray cluster and return the head node IP address.
    """
    print("creating ray cluster")
    cluster_ip = os.getenv("MY_POD_IP")
    if cluster_ip is None:
        raise ValueError("MY_POD_IP environment variable is not set")
    return f"{cluster_ip}"

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(create_ray_cluster)
    run.wait()
    print("run url:", run.url)
    print("cluster created, running ray task")
    print("ray address:", run.outputs()[0])
    run = flyte.run(hello_ray, cluster_ip=run.outputs()[0])
    print("run url:", run.url)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/integrations/flyte-plugins/ray/ray_existing_example.py*

## API reference

See the [Ray API reference](../../api-reference/integrations/ray/_index) for full details.


=== PAGE: https://www.union.ai/docs/v2/union/integrations/snowflake ===

# Snowflake

The Snowflake connector lets you run SQL queries against [Snowflake](https://www.snowflake.com/) directly from Flyte tasks. Queries are submitted asynchronously and polled for completion, so they don't block a worker while waiting for results.

The connector supports:

- Parameterized SQL queries with typed inputs
- Key-pair and password-based authentication
- Returns query results as DataFrames
- Automatic links to the Snowflake query dashboard in the Flyte UI
- Query cancellation on task abort

## Installation

```bash
pip install flyteplugins-snowflake
```

This installs the Snowflake Python connector and the `cryptography` library for key-pair authentication.

## Quick start

Here's a minimal example that runs a SQL query on Snowflake:

```python {hl_lines=[2, 4, 12]}
from flyte.io import DataFrame
from flyteplugins.connectors.snowflake import Snowflake, SnowflakeConfig

config = SnowflakeConfig(
    account="myorg-myaccount",
    user="flyte_user",
    database="ANALYTICS",
    schema="PUBLIC",
    warehouse="COMPUTE_WH",
)

count_users = Snowflake(
    name="count_users",
    query_template="SELECT COUNT(*) FROM users",
    plugin_config=config,
    output_dataframe_type=DataFrame,
)
```

This defines a task called `count_users` that runs `SELECT COUNT(*) FROM users` on the configured Snowflake instance. When executed, the connector:

1. Connects to Snowflake using the provided configuration
2. Submits the query asynchronously
3. Polls until the query completes or fails
4. Provides a link to the query in the Snowflake dashboard

![Snowflake Link](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/integrations/snowflake/ui.png)

To run the task, create a `TaskEnvironment` from it and execute it locally or remotely:

```python {hl_lines=3}
import flyte

snowflake_env = flyte.TaskEnvironment.from_task("snowflake_env", count_users)

if __name__ == "__main__":
    flyte.init_from_config()

    # Run locally (connector runs in-process, requires credentials and packages locally)
    run = flyte.with_runcontext(mode="local").run(count_users)

    # Run remotely (connector runs on the control plane)
    run = flyte.with_runcontext(mode="remote").run(count_users)

    print(run.url)
```

> [!NOTE]
> The `TaskEnvironment` created by `from_task` does not need an image or pip packages. Snowflake tasks are connector tasks, which means the query executes on the connector service, not in your task container. In `local` mode, the connector runs in-process and requires `flyteplugins-snowflake` and credentials to be available on your machine. In `remote` mode, the connector runs on the control plane.

## Configuration

The `SnowflakeConfig` dataclass defines the connection settings for your Snowflake instance.

### Required fields

| Field       | Type  | Description                                             |
| ----------- | ----- | ------------------------------------------------------- |
| `account`   | `str` | Snowflake account identifier (e.g. `"myorg-myaccount"`) |
| `database`  | `str` | Target database name                                    |
| `schema`    | `str` | Target schema name (e.g. `"PUBLIC"`)                    |
| `warehouse` | `str` | Compute warehouse to use for query execution            |
| `user`      | `str` | Snowflake username                                      |

### Additional connection parameters

Use `connection_kwargs` to pass any additional parameters supported by the [Snowflake Python connector](https://docs.snowflake.com/en/developer-guide/python-connector/python-connector-api). This is a dictionary that gets forwarded directly to `snowflake.connector.connect()`.

Common options include:

| Parameter       | Type  | Description                                                                |
| --------------- | ----- | -------------------------------------------------------------------------- |
| `role`          | `str` | Snowflake role to use for the session                                      |
| `authenticator` | `str` | Authentication method (e.g. `"snowflake"`, `"externalbrowser"`, `"oauth"`) |
| `token`         | `str` | OAuth token when using `authenticator="oauth"`                             |
| `login_timeout` | `int` | Timeout in seconds for the login request                                   |

Example with a role:

```python {hl_lines=8}
config = SnowflakeConfig(
    account="myorg-myaccount",
    user="flyte_user",
    database="ANALYTICS",
    schema="PUBLIC",
    warehouse="COMPUTE_WH",
    connection_kwargs={
        "role": "DATA_ANALYST",
    },
)
```

## Authentication

The connector supports two authentication approaches: key-pair authentication, and password-based or other authentication methods provided through `connection_kwargs`.

### Key-pair authentication

Key-pair authentication is the recommended approach for automated workloads. Pass the names of the Flyte secrets containing the private key and optional passphrase:

```python {hl_lines=[5, 6]}
query = Snowflake(
    name="secure_query",
    query_template="SELECT * FROM sensitive_data",
    plugin_config=config,
    snowflake_private_key="my-snowflake-private-key",
    snowflake_private_key_passphrase="my-snowflake-pk-passphrase",
)
```

The `snowflake_private_key` parameter is the name of the secret (or secret key) that contains your PEM-encoded private key. The `snowflake_private_key_passphrase` parameter is the name of the secret (or secret key) that contains the passphrase, if your key is encrypted. If your key is not encrypted, omit the passphrase parameter.

The connector decodes the PEM key and converts it to DER format for Snowflake authentication.

> [!NOTE]
> If your credentials are stored in a secret group, you can pass `secret_group` to the `Snowflake` task. The plugin expects `snowflake_private_key` and
> `snowflake_private_key_passphrase` to be keys within the same secret group.

### Password authentication

Send the password via `connection_kwargs`:

```python {hl_lines=8}
config = SnowflakeConfig(
    account="myorg-myaccount",
    user="flyte_user",
    database="ANALYTICS",
    schema="PUBLIC",
    warehouse="COMPUTE_WH",
    connection_kwargs={
        "password": "my-password",
    },
)
```

### OAuth authentication

For OAuth-based authentication, specify the authenticator and token:

```python {hl_lines=["8-9"]}
config = SnowflakeConfig(
    account="myorg-myaccount",
    user="flyte_user",
    database="ANALYTICS",
    schema="PUBLIC",
    warehouse="COMPUTE_WH",
    connection_kwargs={
        "authenticator": "oauth",
        "token": "<oauth-token>",
    },
)
```

## Query templating

Use the `inputs` parameter to define typed inputs for your query. Input values are bound using the `%(param)s` syntax supported by the [Snowflake Python connector](https://docs.snowflake.com/en/developer-guide/python-connector/python-connector-api), which handles type conversion and escaping automatically.

### Supported input types

The `inputs` dictionary maps parameter names to Python values. Supported scalar types include `str`, `int`, `float`, and `bool`.

To insert multiple rows in a single query, you can also provide lists as input values. When using list inputs, be sure to set `batch=True` on the `Snowflake` task. This enables automatic batching, where the inputs are expanded and sent as a single multi-row query instead of you having to write multiple individual statements.

### Batched `INSERT` with list inputs

When `batch=True` is enabled, a parameterized `INSERT` query with list inputs is automatically expanded into a multi-row `VALUES` statement.

Example:

```python
query = "INSERT INTO t (a, b) VALUES (%(a)s, %(b)s)"
inputs = {"a": [1, 2], "b": ["x", "y"]}
```

This is expanded into:

```sql
INSERT INTO t (a, b)
VALUES (%(a_0)s, %(b_0)s), (%(a_1)s, %(b_1)s)
```

with the following flattened parameters:

```python
flat_params = {
    "a_0": 1,
    "b_0": "x",
    "a_1": 2,
    "b_1": "y",
}
```

#### Constraints

- The query must contain exactly one `VALUES (...)` clause.
- All list inputs must have the same non-zero length.

### Parameterized `SELECT`

```python {hl_lines=[5, 7]}
from flyte.io import DataFrame

events_by_date = Snowflake(
    name="events_by_date",
    query_template="SELECT * FROM events WHERE event_date = %(event_date)s",
    plugin_config=config,
    inputs={"event_date": str},
    output_dataframe_type=DataFrame,
)
```

You can call the task with the required inputs:

```python {hl_lines=3}
@env.task
async def fetch_events() -> DataFrame:
    return await events_by_date(event_date="2024-01-15")
```

### Multiple inputs

You can define multiple input parameters of different types:

```python {hl_lines=["4-8", "12-15"]}
filtered_events = Snowflake(
    name="filtered_events",
    query_template="""
        SELECT * FROM events
        WHERE event_date >= %(start_date)s
          AND event_date <= %(end_date)s
          AND region = %(region)s
          AND score > %(min_score)s
    """,
    plugin_config=config,
    inputs={
        "start_date": str,
        "end_date": str,
        "region": str,
        "min_score": float,
    },
    output_dataframe_type=DataFrame,
)
```

> [!NOTE]
> The query template is normalized before execution: newlines and tabs are replaced with spaces, and consecutive whitespace is collapsed. You can format your queries across multiple lines for readability without affecting execution.

## Retrieving query results

If your query produces output, set `output_dataframe_type` to capture the results. `output_dataframe_type` accepts `DataFrame` from `flyte.io`. This is a meta-wrapper type that represents tabular results and can be materialized into a concrete DataFrame implementation using `open()` where you specify the target type and `all()`.

```python {hl_lines=13}
from flyte.io import DataFrame

top_customers = Snowflake(
    name="top_customers",
    query_template="""
        SELECT customer_id, SUM(amount) AS total_spend
        FROM orders
        GROUP BY customer_id
        ORDER BY total_spend DESC
        LIMIT 100
    """,
    plugin_config=config,
    output_dataframe_type=DataFrame,
)
```

At present, only `pandas.DataFrame` is supported. The results are returned directly when you call the task:

```python {hl_lines=6}
import pandas as pd

@env.task
async def analyze_top_customers() -> dict:
    df = await top_customers()
    pandas_df = await df.open(pd.DataFrame).all()
    total_spend = pandas_df["total_spend"].sum()
    return {"total_spend": float(total_spend)}
```

If you specify `pandas.DataFrame` as the `output_dataframe_type`, you do not need to call `open()` and `all()` to materialize the results.

```python {hl_lines=[1, 13, "18-19"]}
import pandas as pd

top_customers = Snowflake(
    name="top_customers",
    query_template="""
        SELECT customer_id, SUM(amount) AS total_spend
        FROM orders
        GROUP BY customer_id
        ORDER BY total_spend DESC
        LIMIT 100
    """,
    plugin_config=config,
    output_dataframe_type=pd.DataFrame,
)

@env.task
async def analyze_top_customers() -> dict:
    df = await top_customers()
    total_spend = df["total_spend"].sum()
    return {"total_spend": float(total_spend)}
```

> [!NOTE]
> Be sure to inject the `SNOWFLAKE_PRIVATE_KEY` and `SNOWFLAKE_PRIVATE_KEY_PASSPHRASE` environment variables as secrets into your downstream tasks, as they must have access to Snowflake credentials in order to retrieve the DataFrame results. More on how you can create secrets **Configure tasks > Secrets**.

If you don't need query results (for example, `DDL` statements or `INSERT` queries), omit `output_dataframe_type`.

## End-to-end example

Here's a complete workflow that uses the Snowflake connector as part of a data pipeline. The workflow creates a staging table, inserts records, queries aggregated results and processes them in a downstream task.

```
import flyte
from flyte.io import DataFrame
from flyteplugins.connectors.snowflake import Snowflake, SnowflakeConfig

config = SnowflakeConfig(
    account="myorg-myaccount",
    user="flyte_user",
    database="ANALYTICS",
    schema="PUBLIC",
    warehouse="COMPUTE_WH",
    connection_kwargs={
        "role": "ETL_ROLE",
    },
)

# Step 1: Create the staging table if it doesn't exist
create_staging = Snowflake(
    name="create_staging",
    query_template="""
        CREATE TABLE IF NOT EXISTS staging.daily_events (
            event_id STRING,
            event_date DATE,
            user_id STRING,
            event_type STRING,
            payload VARIANT
        )
    """,
    plugin_config=config,
    snowflake_private_key="snowflake",
    snowflake_private_key_passphrase="snowflake_passphrase",
)

# Step 2: Insert a record into the staging table
insert_events = Snowflake(
    name="insert_event",
    query_template="""
        INSERT INTO staging.daily_events (event_id, event_date, user_id, event_type)
        VALUES (%(event_id)s, %(event_date)s, %(user_id)s, %(event_type)s)
    """,
    plugin_config=config,
    inputs={
        "event_id": list[str],
        "event_date": list[str],
        "user_id": list[str],
        "event_type": list[str],
    },
    snowflake_private_key="snowflake",
    snowflake_private_key_passphrase="snowflake_passphrase",
    batch=True,
)

# Step 3: Query aggregated results for a given date
daily_summary = Snowflake(
    name="daily_summary",
    query_template="""
        SELECT
            event_type,
            COUNT(*) AS event_count,
            COUNT(DISTINCT user_id) AS unique_users
        FROM staging.daily_events
        WHERE event_date = %(report_date)s
        GROUP BY event_type
        ORDER BY event_count DESC
    """,
    plugin_config=config,
    inputs={"report_date": str},
    output_dataframe_type=DataFrame,
    snowflake_private_key="snowflake",
    snowflake_private_key_passphrase="snowflake_passphrase",
)

# Create environments for all Snowflake tasks
snowflake_env = flyte.TaskEnvironment.from_task(
    "snowflake_env", create_staging, insert_events, daily_summary
)

# Main pipeline environment that depends on the Snowflake task environments
env = flyte.TaskEnvironment(
    name="analytics_env",
    resources=flyte.Resources(memory="512Mi"),
    image=flyte.Image.from_debian_base(name="analytics").with_pip_packages(
        "flyteplugins-snowflake", pre=True
    ),
    secrets=[
        flyte.Secret(key="snowflake", as_env_var="SNOWFLAKE_PRIVATE_KEY"),
        flyte.Secret(
            key="snowflake_passphrase", as_env_var="SNOWFLAKE_PRIVATE_KEY_PASSPHRASE"
        ),
    ],
    depends_on=[snowflake_env],
)

# Step 4: Process the results in Python
@env.task
async def generate_report(summary: DataFrame) -> dict:
    import pandas as pd

    df = await summary.open(pd.DataFrame).all()
    total_events = df["event_count"].sum()
    top_event = df.iloc[0]["event_type"]
    return {
        "total_events": int(total_events),
        "top_event_type": top_event,
        "event_types_count": len(df),
    }

# Compose the pipeline
@env.task
async def run_daily_pipeline(
    event_ids: list[str],
    event_dates: list[str],
    user_ids: list[str],
    event_types: list[str],
) -> dict:
    await create_staging()
    await insert_events(
        event_id=event_ids,
        event_date=event_dates,
        user_id=user_ids,
        event_type=event_types,
    )
    summary = await daily_summary(report_date=event_dates[0])
    return await generate_report(summary=summary)

if __name__ == "__main__":
    flyte.init_from_config()

    # Run locally
    run = flyte.with_runcontext(mode="local").run(
        run_daily_pipeline,
        event_ids=["event-1", "event-2"],
        event_dates=["2023-01-01", "2023-01-02"],
        user_ids=["user-1", "user-2"],
        event_types=["click", "view"],
    )

    # Or run remotely
    run = flyte.with_runcontext(mode="remote").run(
        run_daily_pipeline,
        event_ids=["event-1", "event-2"],
        event_dates=["2023-01-01", "2023-01-02"],
        user_ids=["user-1", "user-2"],
        event_types=["click", "view"],
    )

    print(run.url)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/integrations/connectors/snowflake/example.py*


=== PAGE: https://www.union.ai/docs/v2/union/integrations/spark ===

# Spark

The Spark plugin lets you run [Apache Spark](https://spark.apache.org/) jobs natively on Kubernetes. Flyte manages the full cluster lifecycle: provisioning a transient Spark cluster for each task execution, running the job, and tearing the cluster down on completion.

Under the hood, the plugin uses the [Spark on Kubernetes Operator](https://github.com/GoogleCloudPlatform/spark-on-k8s-operator) to create and manage Spark applications. No external Spark service or long-running cluster is required.

## When to use this plugin

- Large-scale data processing and ETL pipelines
- Jobs that benefit from Spark's distributed execution engine (Spark SQL, PySpark, Spark MLlib)
- Workloads that need Hadoop-compatible storage access (S3, GCS, HDFS)

## Installation

```bash
pip install flyteplugins-spark
```

## Configuration

Create a `Spark` configuration and pass it as `plugin_config` to a `TaskEnvironment`:

```python
from flyteplugins.spark import Spark

spark_config = Spark(
    spark_conf={
        "spark.driver.memory": "3000M",
        "spark.executor.memory": "1000M",
        "spark.executor.cores": "1",
        "spark.executor.instances": "2",
        "spark.driver.cores": "1",
    },
)

spark_env = flyte.TaskEnvironment(
    name="spark_env",
    plugin_config=spark_config,
    image=image,
)
```

### `Spark` parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `spark_conf` | `Dict[str, str]` | Spark configuration key-value pairs (e.g., executor memory, cores, instances) |
| `hadoop_conf` | `Dict[str, str]` | Hadoop configuration key-value pairs (e.g., S3/GCS access settings) |
| `executor_path` | `str` | Path to the Python binary for PySpark executors |
| `applications_path` | `str` | Path to the main Spark application file |
| `driver_pod` | `PodTemplate` | Pod template for the Spark driver pod |
| `executor_pod` | `PodTemplate` | Pod template for the Spark executor pods |

### Accessing the Spark session

Inside a Spark task, the `SparkSession` is available through the task context:

```python
from flyte._context import internal_ctx

@spark_env.task
async def my_spark_task() -> float:
    ctx = internal_ctx()
    spark = ctx.data.task_context.data["spark_session"]
    # Use spark as a normal SparkSession
    df = spark.read.parquet("s3://my-bucket/data.parquet")
    return df.count()
```

### Overriding configuration at runtime

You can override Spark configuration for individual task calls using `.override()`:

```python
from copy import deepcopy

updated_config = deepcopy(spark_config)
updated_config.spark_conf["spark.executor.instances"] = "4"

result = await my_spark_task.override(plugin_config=updated_config)()
```

## Example

```python
# /// script
# requires-python = "==3.13"
# dependencies = [
#    "flyte>=2.0.0b52",
#    "flyteplugins-spark"
# ]
# main = "hello_spark_nested"
# params = "3"
# ///

import random
from copy import deepcopy
from operator import add

from flyteplugins.spark.task import Spark

import flyte.remote
from flyte._context import internal_ctx

image = (
    flyte.Image.from_base("apache/spark-py:v3.4.0")
    .clone(name="spark", python_version=(3, 10), registry="ghcr.io/flyteorg")
    .with_pip_packages("flyteplugins-spark", pre=True)
)

task_env = flyte.TaskEnvironment(
    name="get_pi", resources=flyte.Resources(cpu=(1, 2), memory=("400Mi", "1000Mi")), image=image
)

spark_conf = Spark(
    spark_conf={
        "spark.driver.memory": "3000M",
        "spark.executor.memory": "1000M",
        "spark.executor.cores": "1",
        "spark.executor.instances": "2",
        "spark.driver.cores": "1",
        "spark.kubernetes.file.upload.path": "/opt/spark/work-dir",
        "spark.jars": "https://storage.googleapis.com/hadoop-lib/gcs/gcs-connector-hadoop3-latest.jar,https://repo1.maven.org/maven2/org/apache/hadoop/hadoop-aws/3.2.2/hadoop-aws-3.2.2.jar,https://repo1.maven.org/maven2/com/amazonaws/aws-java-sdk-bundle/1.12.262/aws-java-sdk-bundle-1.12.262.jar",
    },
)

spark_env = flyte.TaskEnvironment(
    name="spark_env",
    resources=flyte.Resources(cpu=(1, 2), memory=("3000Mi", "5000Mi")),
    plugin_config=spark_conf,
    image=image,
    depends_on=[task_env],
)

def f(_):
    x = random.random() * 2 - 1
    y = random.random() * 2 - 1
    return 1 if x**2 + y**2 <= 1 else 0

@task_env.task
async def get_pi(count: int, partitions: int) -> float:
    return 4.0 * count / partitions

@spark_env.task
async def hello_spark_nested(partitions: int = 3) -> float:
    n = 1 * partitions
    ctx = internal_ctx()
    spark = ctx.data.task_context.data["spark_session"]
    count = spark.sparkContext.parallelize(range(1, n + 1), partitions).map(f).reduce(add)

    return await get_pi(count, partitions)

@task_env.task
async def spark_overrider(executor_instances: int = 3, partitions: int = 4) -> float:
    updated_spark_conf = deepcopy(spark_conf)
    updated_spark_conf.spark_conf["spark.executor.instances"] = str(executor_instances)
    return await hello_spark_nested.override(plugin_config=updated_spark_conf)(partitions=partitions)

if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.run(hello_spark_nested)
    print(r.name)
    print(r.url)
    r.wait()
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/integrations/flyte-plugins/spark/spark_example.py*

## API reference

See the [Spark API reference](../../api-reference/integrations/spark/_index) for full details.


=== PAGE: https://www.union.ai/docs/v2/union/integrations/wandb ===

# Weights & Biases

[Weights & Biases](https://wandb.ai) (W&B) is a platform for tracking machine learning experiments, visualizing metrics and optimizing hyperparameters. This plugin integrates W&B with Flyte, enabling you to:

- Automatically initialize W&B runs in your tasks without boilerplate
- Link directly from the Flyte UI to your W&B runs and sweeps
- Share W&B runs across parent and child tasks
- Track distributed training jobs across multiple GPUs and nodes
- Run hyperparameter sweeps with parallel agents

## Installation

```bash
pip install flyteplugins-wandb
```

You also need a W&B API key. Store it as a Flyte secret so your tasks can authenticate with W&B.

## Quick start

Here's a minimal example that logs metrics to W&B from a Flyte task:

```
import flyte

from flyteplugins.wandb import get_wandb_run, wandb_config, wandb_init

env = flyte.TaskEnvironment(
    name="wandb-example",
    image=flyte.Image.from_debian_base(name="wandb-example").with_pip_packages(
        "flyteplugins-wandb"
    ),
    secrets=[flyte.Secret(key="wandb_api_key", as_env_var="WANDB_API_KEY")],
)

@wandb_init
@env.task
async def train_model() -> str:
    wandb_run = get_wandb_run()

    # Your training code here
    for epoch in range(10):
        loss = 1.0 / (epoch + 1)
        wandb_run.log({"epoch": epoch, "loss": loss})

    return "Training complete"

if __name__ == "__main__":
    flyte.init_from_config()

    r = flyte.with_runcontext(
        custom_context=wandb_config(
            project="my-project",
            entity="my-team",
        ),
    ).run(train_model)

    print(f"run url: {r.url}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/integrations/flyte-plugins/wandb/quick_start.py*

This example demonstrates the core pattern:

1. **Define a task environment** with the plugin installed and your W&B API key as a secret
2. **Decorate your task** with `@wandb_init` (must be the outermost decorator, above `@env.task`)
3. **Access the run** with `get_wandb_run()` to log metrics
4. **Provide configuration** via `wandb_config()` when running the task

The plugin handles calling `wandb.init()` and `wandb.finish()` for you, and automatically adds a link to the W&B run in the Flyte UI.

![UI](https://raw.githubusercontent.com/unionai/unionai-docs-static/main/images/integrations/wandb/ui.png)

## What's next

This integration guide is split into focused sections, depending on how you want to use Weights & Biases with Flyte:

- ****Weights & Biases > Experiments****: Create and manage W&B runs from Flyte tasks.
- ****Weights & Biases > Distributed training****: Track experiments across multi-GPU and multi-node training jobs.
- ****Weights & Biases > Sweeps****: Run hyperparameter searches and manage sweep execution from Flyte tasks.
- ****Weights & Biases > Downloading logs****: Download logs and execution metadata from Weights & Biases.
- ****Weights & Biases > Constraints and best practices****: Learn about limitations, edge cases and recommended patterns.
- ****Weights & Biases > Manual integration****: Use Weights & Biases directly in Flyte tasks without decorators or helpers.

> **📝 Note**
>
> We've included additional examples developed while testing edge cases of the plugin [here](https://github.com/flyteorg/flyte-sdk/tree/main/plugins/wandb/examples).

## Subpages
- **Weights & Biases > Experiments**
- **Weights & Biases > Distributed training**
- **Weights & Biases > Sweeps**
- **Weights & Biases > Downloading logs**
- **Weights & Biases > Constraints and best practices**
- **Weights & Biases > Manual integration**


=== PAGE: https://www.union.ai/docs/v2/union/integrations/wandb/experiments ===

# Experiments

The `@wandb_init` decorator automatically initializes a W&B run when your task executes and finishes it when the task completes. This section covers the different ways to use it.

## Basic usage

Apply `@wandb_init` as the outermost decorator on your task:

```python {hl_lines=1}
@wandb_init
@env.task
async def my_task() -> str:
    run = get_wandb_run()
    run.log({"metric": 42})
    return "done"
```

The decorator:

- Calls `wandb.init()` before your task code runs
- Calls `wandb.finish()` after your task completes (or fails)
- Adds a link to the W&B run in the Flyte UI

You can also use it on synchronous tasks:

```python {hl_lines=[1, 3]}
@wandb_init
@env.task
def my_sync_task() -> str:
    run = get_wandb_run()
    run.log({"metric": 42})
    return "done"
```

## Accessing the run object

Use `get_wandb_run()` to access the current W&B run object:

```python {hl_lines=6}
from flyteplugins.wandb import get_wandb_run

@wandb_init
@env.task
async def train() -> str:
    run = get_wandb_run()

    # Log metrics
    run.log({"loss": 0.5, "accuracy": 0.9})

    # Access run properties
    print(f"Run ID: {run.id}")
    print(f"Run URL: {run.url}")
    print(f"Project: {run.project}")

    # Log configuration
    run.config.update({"learning_rate": 0.001, "batch_size": 32})

    return run.id
```

## Parent-child task relationships

When a parent task calls child tasks, the plugin can share the same W&B run across all of them. This is useful for tracking an entire workflow in a single run.

```python {hl_lines=[1, 9, 16]}
@wandb_init
@env.task
async def child_task(x: int) -> int:
    run = get_wandb_run()
    run.log({"child_metric": x * 2})
    return x * 2

@wandb_init
@env.task
async def parent_task() -> int:
    run = get_wandb_run()
    run.log({"parent_metric": 100})

    # Child task shares the parent's run by default
    result = await child_task(5)

    return result
```

By default (`run_mode="auto"`), child tasks reuse their parent's W&B run. All metrics logged by the parent and children appear in the same run in the W&B UI.

## Run modes

The `run_mode` parameter controls how tasks create or reuse W&B runs. There are three modes:

| Mode             | Behavior                                                                   |
| ---------------- | -------------------------------------------------------------------------- |
| `auto` (default) | Create a new run if no parent run exists, otherwise reuse the parent's run |
| `new`            | Always create a new run, even if a parent run exists                       |
| `shared`         | Always reuse the parent's run (fails if no parent run exists)              |

### Using `run_mode="new"` for independent runs

```python {hl_lines=1}
@wandb_init(run_mode="new")
@env.task
async def independent_child(x: int) -> int:
    run = get_wandb_run()
    # This task gets its own separate run
    run.log({"independent_metric": x})
    return x

@wandb_init
@env.task
async def parent_task() -> str:
    run = get_wandb_run()
    parent_run_id = run.id

    # This child creates its own run
    await independent_child(5)

    # Parent's run is unchanged
    assert run.id == parent_run_id
    return parent_run_id
```

### Using `run_mode="shared"` for explicit sharing

```python {hl_lines=1}
@wandb_init(run_mode="shared")
@env.task
async def must_share_run(x: int) -> int:
    # This task requires a parent run to exist
    # It will fail if called as a top-level task
    run = get_wandb_run()
    run.log({"shared_metric": x})
    return x
```

## Configuration with `wandb_config`

Use `wandb_config()` to configure W&B runs. You can set it at the workflow level or override it for specific tasks, allowing you to provide configuration values at runtime.

### Workflow-level configuration

```python {hl_lines=["5-9"]}
if __name__ == "__main__":
    flyte.init_from_config()

    flyte.with_runcontext(
        custom_context=wandb_config(
            project="my-project",
            entity="my-team",
            tags=["experiment-1", "production"],
            config={"model": "resnet50", "dataset": "imagenet"},
        ),
    ).run(train_task)
```

### Overriding configuration for child tasks

Use `wandb_config()` as a context manager to override settings for specific child task calls:

```python {hl_lines=[8, 12]}
@wandb_init
@env.task
async def parent_task() -> str:
    run = get_wandb_run()
    run.log({"parent_metric": 100})

    # Override tags and config for this child call
    with wandb_config(tags=["special-run"], config={"learning_rate": 0.01}):
        await child_task(10)

    # Override run_mode for this child call
    with wandb_config(run_mode="new"):
        await child_task(20)  # Gets its own run

    return "done"
```

## Using traces with W&B runs

Flyte traces can access the parent task's W&B run without needing the `@wandb_init` decorator. This is useful for helper functions that should log to the same run:

```python {hl_lines=[1, 3]}
@flyte.trace
async def log_validation_metrics(accuracy: float, f1: float):
    run = get_wandb_run()
    if run:
        run.log({"val_accuracy": accuracy, "val_f1": f1})

@wandb_init
@env.task
async def train_and_validate() -> str:
    run = get_wandb_run()

    # Training loop
    for epoch in range(10):
        run.log({"train_loss": 1.0 / (epoch + 1)})

    # Trace logs to the same run
    await log_validation_metrics(accuracy=0.95, f1=0.92)

    return "done"
```

> **📝 Note**
>
> Do not apply `@wandb_init` to traces. Traces automatically access the parent task's run via `get_wandb_run()`.


=== PAGE: https://www.union.ai/docs/v2/union/integrations/wandb/distributed_training ===

# Distributed training

When running distributed training jobs, multiple processes run simultaneously across GPUs. The `@wandb_init` decorator automatically detects distributed training environments and coordinates W&B logging across processes.

The plugin:

- Auto-detects distributed context from environment variables (set by launchers like `torchrun`)
- Controls which processes initialize W&B runs based on the `run_mode` and `rank_scope` parameters
- Generates unique run IDs that distinguish between workers and ranks
- Adds links to W&B runs in the Flyte UI

## Quick start

Here's a minimal single-node example that logs metrics from a distributed training task. By default (`run_mode="auto"`, `rank_scope="global"`), only rank 0 logs to W&B:

```
import flyte
import torch
import torch.distributed
from flyteplugins.pytorch.task import Elastic
from flyteplugins.wandb import get_wandb_run, wandb_config, wandb_init

image = flyte.Image.from_debian_base(name="torch-wandb").with_pip_packages(
    "flyteplugins-wandb", "flyteplugins-pytorch"
)

env = flyte.TaskEnvironment(
    name="distributed_env",
    image=image,
    resources=flyte.Resources(gpu="A100:2"),
    plugin_config=Elastic(nproc_per_node=2, nnodes=1),
    secrets=flyte.Secret(key="wandb_api_key", as_env_var="WANDB_API_KEY"),
)

@wandb_init
@env.task
def train() -> float:
    torch.distributed.init_process_group("nccl")

    # Only rank 0 gets a W&B run object; others get None
    run = get_wandb_run()

    # Simulate training
    for step in range(100):
        loss = 1.0 / (step + 1)

        # Safe to call on all ranks - only rank 0 actually logs
        if run:
            run.log({"loss": loss, "step": step})

    torch.distributed.destroy_process_group()
    return loss

if __name__ == "__main__":
    flyte.init_from_config()
    flyte.with_runcontext(
        custom_context=wandb_config(project="my-project", entity="my-team")
    ).run(train)
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/integrations/flyte-plugins/wandb/distributed_training_quick_start.py*

A few things to note:

1. Use the `Elastic` plugin to configure distributed training (number of processes, nodes)
2. Apply `@wandb_init` as the outermost decorator
3. Check if `run` is not None before logging - only the primary rank has a run object in `auto` mode

> **📝 Note**
>
> The `if run:` check is always safe regardless of run mode. In `shared` and `new` modes all ranks get a run object, but the check doesn't hurt and keeps your code portable across modes.

![Single-node auto](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/integrations/wandb/single_node_auto_flyte.png)

## Run modes in distributed training

The `run_mode` parameter controls how W&B runs are created across distributed processes. The behavior differs between single-node (one machine, multiple GPUs) and multi-node (multiple machines) setups.

### Single-node behavior

| Mode             | Which ranks log       | Result                                 |
| ---------------- | --------------------- | -------------------------------------- |
| `auto` (default) | Only rank 0           | 1 W&B run                              |
| `shared`         | All ranks to same run | 1 W&B run with metrics labeled by rank |
| `new`            | Each rank separately  | N W&B runs (grouped in UI)             |

### Multi-node behavior

For multi-node training, the `rank_scope` parameter controls the granularity of W&B runs:

- **`global`** (default): Treat all workers as one unit
- **`worker`**: Treat each worker/node independently

The combination of `run_mode` and `rank_scope` determines logging behavior:

| `run_mode` | `rank_scope` | Who initializes W&B    | W&B Runs | Grouping |
| ---------- | ------------ | ---------------------- | -------- | -------- |
| `auto`     | `global`     | Global rank 0 only     | 1        | -        |
| `auto`     | `worker`     | Local rank 0 per worker | N        | -        |
| `shared`   | `global`     | All ranks (shared globally) | 1        | -        |
| `shared`   | `worker`     | All ranks (shared per worker) | N        | -        |
| `new`      | `global`     | All ranks              | N × M    | 1 group  |
| `new`      | `worker`     | All ranks              | N × M    | N groups |

Where `N` = number of workers/nodes, `M` = processes per worker.

### Choosing run mode and rank scope

- **`auto`** (recommended): Use when you want clean dashboards with minimal runs. Most metrics (loss, accuracy) are the same across ranks after gradient synchronization, so logging from one rank is sufficient.
- **`shared`**: Use when you need to compare metrics across ranks in a single view. Each rank's metrics are labeled with an `x_label` identifier. Useful for debugging load imbalance or per-GPU throughput.
- **`new`**: Use when you need completely separate runs per GPU, for example to track GPU-specific metrics or compare training dynamics across devices.

For multi-node training:
- Use **`rank_scope="global"`** (default) for most cases. A single consolidated run across all nodes is sufficient since metrics like loss and accuracy converge after gradient synchronization.
- Use **`rank_scope="worker"`** for debugging and per-node analysis. This is useful when you need to inspect data distribution across nodes, compare predictions from different workers, or track metrics on individual batches outside the main node.

## Single-node multi-GPU

For single-node distributed training, configure the `Elastic` plugin with `nnodes=1` and set `nproc_per_node` to your GPU count.

### Basic example with `auto` mode

```python {hl_lines=["6-7", 13, 18, 30]}
import os

import torch
import torch.distributed
import flyte
from flyteplugins.pytorch.task import Elastic
from flyteplugins.wandb import wandb_init, get_wandb_run

env = flyte.TaskEnvironment(
    name="single_node_env",
    image=image,
    resources=flyte.Resources(gpu="A100:4"),
    plugin_config=Elastic(nproc_per_node=4, nnodes=1),
    secrets=flyte.Secret(key="wandb_api_key", as_env_var="WANDB_API_KEY"),
)

@wandb_init # run_mode="auto" (default)
@env.task
def train_single_node() -> float:
    torch.distributed.init_process_group("nccl")
    rank = torch.distributed.get_rank()
    local_rank = int(os.environ.get("LOCAL_RANK", 0))

    device = torch.device(f"cuda:{local_rank}")
    torch.cuda.set_device(device)

    run = get_wandb_run()

    # Training loop - only rank 0 logs
    for epoch in range(10):
        loss = train_epoch(model, dataloader, device)

        if run:
            run.log({"epoch": epoch, "loss": loss})

    torch.distributed.destroy_process_group()
    return loss
```

### Using `shared` mode for per-rank metrics

When you need to see metrics from all GPUs in a single run, use `run_mode="shared"`:

```python {hl_lines=[3, 13, 19]}
import os

@wandb_init(run_mode="shared")
@env.task
def train_with_per_gpu_metrics() -> float:
    torch.distributed.init_process_group("nccl")
    rank = torch.distributed.get_rank()
    local_rank = int(os.environ.get("LOCAL_RANK", 0))

    device = torch.device(f"cuda:{local_rank}")
    torch.cuda.set_device(device)

    # In shared mode, all ranks get a run object
    run = get_wandb_run()

    for step in range(1000):
        loss, throughput = train_step(model, batch, device)

        # Each rank logs with automatic x_label identification
        if run:
            run.log({
                "loss": loss,
                "throughput_samples_per_sec": throughput,
                "gpu_memory_used": torch.cuda.memory_allocated(device),
            })

    torch.distributed.destroy_process_group()
    return loss
```

![Single-node shared](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/integrations/wandb/single_node_shared_flyte.png)

In the W&B UI, metrics from each rank appear with distinct labels, allowing you to compare GPU utilization and throughput across devices.

![Single-node shared W&B UI](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/integrations/wandb/single_node_shared_wandb.png)

### Using `new` mode for per-rank runs

When you need completely separate W&B runs for each GPU, use `run_mode="new"`. Each rank gets its own run, and runs are grouped together in the W&B UI:

```python {hl_lines=[1, "11-12"]}
@wandb_init(run_mode="new")  # Each rank gets its own run
@env.task
def train_per_rank() -> float:
    torch.distributed.init_process_group("nccl")
    rank = torch.distributed.get_rank()
    # ...

    # Each rank has its own W&B run
    run = get_wandb_run()

    # Run IDs: {base}-rank-{rank}
    # All runs are grouped under {base} in W&B UI
    run.log({"train/loss": loss.item(), "rank": rank})
    # ...
```

With `run_mode="new"`:

- Each rank creates its own W&B run
- Run IDs follow the pattern `{run_name}-{action_name}-rank-{rank}`
- All runs are grouped together in the W&B UI for comparison

## Multi-node training with `Elastic`

For multi-node distributed training, set `nnodes` to your node count. The `rank_scope` parameter controls whether you get a single W&B run across all nodes (`global`) or one run per node (`worker`).

### Global scope (default): Single run across all nodes

With `run_mode="auto"` and `rank_scope="global"` (both defaults), only global rank 0 initializes W&B, resulting in a single run for the entire distributed job:

```python {hl_lines=["11-12", "27-30", "35", "59-60", "95-98"]}
import os

import torch
import torch.distributed
import torch.nn as nn
import torch.optim as optim
from torch.nn.parallel import DistributedDataParallel as DDP
from torch.utils.data import DataLoader, DistributedSampler

import flyte
from flyteplugins.pytorch.task import Elastic
from flyteplugins.wandb import wandb_init, wandb_config, get_wandb_run

image = flyte.Image.from_debian_base(name="torch-wandb").with_pip_packages(
    "flyteplugins-wandb", "flyteplugins-pytorch", pre=True
)

multi_node_env = flyte.TaskEnvironment(
    name="multi_node_env",
    image=image,
    resources=flyte.Resources(
        cpu=(1, 2),
        memory=("1Gi", "10Gi"),
        gpu="A100:4",
        shm="auto",
    ),
    plugin_config=Elastic(
        nproc_per_node=4,  # GPUs per node
        nnodes=2,          # Number of nodes
    ),
    secrets=flyte.Secret(key="wandb_api_key", as_env_var="WANDB_API_KEY"),
)

@wandb_init  # rank_scope="global" by default → 1 run total
@multi_node_env.task
def train_multi_node(epochs: int, batch_size: int) -> float:
    torch.distributed.init_process_group("nccl")

    rank = torch.distributed.get_rank()
    world_size = torch.distributed.get_world_size()
    local_rank = int(os.environ.get("LOCAL_RANK", 0))

    device = torch.device(f"cuda:{local_rank}")
    torch.cuda.set_device(device)

    # Model with DDP
    model = MyModel().to(device)
    model = DDP(model, device_ids=[local_rank])

    # Distributed data loading
    dataset = MyDataset()
    sampler = DistributedSampler(dataset, num_replicas=world_size, rank=rank)
    dataloader = DataLoader(dataset, batch_size=batch_size, sampler=sampler)

    optimizer = optim.AdamW(model.parameters(), lr=1e-3)
    criterion = nn.CrossEntropyLoss()

    # Only global rank 0 gets a W&B run
    run = get_wandb_run()

    for epoch in range(epochs):
        sampler.set_epoch(epoch)
        model.train()

        for batch_idx, (data, target) in enumerate(dataloader):
            data, target = data.to(device), target.to(device)

            optimizer.zero_grad()
            output = model(data)
            loss = criterion(output, target)
            loss.backward()
            optimizer.step()

            if run and batch_idx % 100 == 0:
                run.log({
                    "train/loss": loss.item(),
                    "train/epoch": epoch,
                    "train/batch": batch_idx,
                })

        if run:
            run.log({"train/epoch_complete": epoch})

    # Barrier ensures all ranks finish before cleanup
    torch.distributed.barrier()
    torch.distributed.destroy_process_group()

    return loss.item()

if __name__ == "__main__":
    flyte.init_from_config()
    flyte.with_runcontext(
        custom_context=wandb_config(
            project="multi-node-training",
            tags=["distributed", "multi-node"],
        )
    ).run(train_multi_node, epochs=10, batch_size=32)
```

With this configuration:

- Two nodes run the task, each with 4 GPUs (8 total processes)
- Only global rank 0 creates a W&B run
- Run ID follows the pattern `{run_name}-{action_name}`
- The Flyte UI shows a single link to the W&B run

### Worker scope: One run per node

Use `rank_scope="worker"` when you want each node to have its own W&B run for per-node analysis:

```python {hl_lines=[1, 8]}
@wandb_init(rank_scope="worker")  # 1 run per worker/node
@multi_node_env.task
def train_per_worker(epochs: int, batch_size: int) -> float:
    torch.distributed.init_process_group("nccl")
    local_rank = int(os.environ.get("LOCAL_RANK", 0))
    # ...

    # Local rank 0 of each worker gets a W&B run
    run = get_wandb_run()

    if run:
        # Each worker logs to its own run
        run.log({"train/loss": loss.item()})
    # ...
```

With `run_mode="auto"`, `rank_scope="worker"`:

- Each node's local rank 0 creates a W&B run
- Run IDs follow the pattern `{run_name}-{action_name}-worker-{worker_index}`
- The Flyte UI shows links to each worker's W&B run

![Multi-node](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/integrations/wandb/multi_node.png)

### Shared mode: All ranks log to the same run

Use `run_mode="shared"` when you need metrics from all ranks in a single view. Each rank's metrics are labeled with an `x_label` identifier.

#### Shared + global scope (1 run total)

```python {hl_lines=[1, 7]}
@wandb_init(run_mode="shared")  # All ranks log to 1 shared run
@multi_node_env.task
def train_shared_global() -> float:
    torch.distributed.init_process_group("nccl")
    # ...

    # All ranks get a run object, all log to the same run
    run = get_wandb_run()

    # Each rank logs with automatic x_label identification
    run.log({"train/loss": loss.item(), "rank": rank})
    # ...
```

#### Shared + worker scope (N runs, 1 per node)

```python {hl_lines=[1, 7, 10]}
@wandb_init(run_mode="shared", rank_scope="worker")  # 1 shared run per worker
@multi_node_env.task
def train_shared_worker() -> float:
    torch.distributed.init_process_group("nccl")
    # ...

    # All ranks get a run object, grouped by worker
    run = get_wandb_run()

    # Ranks on the same worker share a run
    run.log({"train/loss": loss.item(), "local_rank": local_rank})
    # ...
```

### New mode: Separate run per rank

Use `run_mode="new"` when you need completely separate runs per GPU. Runs are grouped in the W&B UI for easy comparison.

#### New + global scope (N×M runs, 1 group)

```python {hl_lines=[1, 7, 10]}
@wandb_init(run_mode="new")  # Each rank gets its own run, all in 1 group
@multi_node_env.task
def train_new_global() -> float:
    torch.distributed.init_process_group("nccl")
    # ...

    # Each rank has its own run
    run = get_wandb_run()

    # Run IDs: {base}-rank-{global_rank}
    run.log({"train/loss": loss.item()})
    # ...
```

#### New + worker scope (N×M runs, N groups)

```python {hl_lines=[1, 7, 10]}
@wandb_init(run_mode="new", rank_scope="worker")  # Each rank gets own run, grouped per worker
@multi_node_env.task
def train_new_worker() -> float:
    torch.distributed.init_process_group("nccl")
    # ...

    # Each rank has its own run, grouped by worker
    run = get_wandb_run()

    # Run IDs: {base}-worker-{idx}-rank-{local_rank}
    run.log({"train/loss": loss.item()})
    # ...
```

## How it works

The plugin automatically detects distributed training by checking environment variables set by distributed launchers like `torchrun`:

| Environment variable | Description                                              |
| -------------------- | -------------------------------------------------------- |
| `RANK`               | Global rank across all processes                         |
| `WORLD_SIZE`         | Total number of processes                                |
| `LOCAL_RANK`         | Rank within the current node                             |
| `LOCAL_WORLD_SIZE`   | Number of processes on the current node                  |
| `GROUP_RANK`         | Node/worker index (0 for first node, 1 for second, etc.) |

When these variables are present, the plugin:

1. **Determines which ranks should initialize W&B** based on `run_mode` and `rank_scope`
2. **Generates unique run IDs** that include worker and rank information
4. **Creates UI links** for each W&B run (single link with `rank_scope="global"`, one per worker with `rank_scope="worker"`)

The plugin automatically adapts to your training setup, eliminating the need for manual distributed configuration.

### Run ID patterns

| Scenario                     | Run ID Pattern                                | Group                    |
| ---------------------------- | --------------------------------------------- | ------------------------ |
| Single-node auto/shared      | `{base}`                                      | -                        |
| Single-node new              | `{base}-rank-{rank}`                          | `{base}`                 |
| Multi-node auto/shared (global) | `{base}`                                   | -                        |
| Multi-node auto/shared (worker) | `{base}-worker-{idx}`                      | -                        |
| Multi-node new (global)      | `{base}-rank-{global_rank}`                   | `{base}`                 |
| Multi-node new (worker)      | `{base}-worker-{idx}-rank-{local_rank}`       | `{base}-worker-{idx}`    |

Where `{base}` = `{run_name}-{action_name}`


=== PAGE: https://www.union.ai/docs/v2/union/integrations/wandb/sweeps ===

# Sweeps

W&B sweeps automate hyperparameter optimization by running multiple trials with different parameter combinations. The `@wandb_sweep` decorator creates a sweep and makes it easy to run trials in parallel using Flyte's distributed execution.

## Creating a sweep

Use `@wandb_sweep` to create a W&B sweep when the task executes:

```
import flyte
import wandb
from flyteplugins.wandb import (
    get_wandb_sweep_id,
    wandb_config,
    wandb_init,
    wandb_sweep,
    wandb_sweep_config,
)

env = flyte.TaskEnvironment(
    name="wandb-example",
    image=flyte.Image.from_debian_base(name="wandb-example").with_pip_packages(
        "flyteplugins-wandb"
    ),
    secrets=[flyte.Secret(key="wandb_api_key", as_env_var="WANDB_API_KEY")],
)

@wandb_init
def objective():
    """Objective function that W&B calls for each trial."""
    wandb_run = wandb.run
    config = wandb_run.config

    # Simulate training with hyperparameters from the sweep
    for epoch in range(config.epochs):
        loss = 1.0 / (config.learning_rate * config.batch_size) + epoch * 0.1
        wandb_run.log({"epoch": epoch, "loss": loss})

@wandb_sweep
@env.task
async def run_sweep() -> str:
    sweep_id = get_wandb_sweep_id()

    # Run 10 trials
    wandb.agent(sweep_id, function=objective, count=10)

    return sweep_id

if __name__ == "__main__":
    flyte.init_from_config()

    r = flyte.with_runcontext(
        custom_context={
            **wandb_config(project="my-project", entity="my-team"),
            **wandb_sweep_config(
                method="random",
                metric={"name": "loss", "goal": "minimize"},
                parameters={
                    "learning_rate": {"min": 0.0001, "max": 0.1},
                    "batch_size": {"values": [16, 32, 64, 128]},
                    "epochs": {"values": [5, 10, 20]},
                },
            ),
        },
    ).run(run_sweep)

    print(f"run url: {r.url}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/integrations/flyte-plugins/wandb/sweep.py*

The `@wandb_sweep` decorator:

- Creates a W&B sweep when the task starts
- Makes the sweep ID available via `get_wandb_sweep_id()`
- Adds a link to the main sweeps page in the Flyte UI

Use `wandb_sweep_config()` to define the sweep parameters. This is passed to W&B's sweep API.

> **📝 Note**
>
> Random and Bayesian searches run indefinitely, and the sweep remains in the `Running` state until you stop it.
> You can stop a running sweep from the Weights & Biases UI or from the command line.

## Running parallel agents

Flyte's distributed execution makes it easy to run multiple sweep agents in parallel, each on its own compute resources:

```
import asyncio
from datetime import timedelta

import flyte
import wandb
from flyteplugins.wandb import (
    get_wandb_sweep_id,
    wandb_config,
    wandb_init,
    wandb_sweep,
    wandb_sweep_config,
    get_wandb_context,
)

env = flyte.TaskEnvironment(
    name="wandb-parallel-sweep-example",
    image=flyte.Image.from_debian_base(
        name="wandb-parallel-sweep-example"
    ).with_pip_packages("flyteplugins-wandb"),
    secrets=[flyte.Secret(key="wandb_api_key", as_env_var="WANDB_API_KEY")],
)

@wandb_init
def objective():
    wandb_run = wandb.run
    config = wandb_run.config

    for epoch in range(config.epochs):
        loss = 1.0 / (config.learning_rate * config.batch_size) + epoch * 0.1
        wandb_run.log({"epoch": epoch, "loss": loss})

@wandb_sweep
@env.task
async def sweep_agent(agent_id: int, sweep_id: str, count: int = 5) -> int:
    """Single agent that runs a subset of trials."""
    wandb.agent(
        sweep_id, function=objective, count=count, project=get_wandb_context().project
    )
    return agent_id

@wandb_sweep
@env.task
async def run_parallel_sweep(total_trials: int = 20, trials_per_agent: int = 5) -> str:
    """Orchestrate multiple agents running in parallel."""
    sweep_id = get_wandb_sweep_id()

    num_agents = (total_trials + trials_per_agent - 1) // trials_per_agent

    # Launch agents in parallel, each with its own resources
    agent_tasks = [
        sweep_agent.override(
            resources=flyte.Resources(cpu="2", memory="4Gi"),
            retries=3,
            timeout=timedelta(minutes=30),
        )(agent_id=i, sweep_id=sweep_id, count=trials_per_agent)
        for i in range(num_agents)
    ]

    await asyncio.gather(*agent_tasks)
    return sweep_id

if __name__ == "__main__":
    flyte.init_from_config()

    r = flyte.with_runcontext(
        custom_context={
            **wandb_config(project="my-project", entity="my-team"),
            **wandb_sweep_config(
                method="random",
                metric={"name": "loss", "goal": "minimize"},
                parameters={
                    "learning_rate": {"min": 0.0001, "max": 0.1},
                    "batch_size": {"values": [16, 32, 64]},
                    "epochs": {"values": [5, 10, 20]},
                },
            ),
        },
    ).run(
        run_parallel_sweep,
        total_trials=20,
        trials_per_agent=5,
    )

    print(f"run url: {r.url}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/integrations/flyte-plugins/wandb/parallel_sweep.py*

This pattern provides:

- **Distributed execution**: Each agent runs on separate compute nodes
- **Resource allocation**: Specify CPU, memory, and GPU per agent
- **Fault tolerance**: Failed agents can retry without affecting others
- **Timeout protection**: Prevent runaway trials

> **📝 Note**
>
> `run_parallel_sweep` links to the main Weights & Biases sweeps page and `sweep_agent` links to the specific sweep URL because we cannot determine the sweep ID at link rendering time.

![Sweep](https://raw.githubusercontent.com/unionai/unionai-docs-static/main/images/integrations/wandb/sweep.png)

## Writing objective functions

The objective function is called by `wandb.agent()` for each trial. It must be a regular Python function decorated with `@wandb_init`:

```python {hl_lines=["1-2", "5-6"]}
@wandb_init
def objective():
    """Objective function for sweep trials."""
    # Access hyperparameters from wandb.run.config
    run = wandb.run
    config = run.config

    # Your training code
    model = create_model(
        learning_rate=config.learning_rate,
        hidden_size=config.hidden_size,
    )

    for epoch in range(config.epochs):
        train_loss = train_epoch(model)
        val_loss = validate(model)

        # Log metrics - W&B tracks these for the sweep
        run.log({
            "epoch": epoch,
            "train_loss": train_loss,
            "val_loss": val_loss,
        })

    # The final val_loss is used by the sweep to rank trials
```

Key points:

- Use `@wandb_init` on the objective function (not `@env.task`)
- Access hyperparameters via `wandb.run.config` (not `get_wandb_run()` since this is outside Flyte context)
- Log the metric specified in `wandb_sweep_config(metric=...)` so the sweep can optimize it
- The function is called multiple times by `wandb.agent()`, once per trial


=== PAGE: https://www.union.ai/docs/v2/union/integrations/wandb/downloading_logs ===

# Downloading logs

This integration enables downloading Weights & Biases run data, including metrics history, summary data, and synced files.

## Automatic download

Set `download_logs=True` to automatically download run data after your task completes:

```python {hl_lines=1}
@wandb_init(download_logs=True)
@env.task
async def train_with_download():
    run = get_wandb_run()

    for epoch in range(10):
        run.log({"loss": 1.0 / (epoch + 1)})

    return run.id
```

The downloaded data is traced by Flyte and appears as a `Dir` output in the Flyte UI. Downloaded files include:

- `summary.json`: Final summary metrics
- `metrics_history.json`: Step-by-step metrics history
- Any files synced by W&B (`requirements.txt`, `wandb_metadata.json`, etc.)

You can also set `download_logs=True` in `wandb_config()`:

```python {hl_lines=5}
flyte.with_runcontext(
    custom_context=wandb_config(
        project="my-project",
        entity="my-team",
        download_logs=True,
    ),
).run(train_task)
```

![Logs](https://raw.githubusercontent.com/unionai/unionai-docs-static/main/images/integrations/wandb/logs.png)

For sweeps, set `download_logs=True` on `@wandb_sweep` or `wandb_sweep_config()` to download all trial data:

```python {hl_lines=1}
@wandb_sweep(download_logs=True)
@env.task
async def run_sweep():
    sweep_id = get_wandb_sweep_id()
    wandb.agent(sweep_id, function=objective, count=10)
    return sweep_id
```

![Sweep Logs](https://raw.githubusercontent.com/unionai/unionai-docs-static/main/images/integrations/wandb/sweep_logs.png)

## Accessing run directories during execution

Use `get_wandb_run_dir()` to access the local W&B run directory during task execution. This is useful for writing custom files that get synced to W&B:

```python {hl_lines=[1, 7, "18-19"]}
from flyteplugins.wandb import get_wandb_run_dir

@wandb_init
@env.task
def train_with_artifacts():
    run = get_wandb_run()
    local_dir = get_wandb_run_dir()

    # Train your model
    for epoch in range(10):
        run.log({"loss": 1.0 / (epoch + 1)})

    # Save model checkpoint to the run directory
    model_path = f"{local_dir}/model_checkpoint.pt"
    torch.save(model.state_dict(), model_path)

    # Save custom metrics file
    with open(f"{local_dir}/custom_metrics.json", "w") as f:
        json.dump({"final_accuracy": 0.95}, f)

    return run.id
```

Files written to the run directory are automatically synced to W&B and can be accessed later via the W&B UI or by setting `download_logs=True`.

> **📝 Note**
>
> `get_wandb_run_dir()` accesses the local directory without making network calls. Files written here may have a brief delay before appearing in the W&B cloud.


=== PAGE: https://www.union.ai/docs/v2/union/integrations/wandb/constraints_and_best_practices ===

# Constraints and best practices

## Decorator ordering

`@wandb_init` and `@wandb_sweep` must be the **outermost decorators**, applied after `@env.task`:

```python
# Correct
@wandb_init
@env.task
async def my_task():
    ...

# Incorrect - will not work
@env.task
@wandb_init
async def my_task():
    ...
```

## Traces cannot use decorators

Do not apply `@wandb_init` to traces. Traces automatically access the parent task's run via `get_wandb_run()`:

```python
# Correct
@flyte.trace
async def my_trace():
    run = get_wandb_run()
    if run:
        run.log({"metric": 42})

# Incorrect - don't decorate traces
@wandb_init
@flyte.trace
async def my_trace():
    ...
```

## Maximum sweep agents

[W&B limits sweeps to a maximum of 20 concurrent agents](https://docs.wandb.ai/models/sweeps/existing-project#3-launch-agents).

## Configuration priority

Configuration is merged with the following priority (highest to lowest):

1. Decorator parameters (`@wandb_init(project="...")`)
2. Context manager (`with wandb_config(...)`)
3. Workflow-level context (`flyte.with_runcontext(custom_context=wandb_config(...))`)
4. Auto-generated values (run ID from Flyte context)

## Run ID generation

When no explicit `id` is provided, the plugin generates run IDs using the pattern:

```
{run_name}-{action_name}
```

This ensures unique, predictable IDs that can be matched between the `Wandb` link class and manual `wandb.init()` calls.

## Sync delay for local files

Files written to the run directory (via `get_wandb_run_dir()`) are synced to W&B asynchronously. There may be a brief delay before they appear in the W&B cloud or can be downloaded via `download_wandb_run_dir()`.

## Shared run mode requirements

When using `run_mode="shared"`, the task requires a parent task to have already created a W&B run. Calling a task with `run_mode="shared"` as a top-level task will fail.

## Objective functions for sweeps

Objective functions passed to `wandb.agent()` should:

- Be regular Python functions (not Flyte tasks)
- Be decorated with `@wandb_init`
- Access hyperparameters via `wandb.run.config` (not `get_wandb_run()`)
- Log the metric specified in `wandb_sweep_config(metric=...)` so the sweep can optimize it

## Error handling

The plugin raises standard exceptions:

- `RuntimeError`: When `download_wandb_run_dir()` is called without a run ID and no active run exists
- `wandb.errors.AuthenticationError`: When `WANDB_API_KEY` is not set or invalid
- `wandb.errors.CommError`: When a run cannot be found in the W&B cloud


=== PAGE: https://www.union.ai/docs/v2/union/integrations/wandb/manual ===

# Manual integration

If you need more control over W&B initialization, you can use the `Wandb` and `WandbSweep` link classes directly instead of the decorators. This lets you call `wandb.init()` and `wandb.finish()` yourself while still getting automatic links in the Flyte UI.

## Using the Wandb link class

Add a `Wandb` link to your task to generate a link to the W&B run in the Flyte UI:

```
import flyte
import wandb
from flyteplugins.wandb import Wandb

env = flyte.TaskEnvironment(
    name="wandb-manual-init-example",
    image=flyte.Image.from_debian_base(
        name="wandb-manual-init-example"
    ).with_pip_packages("flyteplugins-wandb"),
    secrets=[flyte.Secret(key="wandb_api_key", as_env_var="WANDB_API_KEY")],
)

@env.task(
    links=(
        Wandb(
            project="my-project",
            entity="my-team",
            run_mode="new",
            # No id parameter - link will auto-generate from run_name-action_name
        ),
    )
)
async def train_model(learning_rate: float) -> str:
    ctx = flyte.ctx()

    # Generate run ID matching the link's auto-generated ID
    run_id = f"{ctx.action.run_name}-{ctx.action.name}"

    # Manually initialize W&B
    wandb_run = wandb.init(
        project="my-project",
        entity="my-team",
        id=run_id,
        config={"learning_rate": learning_rate},
    )

    # Your training code
    for epoch in range(10):
        loss = 1.0 / (learning_rate * (epoch + 1))
        wandb_run.log({"epoch": epoch, "loss": loss})

    # Manually finish the run
    wandb_run.finish()

    return wandb_run.id

if __name__ == "__main__":
    flyte.init_from_config()

    r = flyte.with_runcontext().run(
        train_model,
        learning_rate=0.01,
    )

    print(f"run url: {r.url}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/integrations/flyte-plugins/wandb/init_manual.py*

### With a custom run ID

If you want to use your own run ID, specify it in both the link and the `wandb.init()` call:

```python {hl_lines=[6, 14]}
@env.task(
    links=(
        Wandb(
            project="my-project",
            entity="my-team",
            id="my-custom-run-id",
        ),
    )
)
async def train_with_custom_id() -> str:
    run = wandb.init(
        project="my-project",
        entity="my-team",
        id="my-custom-run-id",  # Must match the link's ID
        resume="allow",
    )

    # Training code...
    run.finish()
    return run.id
```

### Adding links at runtime with override

You can also add links when calling a task using `.override()`:

```python {hl_lines=9}
@env.task
async def train_model(learning_rate: float) -> str:
    # ... training code with manual wandb.init() ...
    return run.id

# Add link when running the task
result = await train_model.override(
    links=(Wandb(project="my-project", entity="my-team", run_mode="new"),)
)(learning_rate=0.01)
```

## Using the `WandbSweep` link class

Use `WandbSweep` to add a link to a W&B sweep:

```
import flyte
import wandb
from flyteplugins.wandb import WandbSweep

env = flyte.TaskEnvironment(
    name="wandb-manual-sweep-example",
    image=flyte.Image.from_debian_base(
        name="wandb-manual-sweep-example"
    ).with_pip_packages("flyteplugins-wandb"),
    secrets=[flyte.Secret(key="wandb_api_key", as_env_var="WANDB_API_KEY")],
)

def objective():
    with wandb.init(project="my-project", entity="my-team") as wandb_run:
        config = wandb_run.config

        for epoch in range(config.epochs):
            loss = 1.0 / (config.learning_rate * config.batch_size) + epoch * 0.1
            wandb_run.log({"epoch": epoch, "loss": loss})

@env.task(
    links=(
        WandbSweep(
            project="my-project",
            entity="my-team",
        ),
    )
)
async def manual_sweep() -> str:
    # Manually create the sweep
    sweep_config = {
        "method": "random",
        "metric": {"name": "loss", "goal": "minimize"},
        "parameters": {
            "learning_rate": {"min": 0.0001, "max": 0.1},
            "batch_size": {"values": [16, 32, 64]},
            "epochs": {"value": 10},
        },
    }

    sweep_id = wandb.sweep(sweep_config, project="my-project", entity="my-team")

    # Run the sweep
    wandb.agent(sweep_id, function=objective, count=10, project="my-project")

    return sweep_id

if __name__ == "__main__":
    flyte.init_from_config()
    r = flyte.with_runcontext().run(manual_sweep)

    print(f"run url: {r.url}")
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/integrations/flyte-plugins/wandb/sweep_manual.py*

The link will point to the project's sweeps page. If you have the sweep ID, you can specify it in the link:

```python {hl_lines=6}
@env.task(
    links=(
        WandbSweep(
            project="my-project",
            entity="my-team",
            id="known-sweep-id",
        ),
    )
)
async def resume_sweep() -> str:
    # Resume an existing sweep
    wandb.agent("known-sweep-id", function=objective, count=10)
    return "known-sweep-id"
```


=== PAGE: https://www.union.ai/docs/v2/union/integrations/codegen ===

# Code generation

The code generation plugin turns natural-language prompts into tested, production-ready Python code.

You describe what the code should do, along with sample data, schema definitions, constraints, and typed inputs/outputs, and the plugin handles the rest: generating code, writing tests, building an isolated [code sandbox](/docs/v2/union//user-guide/sandboxing/code-sandboxing) with the right dependencies, running the tests, diagnosing failures, and iterating until everything passes. The result is a validated script you can execute against real data or deploy as a reusable Flyte task.

## Installation

```bash
pip install flyteplugins-codegen

# For Agent mode (Claude-only)
pip install flyteplugins-codegen[agent]
```

## Quick start

```python{hl_lines=[3, 4, 6, 12, 14, "20-25"]}
import flyte
from flyte.io import File
from flyte.sandbox import sandbox_environment
from flyteplugins.codegen import AutoCoderAgent

agent = AutoCoderAgent(model="gpt-4.1", name="summarize-sales")

env = flyte.TaskEnvironment(
    name="my-env",
    secrets=[flyte.Secret(key="openai_key", as_env_var="OPENAI_API_KEY")],
    image=flyte.Image.from_debian_base().with_pip_packages(
        "flyteplugins-codegen",
    ),
    depends_on=[sandbox_environment],
)

@env.task
async def process_data(csv_file: File) -> tuple[float, int, int]:
    result = await agent.generate.aio(
        prompt="Read the CSV and compute total_revenue, total_units and row_count.",
        samples={"sales": csv_file},
        outputs={"total_revenue": float, "total_units": int, "row_count": int},
    )
    return await result.run.aio()
```

The `depends_on=[sandbox_environment]` declaration is required. It ensures the sandbox runtime is available when dynamically-created sandboxes execute.

![Sandbox](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/integrations/codegen/sandbox.png)

## Two execution backends

The plugin supports two backends for generating and validating code. Both share the same `AutoCoderAgent` interface and produce the same `CodeGenEvalResult`.

### LiteLLM (default)

Uses structured-output LLM calls to generate code, detect packages, build sandbox images, run tests, diagnose failures, and iterate. Works with any model that supports structured outputs (GPT-4, Claude, Gemini, etc. via LiteLLM).

```python{hl_lines=[1, 3]}
agent = AutoCoderAgent(
    name="my-task",
    model="gpt-4.1",
    max_iterations=10,
)
```

The LiteLLM backend follows a fixed pipeline:

```mermaid
flowchart TD
    A["prompt + samples"] --> B["generate_plan"]
    B --> C["generate_code"]
    C --> D["detect_packages"]
    D --> E["build_image"]
    E --> F{skip_tests?}
    F -- yes --> G["return result"]
    F -- no --> H["generate_tests"]
    H --> I["execute_tests"]
    I --> J{pass?}
    J -- yes --> G
    J -- no --> K["diagnose_error"]
    K --> L{error type?}
    L -- "logic error" --> M["regenerate code"]
    L -- "environment error" --> N["add packages, rebuild image"]
    L -- "test error" --> O["fix test expectations"]
    M --> I
    N --> I
    O --> I
```

The loop continues until tests pass or `max_iterations` is reached.

![LiteLLM](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/integrations/codegen/litellm.png)

### Agent (Claude)

Uses the Claude Agent SDK to autonomously generate, test, and fix code. The agent has access to `Bash`, `Read`, `Write`, and `Edit` tools and decides what to do at each step. Test execution commands (`pytest`) are intercepted and run inside isolated sandboxes.

```python{hl_lines=["3-4"]}
agent = AutoCoderAgent(
    name="my-task",
    model="claude-sonnet-4-5-20250929",
    backend="claude",
)
```

> [!NOTE]
> Agent mode requires `ANTHROPIC_API_KEY` as a Flyte secret and is Claude-only.

**Key differences from LiteLLM:**

|                       | LiteLLM                           | Agent                                          |
| --------------------- | --------------------------------- | ---------------------------------------------- |
| **Execution**         | Fixed generate-test-fix pipeline  | Autonomous agent decides actions               |
| **Model support**     | Any model with structured outputs | Claude only                                    |
| **Iteration control** | `max_iterations`                  | `agent_max_turns`                              |
| **Test execution**    | Direct sandbox execution          | `pytest` commands intercepted via hooks        |
| **Tool safety**       | N/A                               | Commands classified as safe/denied/intercepted |
| **Observability**     | Logs + token counts               | Full tool call tracing in Flyte UI             |

In Agent mode, Bash commands are classified before execution:

- **Safe** (`ls`, `cat`, `grep`, `head`, etc.) — allowed to run directly
- **Intercepted** (`pytest`) — routed to sandbox execution
- **Denied** (`apt`, `pip install`, `curl`, etc.) — blocked for safety

## Providing data

### Sample data

Pass sample data via `samples` as `File` objects or pandas `DataFrame`s. The plugin automatically:

1. Converts DataFrames to CSV files
2. Infers [Pandera](https://pandera.readthedocs.io/) schemas from the data — column types, nullability
3. Parses natural-language `constraints` into Pandera checks (e.g., `"quantity must be positive"` becomes `pa.Check.gt(0)`)
4. Extracts data context — column statistics, distributions, patterns, sample rows
5. Injects all of this into the LLM prompt so the generated code is aware of the exact data structure

Pandera is used purely for prompt enrichment, not runtime validation. The generated code does not import Pandera — it benefits from the LLM knowing the precise data structure. The generated schemas are stored on `result.generated_schemas` for inspection.

```python{hl_lines=[3]}
result = await agent.generate.aio(
    prompt="Clean and validate the data, remove duplicates",
    samples={"orders": orders_df, "products": products_file},
    constraints=["quantity must be positive", "price between 0 and 10000"],
    outputs={"cleaned_orders": File},
)
```

### Schema and constraints

Use `schema` to provide free-form context about data formats or target structures (e.g., a database schema). Use `constraints` to declare business rules that the generated code must respect:

```python{hl_lines=["4-17"]}
result = await agent.generate.aio(
    prompt=prompt,
    samples={"readings": sensor_df},
    schema="""Output JSON schema for report_json:
    {
        "sensor_id": str,
        "avg_temp": float,
        "min_temp": float,
        "max_temp": float,
        "avg_humidity": float,
    }
    """,
    constraints=[
        "Temperature values must be between -40 and 60 Celsius",
        "Humidity values must be between 0 and 100 percent",
        "Output report must have one row per unique sensor_id",
    ],
    outputs={
        "report_json": str,
        "total_anomalies": int,
    },
)
```

![Pandera Constraints](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/integrations/codegen/pandera_constraints.png)

### Inputs and outputs

Declare `inputs` for non-sample arguments (e.g., thresholds, flags) and `outputs` for the expected result types.

Supported output types: `str`, `int`, `float`, `bool`, `datetime.datetime`, `datetime.timedelta`, `File`.

Sample entries are automatically added as `File` inputs — you do not need to redeclare them.

```python{hl_lines=[4, 5]}
result = await agent.generate.aio(
    prompt="Filter transactions above the threshold",
    samples={"transactions": tx_file},
    inputs={"threshold": float, "include_pending": bool},
    outputs={"filtered": File, "count": int},
)
```

## Running generated code

`agent.generate()` returns a `CodeGenEvalResult`. If `result.success` is `True`, the generated code passed all tests and you can execute it against real data. If `max_iterations` (LiteLLM) or `agent_max_turns` (Agent) is reached without tests passing, `result.success` is `False` and `result.error` contains the failure details.

Both `run()` and `as_task()` return output values as a tuple in the order declared in `outputs`. If there is a single output, the value is returned directly (not wrapped in a tuple).

### One-shot execution with `result.run()`

Runs the generated code in a sandbox. If samples were provided during `generate()`, they are used as default inputs.

```python
# Use sample data as defaults
total_revenue, total_units, count = await result.run.aio()

# Override specific inputs
total_revenue, total_units, count = await result.run.aio(threshold=0.5)

# Sync version
total_revenue, total_units, count = result.run()
```

`result.run()` accepts optional configuration:

```python{hl_lines=["4-6"]}
total_revenue, total_units, count = await result.run.aio(
    name="execute-on-data",
    resources=flyte.Resources(cpu=2, memory="4Gi"),
    retries=2,
    timeout=600,
    cache="auto",
)
```

### Reusable task with `result.as_task()`

Creates a callable sandbox task from the generated code. Useful when you want to run the same generated code against different data.

```python{hl_lines=[1, "6-7", "9-10"]}
task = result.as_task(
    name="run-sensor-analysis",
    resources=flyte.Resources(cpu=1, memory="512Mi"),
)

# Call with sample defaults
report, total_anomalies = await task.aio()

# Call with different data
report, total_anomalies = await task.aio(readings=new_data_file)
```

## Error diagnosis

The LiteLLM backend classifies test failures into three categories and applies targeted fixes:

| Error type    | Meaning                       | Action                                           |
| ------------- | ----------------------------- | ------------------------------------------------ |
| `logic`       | Bug in the generated code     | Regenerate code with specific patch instructions |
| `environment` | Missing package or dependency | Add the package and rebuild the sandbox image    |
| `test_error`  | Bug in the generated test     | Fix the test expectations                        |

If the same error persists after a fix, the plugin reclassifies it (e.g., `logic` to `test_error`) to try the other approach.

In Agent mode, the agent diagnoses and fixes issues autonomously based on error output.

## Durable execution

Code generation is expensive — it involves multiple LLM calls, image builds, and sandbox executions. Without durability, a transient failure in the pipeline (network blip, OOM, downstream service error) would force the entire process to restart from scratch: regenerating code, rebuilding images, re-running sandboxes, making additional LLM calls.

Flyte solves this through two complementary mechanisms: **replay logs** and **caching**.

### Replay logs

Flyte maintains a replay log that records every trace and task execution within a run. When a task crashes and retries, the system replays the log from the previous attempt rather than recomputing everything:

- No additional model calls
- No code regeneration
- No sandbox re-execution
- No container rebuilds

The workflow breezes through the earlier steps and resumes from the failure point. This applies as long as the traces and tasks execute in the same order and use the same inputs as the first attempt.

### Caching

Separately, Flyte can cache task results across runs. With `cache="auto"`, sandbox executions (image builds, test runs, code execution) are cached. This is useful when you re-run the same pipeline — not just when recovering from a crash, but across entirely separate invocations with the same inputs.

Together, replay logs handle crash recovery within a run, and caching avoids redundant work across runs.

### Non-determinism in Agent mode

One challenge with agents is that they are inherently non-deterministic — the sequence of actions can vary between runs, which could break replay.

In practice, the codegen agent follows a predictable pattern (write code, generate tests, run tests, inspect results), which works in replay's favor. The plugin also embeds logic that instructs the agent not to regenerate or re-execute steps that already completed successfully in the first run. This acts as an additional safety check alongside the replay log to account for non-determinism.

![Agent](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/integrations/codegen/agent.png)

On the first attempt, the full pipeline runs. If a transient failure occurs, the system instantly replays the traces (which track model calls) and sandbox executions, allowing the pipeline to resume from the point of failure.

![Durability](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/integrations/codegen/durability.png)

## Observability

### LiteLLM backend

- Logs every iteration with attempt count, error type, and package changes
- Tracks total input/output tokens across all LLM calls (available on `result.total_input_tokens` and `result.total_output_tokens`)
- Results include full conversation history for debugging (`result.conversation_history`)

### Agent backend

- Traces each tool call (name + input) via `PostToolUse` hooks
- Traces tool failures via `PostToolUseFailure` hooks
- Traces a summary when the agent finishes (total tool calls, tool distribution, final image/packages)
- Classifies Bash commands as safe, denied, or intercepted (for sandbox execution)
- All traces appear in the Flyte UI

## Examples

### Processing CSVs with different schemas

Generate code that handles varying CSV formats, then run on real data:

```python{hl_lines=[1, 3, 14, 16, 27]}
from flyteplugins.codegen import AutoCoderAgent

agent = AutoCoderAgent(
    name="sales-processor",
    model="gpt-4.1",
    max_iterations=5,
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    litellm_params={"temperature": 0.2, "max_tokens": 4096},
)

@env.task
async def process_sales(csv_file: File) -> dict[str, float | int]:
    result = await agent.generate.aio(
        prompt="Read the CSV and compute total_revenue, total_units, and transaction_count.",
        samples={"csv_data": csv_file},
        outputs={
            "total_revenue": float,
            "total_units": int,
            "transaction_count": int,
        },
    )

    if not result.success:
        raise RuntimeError(f"Code generation failed: {result.error}")

    total_revenue, total_units, transaction_count = await result.run.aio()

    return {
        "total_revenue": total_revenue,
        "total_units": total_units,
        "transaction_count": transaction_count,
    }
```

### DataFrame analysis with constraints

Pass DataFrames directly and enforce business rules with constraints:

```python{hl_lines=[10, "15-19"]}
agent = AutoCoderAgent(
    model="gpt-4.1",
    name="sensor-analysis",
    base_packages=["numpy"],
    max_sample_rows=30,
)

@env.task
async def analyze_sensors(sensor_df: pd.DataFrame) -> tuple[File, int]:
    result = await agent.generate.aio(
        prompt="""Analyze IoT sensor data. For each sensor, calculate mean/min/max
temperature, mean humidity, and count warnings. Output a summary CSV.""",
        samples={"readings": sensor_df},
        constraints=[
            "Temperature values must be between -40 and 60 Celsius",
            "Humidity values must be between 0 and 100 percent",
            "Output report must have one row per unique sensor_id",
        ],
        outputs={
            "report": File,
            "total_anomalies": int,
        },
    )

    if not result.success:
        raise RuntimeError(f"Code generation failed: {result.error}")

    task = result.as_task(
        name="run-sensor-analysis",
        resources=flyte.Resources(cpu=1, memory="512Mi"),
    )

    return await task.aio(readings=result.original_samples["readings"])
```

### Agent mode

The same task using Claude as an autonomous agent:

```python{hl_lines=[3]}
agent = AutoCoderAgent(
    name="sales-agent",
    backend="claude",
    model="claude-sonnet-4-5-20250929",
    resources=flyte.Resources(cpu=1, memory="512Mi"),
)

@env.task
async def process_sales_with_agent(csv_file: File) -> dict[str, float | int]:
    result = await agent.generate.aio(
        prompt="Read the CSV and compute total_revenue, total_units, and transaction_count.",
        samples={"csv_data": csv_file},
        outputs={
            "total_revenue": float,
            "total_units": int,
            "transaction_count": int,
        },
    )

    if not result.success:
        raise RuntimeError(f"Agent code generation failed: {result.error}")

    total_revenue, total_units, transaction_count = await result.run.aio()

    return {
        "total_revenue": total_revenue,
        "total_units": total_units,
        "transaction_count": transaction_count,
    }
```

## Configuration

### LiteLLM parameters

Tune model behavior with `litellm_params`:

```python{hl_lines=["5-8"]}
agent = AutoCoderAgent(
    name="my-task",
    model="anthropic/claude-sonnet-4-20250514",
    api_key="ANTHROPIC_API_KEY",
    litellm_params={
        "temperature": 0.3,
        "max_tokens": 4000,
    },
)
```

### Image configuration

Control the registry and Python version for sandbox images:

```python{hl_lines=["6-10"]}
from flyte.sandbox import ImageConfig

agent = AutoCoderAgent(
    name="my-task",
    model="gpt-4.1",
    image_config=ImageConfig(
        registry="my-registry.io",
        registry_secret="registry-creds",
        python_version=(3, 12),
    ),
)
```

### Skipping tests

Set `skip_tests=True` to skip test generation and execution. The agent still generates code, detects packages, and builds the sandbox image, but does not generate or run tests.

```python{hl_lines=[4]}
agent = AutoCoderAgent(
    name="my-task",
    model="gpt-4.1",
    skip_tests=True,
)
```

> [!NOTE]
> `skip_tests` only applies to LiteLLM mode. In Agent mode, the agent autonomously decides when to test.

### Base packages

Ensure specific packages are always installed in every sandbox:

```python{hl_lines=[4]}
agent = AutoCoderAgent(
    name="my-task",
    model="gpt-4.1",
    base_packages=["numpy", "pandas"],
)
```

## Best practices

- **One agent per task.** Each `generate()` call builds its own sandbox image and manages its own package state. Running multiple agents in the same task can cause resource contention and makes failures harder to diagnose.
- **Keep `cache="auto"` (the default).** Caching flows to all internal sandboxes, making retries near-instant. Use `"disable"` during development if you want fresh executions, or `"override"` to force re-execution and update the cached result.
- **Set `max_iterations` conservatively.** Start with 5-10 iterations. If the model cannot produce correct code in that budget, the prompt or constraints likely need refinement.
- **Provide constraints for data-heavy tasks.** Explicit constraints (e.g., `"quantity must be positive"`) produce better schemas and better generated code.
- **Inspect `result.generated_schemas`.** Review the inferred Pandera schemas to verify the model understood your data structure correctly.

## API reference

### `AutoCoderAgent` constructor

| Parameter         | Type              | Default        | Description                                                                            |
| ----------------- | ----------------- | -------------- | -------------------------------------------------------------------------------------- |
| `name`            | `str`             | `"auto-coder"` | Unique name for tracking and image naming                                              |
| `model`           | `str`             | `"gpt-4.1"`    | LiteLLM model identifier                                                               |
| `backend`         | `str`             | `"litellm"`    | Execution backend: `"litellm"` or `"claude"`                                           |
| `system_prompt`   | `str`             | `None`         | Custom system prompt override                                                          |
| `api_key`         | `str`             | `None`         | Name of the environment variable containing the LLM API key (e.g., `"OPENAI_API_KEY"`) |
| `api_base`        | `str`             | `None`         | Custom API base URL                                                                    |
| `litellm_params`  | `dict`            | `None`         | Extra LiteLLM params (temperature, max_tokens, etc.)                                   |
| `base_packages`   | `list[str]`       | `None`         | Always-install pip packages                                                            |
| `resources`       | `flyte.Resources` | `None`         | Resources for sandbox execution (default: 1 CPU, 1Gi)                                  |
| `image_config`    | `ImageConfig`     | `None`         | Registry, secret, and Python version                                                   |
| `max_iterations`  | `int`             | `10`           | Max generate-test-fix iterations (LiteLLM mode)                                        |
| `max_sample_rows` | `int`             | `100`          | Rows to sample from data for LLM context                                               |
| `skip_tests`      | `bool`            | `False`        | Skip test generation and execution (LiteLLM mode)                                      |
| `sandbox_retries` | `int`             | `0`            | Flyte task-level retries for each sandbox execution                                    |
| `timeout`         | `int`             | `None`         | Timeout in seconds for sandboxes                                                       |
| `env_vars`        | `dict[str, str]`  | `None`         | Environment variables for sandboxes                                                    |
| `secrets`         | `list[Secret]`    | `None`         | Flyte secrets for sandboxes                                                            |
| `cache`           | `str`             | `"auto"`       | Cache behavior: `"auto"`, `"override"`, or `"disable"`                                 |
| `agent_max_turns` | `int`             | `50`           | Max turns when `backend="claude"`                                                      |

### `generate()` parameters

| Parameter     | Type                           | Default  | Description                                                                             |
| ------------- | ------------------------------ | -------- | --------------------------------------------------------------------------------------- |
| `prompt`      | `str`                          | required | Natural-language task description                                                       |
| `schema`      | `str`                          | `None`   | Free-form context about data formats or target structures                               |
| `constraints` | `list[str]`                    | `None`   | Natural-language constraints (e.g., `"quantity must be positive"`)                      |
| `samples`     | `dict[str, File \| DataFrame]` | `None`   | Sample data. DataFrames are auto-converted to CSV files.                                |
| `inputs`      | `dict[str, type]`              | `None`   | Non-sample input types (e.g., `{"threshold": float}`)                                   |
| `outputs`     | `dict[str, type]`              | `None`   | Output types. Supported: `str`, `int`, `float`, `bool`, `datetime`, `timedelta`, `File` |

### `CodeGenEvalResult` fields

| Field                      | Type                      | Description                                               |
| -------------------------- | ------------------------- | --------------------------------------------------------- |
| `success`                  | `bool`                    | Whether tests passed                                      |
| `solution`                 | `CodeSolution`            | Generated code (`.code`, `.language`, `.system_packages`) |
| `tests`                    | `str`                     | Generated test code                                       |
| `output`                   | `str`                     | Test output                                               |
| `exit_code`                | `int`                     | Test exit code                                            |
| `error`                    | `str \| None`             | Error message if failed                                   |
| `attempts`                 | `int`                     | Number of iterations used                                 |
| `image`                    | `str`                     | Built sandbox image with all dependencies                 |
| `detected_packages`        | `list[str]`               | Pip packages detected                                     |
| `detected_system_packages` | `list[str]`               | Apt packages detected                                     |
| `generated_schemas`        | `dict[str, str] \| None`  | Pandera schemas as Python code strings                    |
| `data_context`             | `str \| None`             | Extracted data context                                    |
| `original_samples`         | `dict[str, File] \| None` | Sample data as Files (defaults for `run()`/`as_task()`)   |
| `total_input_tokens`       | `int`                     | Total input tokens across all LLM calls                   |
| `total_output_tokens`      | `int`                     | Total output tokens across all LLM calls                  |
| `conversation_history`     | `list[dict]`              | Full LLM conversation history for debugging               |

### `CodeGenEvalResult` methods

| Method                              | Description                                                        |
| ----------------------------------- | ------------------------------------------------------------------ |
| `result.run(**overrides)`           | Execute generated code in a sandbox. Sample data used as defaults. |
| `await result.run.aio(**overrides)` | Async version of `run()`.                                          |
| `result.as_task(name, ...)`         | Create a reusable callable sandbox task from the generated code.   |

Both `run()` and `as_task()` accept optional `name`, `resources`, `retries`, `timeout`, `env_vars`, `secrets`, and `cache` parameters.


=== PAGE: https://www.union.ai/docs/v2/union/integrations/mlflow ===

# MLflow

The MLflow plugin integrates [MLflow](https://mlflow.org/) experiment tracking with Flyte. It provides a `@mlflow_run` decorator that automatically manages MLflow runs within Flyte tasks, with support for autologging, parent-child run sharing, distributed training, and auto-generated UI links.

The decorator works with both sync and async tasks.

## Installation

```bash
pip install flyteplugins-mlflow
```

Requires `mlflow` and `flyte`.

## Quick start

```python{hl_lines=[3, 9, "13-16", 22]}
import flyte
import mlflow
from flyteplugins.mlflow import mlflow_run, get_mlflow_run

env = flyte.TaskEnvironment(
    name="mlflow-tracking",
    resources=flyte.Resources(cpu=1, memory="500Mi"),
    image=flyte.Image.from_debian_base(name="mlflow_example").with_pip_packages(
        "flyteplugins-mlflow"
    ),
)

@mlflow_run(
    tracking_uri="http://localhost:5000",
    experiment_name="my-experiment",
)
@env.task
async def train_model(learning_rate: float) -> str:
    mlflow.log_param("lr", learning_rate)
    mlflow.log_metric("loss", 0.42)

    run = get_mlflow_run()
    return run.info.run_id
```

![Link](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/integrations/mlflow/link.png)

![Mlflow UI](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/integrations/mlflow/mlflow_dashboard.png)

> [!NOTE]
> `@mlflow_run` must be the outermost decorator, before `@env.task`:
>
> ```python{hl_lines=["1-2"]}
> @mlflow_run          # outermost
> @env.task            # innermost
> async def my_task(): ...
> ```

## Autologging

Enable MLflow's autologging to automatically capture parameters, metrics, and models without manual `mlflow.log_*` calls.

### Generic autologging

```python{hl_lines=[1]}
@mlflow_run(autolog=True)
@env.task
async def train():
    from sklearn.linear_model import LogisticRegression

    model = LogisticRegression()
    model.fit(X, y)  # Parameters, metrics, and model are logged automatically
```

### Framework-specific autologging

Pass `framework` to use a framework-specific autolog implementation:

```python{hl_lines=[3]}
@mlflow_run(
    autolog=True,
    framework="sklearn",
    log_models=True,
    log_datasets=False,
)
@env.task
async def train_sklearn():
    from sklearn.ensemble import RandomForestClassifier

    model = RandomForestClassifier(n_estimators=100)
    model.fit(X_train, y_train)
```

Supported frameworks include any framework with an `mlflow.{framework}.autolog()` function. You can find the full list of supported frameworks [here](https://mlflow.org/docs/latest/ml/tracking/autolog/#supported-libraries).

You can pass additional autolog parameters via `autolog_kwargs`:

```python{hl_lines=[4]}
@mlflow_run(
    autolog=True,
    framework="pytorch",
    autolog_kwargs={"log_every_n_epoch": 5},
)
@env.task
async def train_pytorch():
    ...
```

![Autolog](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/integrations/mlflow/autolog.png)

## Run modes

The `run_mode` parameter controls how MLflow runs are created and shared across tasks:

| Mode               | Behavior                                                              |
| ------------------ | --------------------------------------------------------------------- |
| `"auto"` (default) | Reuse the parent's run if one exists, otherwise create a new run      |
| `"new"`            | Always create a new independent run                                   |
| `"nested"`         | Create a new run nested under the parent via `mlflow.parentRunId` tag |

### Sharing a run across tasks

With `run_mode="auto"` (the default), child tasks reuse the parent's MLflow run:

```python{hl_lines=[1, 5, 7]}
@mlflow_run
@env.task
async def parent_task():
    mlflow.log_param("stage", "parent")
    await child_task()  # Shares the same MLflow run

@mlflow_run
@env.task
async def child_task():
    mlflow.log_metric("child_metric", 1.0)  # Logged to the parent's run
```

### Creating independent runs

Use `run_mode="new"` when a task should always create its own top-level MLflow run, completely independent of any parent:

```python{hl_lines=[1]}
@mlflow_run(run_mode="new")
@env.task
async def standalone_experiment():
    mlflow.log_param("experiment_type", "baseline")
    mlflow.log_metric("accuracy", 0.95)
```

### Nested runs

Use `run_mode="nested"` to create a child run that appears under the parent in the MLflow UI. This works across processes and containers via the `mlflow.parentRunId` tag.

![Nested runs](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/integrations/mlflow/mlflow_hpo.png)

This is the recommended pattern for hyperparameter optimization, where each trial should be tracked as a child of the parent study run:

```python{hl_lines=[1, 2, 15, "22-25"]}
from flyteplugins.mlflow import Mlflow

@mlflow_run(run_mode="nested")
@env.task(links=[Mlflow()])
async def run_trial(trial_number: int, n_estimators: int, max_depth: int) -> float:
    """Each trial creates a nested MLflow run under the parent."""
    mlflow.log_params({"n_estimators": n_estimators, "max_depth": max_depth})
    mlflow.log_param("trial_number", trial_number)

    model = RandomForestRegressor(n_estimators=n_estimators, max_depth=max_depth)
    model.fit(X_train, y_train)

    rmse = float(np.sqrt(mean_squared_error(y_val, model.predict(X_val))))
    mlflow.log_metric("rmse", rmse)
    return rmse

@mlflow_run
@env.task
async def hpo_search(n_trials: int = 30) -> str:
    """Parent run tracks the overall study."""
    run = get_mlflow_run()
    mlflow.log_param("n_trials", n_trials)

    # Run trials in parallel — each gets a nested MLflow run
    rmses = await asyncio.gather(
        *(run_trial(trial_number=i, **params) for i, params in enumerate(trial_params))
    )

    mlflow.log_metric("best_rmse", min(rmses))
    return run.info.run_id
```

![HPO](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/integrations/mlflow/hpo.png)

## Workflow-level configuration

Use `mlflow_config()` with `flyte.with_runcontext()` to set MLflow configuration for an entire workflow. All `@mlflow_run`-decorated tasks in the workflow inherit these settings:

```python{hl_lines=[1, "4-8"]}
from flyteplugins.mlflow import mlflow_config

r = flyte.with_runcontext(
    custom_context=mlflow_config(
        tracking_uri="http://localhost:5000",
        experiment_id="846992856162999",
        tags={"team": "ml"},
    )
).run(train_model, learning_rate=0.001)
```

This eliminates the need to repeat `tracking_uri` and experiment settings on every `@mlflow_run` decorator.

### Per-task overrides

Use `mlflow_config()` as a context manager inside a task to override configuration for specific child tasks:

```python{hl_lines=[6]}
@mlflow_run
@env.task
async def parent_task():
    await shared_child()  # Inherits parent config

    with mlflow_config(run_mode="new", tags={"role": "independent"}):
        await independent_child()  # Gets its own run
```

### Configuration priority

Settings are resolved in priority order:

1. Explicit `@mlflow_run` decorator arguments
2. `mlflow_config()` context configuration
3. Environment variables (for `tracking_uri`)
4. MLflow defaults

## Distributed training

In distributed training, only rank 0 logs to MLflow by default. The plugin detects rank automatically from the `RANK` environment variable:

```python{hl_lines=[1, "4-6"]}
@mlflow_run
@env.task
async def distributed_train():
    # Only rank 0 creates an MLflow run and logs metrics.
    # Other ranks execute the task function directly without
    # creating an MLflow run or incurring any MLflow overhead.
    ...
```

On non-rank-0 workers, no MLflow run is created and `get_mlflow_run()` returns `None`. The task function still executes normally — only the MLflow instrumentation is skipped.

![Distributed training](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/integrations/mlflow/distributed_training.png)

You can also set rank explicitly:

```python{hl_lines=[1]}
@mlflow_run(rank=0)
@env.task
async def train():
    ...
```

## MLflow UI links

The `Mlflow` link class displays links to the MLflow UI in the Flyte UI.

Since the MLflow run is created inside the task at execution time, the run URL cannot be determined before the task starts. Links are only shown when a run URL is already available from context, either because a parent task created the run, or because an explicit URL is provided.

The recommended pattern is for the parent task to create the MLflow run, and child tasks that inherit the run (via `run_mode="auto"`) display the link to that run. For nested runs (`run_mode="nested"`), children display a link to the parent run.

### Setup

Set `link_host` via `mlflow_config()` and attach `Mlflow()` links to child tasks:

```python{hl_lines=[4, 17]}
from flyteplugins.mlflow import Mlflow, mlflow_config

@mlflow_run
@env.task(links=[Mlflow()])
async def child_task():
    ...  # Link points to the parent's MLflow run

@mlflow_run
@env.task
async def parent_task():
    await child_task()

if __name__ == "__main__":
    r = flyte.with_runcontext(
        custom_context=mlflow_config(
            tracking_uri="http://localhost:5000",
            link_host="http://localhost:5000",
        )
    ).run(parent_task)
```

> [!NOTE]
> `Mlflow()` is instantiated without a `link` argument because the URL is auto-generated at runtime. When the parent task creates an MLflow run, the plugin builds the URL from `link_host` and the run's experiment/run IDs, then propagates it to child tasks via the Flyte context. Passing an explicit `link` would bypass this auto-generation.

### Custom URL templates

The default link format is:

```
{host}/#/experiments/{experiment_id}/runs/{run_id}
```

For platforms like Databricks that use a different URL structure, provide a custom template:

```python{hl_lines=[3]}
mlflow_config(
    link_host="https://dbc-xxx.cloud.databricks.com",
    link_template="{host}/ml/experiments/{experiment_id}/runs/{run_id}",
)
```

### Explicit links

If you know the run URL ahead of time, you can set it directly:

```python{hl_lines=[1]}
@env.task(links=[Mlflow(link="https://mlflow.example.com/#/experiments/1/runs/abc123")])
async def my_task():
    ...
```

### Link behavior by run mode

| Run mode   | Link behavior                                                                                  |
| ---------- | ---------------------------------------------------------------------------------------------- |
| `"auto"`   | Parent link propagates to child tasks sharing the run                                          |
| `"new"`    | Parent link is cleared; no link is shown until the task's own run is available to its children |
| `"nested"` | Parent link is kept and renamed to "MLflow (parent)"                                           |

## Automatic Flyte tags

When running inside Flyte, the plugin automatically tags MLflow runs with execution metadata:

| Tag                 | Description      |
| ------------------- | ---------------- |
| `flyte.action_name` | Task action name |
| `flyte.run_name`    | Flyte run name   |
| `flyte.project`     | Flyte project    |
| `flyte.domain`      | Flyte domain     |

These tags are merged with any user-provided tags.

## API reference

### `mlflow_run` and `mlflow_config`

`mlflow_run` is a decorator that manages MLflow runs for Flyte tasks. `mlflow_config` creates workflow-level configuration or per-task overrides. Both accept the same core parameters:

| Parameter         | Type             | Default  | Description                                                                   |
| ----------------- | ---------------- | -------- | ----------------------------------------------------------------------------- |
| `run_mode`        | `str`            | `"auto"` | `"auto"`, `"new"`, or `"nested"`                                              |
| `tracking_uri`    | `str`            | `None`   | MLflow tracking server URL                                                    |
| `experiment_name` | `str`            | `None`   | MLflow experiment name (raises `ValueError` if combined with `experiment_id`) |
| `experiment_id`   | `str`            | `None`   | MLflow experiment ID (raises `ValueError` if combined with `experiment_name`) |
| `run_name`        | `str`            | `None`   | Human-readable run name (raises `ValueError` if combined with `run_id`)       |
| `run_id`          | `str`            | `None`   | Explicit MLflow run ID (raises `ValueError` if combined with `run_name`)      |
| `tags`            | `dict[str, str]` | `None`   | Tags for the run                                                              |
| `autolog`         | `bool`           | `False`  | Enable MLflow autologging                                                     |
| `framework`       | `str`            | `None`   | Framework for autolog (e.g. `"sklearn"`, `"pytorch"`)                         |
| `log_models`      | `bool`           | `None`   | Log models automatically (requires `autolog`)                                 |
| `log_datasets`    | `bool`           | `None`   | Log datasets automatically (requires `autolog`)                               |
| `autolog_kwargs`  | `dict`           | `None`   | Extra parameters for `mlflow.autolog()`                                       |

Additional keyword arguments are passed to `mlflow.start_run()`.

`mlflow_run` also accepts:

| Parameter | Type  | Default | Description                                              |
| --------- | ----- | ------- | -------------------------------------------------------- |
| `rank`    | `int` | `None`  | Process rank for distributed training (only rank 0 logs) |

`mlflow_config` also accepts:

| Parameter       | Type  | Default | Description                                                                 |
| --------------- | ----- | ------- | --------------------------------------------------------------------------- |
| `link_host`     | `str` | `None`  | MLflow UI host for auto-generating links                                    |
| `link_template` | `str` | `None`  | Custom URL template (placeholders: `{host}`, `{experiment_id}`, `{run_id}`) |

### `get_mlflow_run`

Returns the current `mlflow.ActiveRun` if within a `@mlflow_run`-decorated task. Returns `None` otherwise.

```python
from flyteplugins.mlflow import get_mlflow_run

run = get_mlflow_run()
if run:
    print(run.info.run_id)
```

### `get_mlflow_context`

Returns the current `mlflow_config` settings from the Flyte context, or `None` if no MLflow configuration is set. Useful for inspecting the inherited configuration inside a task:

```python
from flyteplugins.mlflow import get_mlflow_context

@mlflow_run
@env.task
async def my_task():
    config = get_mlflow_context()
    if config:
        print(config.tracking_uri, config.experiment_id)
```

### `Mlflow`

Link class for displaying MLflow UI links in the Flyte console.

| Field  | Type  | Default    | Description                             |
| ------ | ----- | ---------- | --------------------------------------- |
| `name` | `str` | `"MLflow"` | Display name for the link               |
| `link` | `str` | `""`       | Explicit URL (bypasses auto-generation) |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference ===

# Reference

This section provides the reference material for the Flyte SDK and CLI.

To get started, add `flyte` to your project

```shell
$ uv pip install --no-cache --upgrade flyte
```

This will install both the Flyte SDK and CLI.

### **Flyte SDK**

The Flyte SDK provides the core Python API for building workflows and apps on your Union instance.

### **Flyte CLI**

The Flyte CLI is the command-line interface for interacting with your Union instance.

### **Migration from Flyte 1 to Flyte 2**

Comprehensive reference for migrating Flyte 1 workflows to Flyte 2.

## Subpages
- **LLM-optimized documentation**
- **Migration from Flyte 1 to Flyte 2**
- **Flyte CLI**
- **Flyte SDK**
- **Integrations**
- **Uctl CLI**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-context ===

# LLM-optimized documentation

This site provides LLM-optimized documentation at four levels of granularity,
designed for use by AI coding agents such as
[Claude Code](https://docs.anthropic.com/en/docs/claude-code),
[Cursor](https://www.cursor.com/),
[Windsurf](https://windsurf.com/),
and similar tools.
These files also follow the [`llms.txt` convention](https://llmstxt.org/),
making them discoverable by AI search engines.

Every page on the site also has an **LLM-optimized** section in the right-hand sidebar
that points to:
* This "LLM-optimized documentation" page (for explanation).
* An LLM-optimized version of that page.
* An LLM-optimized single file containing the whole section (only on top pages of key sections).
* The full site index for LLMs.

All links within LLM-optimized files use absolute URLs (`https://www.union.ai/docs/...`),
so files work correctly when copied locally and used outside the docs site.

## Per-page Markdown (`page.md`)

Every page on this site has a parallel LLM-optimized version in clean Markdown,
accessible at the same URL path with `/page.md` appended and via the "**This page**" link in the "**LLM-optimized**" section of the right sidebar.
For example, this page is at:

* **LLM-optimized documentation**

and its LLM-optimized version is at:

* **LLM-optimized documentation**

Section landing pages include a `## Subpages` table listing child pages with their H2/H3 headings,
making it easy to identify the right page to fetch.

## Section bundles (`section.md`)

For key documentation sections, a curated bundle file concatenates all pages in the section
into a single `section.md` file.

These are accessible at the same URL path as the top page of the section, with `/section.md` appended and via the "**This section in one file**" link in the "**LLM-optimized**" section of the right sidebar.

These `section.md` files are sized to fit within modern LLM context windows
and are ideal for pasting into a prompt or adding to project context.

Available bundle files:

{{< llm-readable-list >}}

## Page index (`llms.txt`)

The `llms.txt` file is a compact index of all LLM-optimized pages, organized by section.
Each page entry includes the H2/H3 headings found on that page, so an agent can identify
the right page to fetch without downloading it first.

Sections that have a `section.md` bundle are marked in the index.

Download it and append its contents to the `AGENTS.md`, `CLAUDE.md` or similar file in your project root.
Make sure you append the index into a file that is **loaded into context by default** by your coding tool.
Adding it as a skill or tool is less effective because the agent must decide to load it
rather than having the information always available.

* [`llms.txt`](https://www.union.ai/docs/v2/union/llms.txt) (~32K tokens)

> [!NOTE]
> You are viewing the **Union.ai** docs.
> To get the `llms.txt` for a different product variant, use the variant selector at the top of the page.

## Full documentation (`llms-full.txt`)

The `llms-full.txt` file contains the entire Union.ai version 2.0 documentation as a single Markdown file.
This file is very large and is not suitable for direct inclusion in an LLM context window,
but it may be useful for RAG-based tools.

* [`llms-full.txt`](https://www.union.ai/docs/v2/union/llms-full.txt) (~1.4M tokens)

> [!NOTE]
> You are viewing the **Union.ai** docs.
> To get the `llms-full.txt` for a different product variant, use the variant selector at the top of the page.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/migration ===

# Migration from Flyte 1 to Flyte 2

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

This section provides a comprehensive reference for migrating Flyte 1 (flytekit) workflows to Flyte 2 (flyte SDK).

For a quick-start overview of the migration process, see **From Flyte 1 to 2 > Migration from Flyte 1 to Flyte 2** in the User Guide.

## Key API changes at a glance

| Use case                      | Flyte 1                     | Flyte 2                                 |
| ----------------------------- | --------------------------- | --------------------------------------- |
| Environment management        | N/A                         | `TaskEnvironment`                       |
| Perform basic computation     | `@task`                     | `@env.task`                             |
| Combine tasks into a workflow | `@workflow`                 | `@env.task`                             |
| Create dynamic workflows      | `@dynamic`                  | `@env.task`                             |
| Fanout parallelism            | `flytekit.map`              | Python `for` loop with `asyncio.gather` |
| Conditional execution         | `flytekit.conditional`      | Python `if-elif-else`                   |
| Catching workflow failures    | `@workflow(on_failure=...)` | Python `try-except`                     |

## Topics

### **Migration from Flyte 1 to Flyte 2 > Philosophy and imports**

Key paradigm shifts and package import mapping from flytekit to flyte.

### **Migration from Flyte 1 to Flyte 2 > Container images**

Migrate from ImageSpec to flyte.Image with the fluent builder API.

### **Migration from Flyte 1 to Flyte 2 > Configuration and CLI**

Config file format changes and CLI command mapping.

### **Migration from Flyte 1 to Flyte 2 > Tasks and workflows**

Migrate @task, @workflow, and @dynamic to TaskEnvironment and @env.task.

### **Migration from Flyte 1 to Flyte 2 > Secrets, resources, and caching**

Updated patterns for secrets access, resource configuration, and caching.

### **Migration from Flyte 1 to Flyte 2 > Parallelism and async**

Migrate map_task to flyte.map and asyncio.gather patterns.

### **Migration from Flyte 1 to Flyte 2 > Triggers and dynamic workflows**

Migrate LaunchPlan schedules to Triggers and @dynamic to regular tasks.

### **Migration from Flyte 1 to Flyte 2 > Examples and common gotchas**

Complete migration examples and common pitfalls to avoid.

## Subpages
- **Migration from Flyte 1 to Flyte 2 > Philosophy and imports**
- **Migration from Flyte 1 to Flyte 2 > Container images**
- **Migration from Flyte 1 to Flyte 2 > Configuration and CLI**
- **Migration from Flyte 1 to Flyte 2 > Tasks and workflows**
- **Migration from Flyte 1 to Flyte 2 > Secrets, resources, and caching**
- **Migration from Flyte 1 to Flyte 2 > Parallelism and async**
- **Migration from Flyte 1 to Flyte 2 > Triggers and dynamic workflows**
- **Migration from Flyte 1 to Flyte 2 > Examples and common gotchas**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/migration/overview ===

# Philosophy and imports

## Key paradigm shifts

| Concept | Flyte 1 (flytekit) | Flyte 2 (flyte) |
|---------|--------------|------------|
| Workflow definition | `@workflow` decorator (DSL-constrained) | Tasks calling tasks (pure Python) |
| Task configuration | Per-task decorator parameters | `TaskEnvironment` (shared config) |
| Parallelism | `map_task()` function | `flyte.map()` or `asyncio.gather()` |
| Conditionals | `flytekit.conditional()` | Native Python `if/else` |
| Error handling | Decorator-based retries | Python `try/except` + retries |
| Execution model | Static DAG compilation | Dynamic pure Python execution |

## What Flyte 2 eliminates

- **`@workflow` decorator**: No longer exists. Workflows are just tasks that call other tasks.
- **`@dynamic` decorator**: No longer needed. All tasks can have dynamic behavior.
- **DSL constraints**: No more restrictions on what Python constructs you can use.
- **Separate workflow/task execution contexts**: Everything runs as a task.

## What Flyte 2 introduces

- **`TaskEnvironment`**: Centralized configuration for groups of tasks.
- **Native async support**: First-class `async/await` with distributed execution.
- **`flyte.map()`**: Simplified parallel execution with generator support.
- **`Trigger`**: Task-based scheduling (replaces LaunchPlan schedules).
- **Pure Python workflows**: Full Python flexibility in orchestration logic.

For more on the pure Python model, see **From Flyte 1 to 2 > Pure Python**.
For more on the async model, see **From Flyte 1 to 2 > Asynchronous model**.

## Package imports

### Basic import changes

### Flyte 1

```python
import flytekit
from flytekit import task, workflow, dynamic, map_task
from flytekit import ImageSpec, Resources, Secret
from flytekit import current_context, LaunchPlan, CronSchedule
```

### Flyte 2

```python
import flyte
from flyte import TaskEnvironment, Resources, Secret
from flyte import Image, Trigger, Cron
```

### Import mapping table

| Flyte 1 import | Flyte 2 import | Notes |
|-----------|-----------|-------|
| `flytekit.task` | `env.task` | Decorator from TaskEnvironment |
| `flytekit.workflow` | `env.task` | Workflows are now tasks |
| `flytekit.dynamic` | `env.task` | All tasks can be dynamic |
| `flytekit.map_task` | `flyte.map` / `asyncio.gather` | Different API |
| `flytekit.ImageSpec` | `flyte.Image` | Different API |
| `flytekit.Resources` | `flyte.Resources` | Similar API |
| `flytekit.Secret` | `flyte.Secret` | Different access pattern |
| `flytekit.current_context()` | `flyte.ctx()` | Different API |
| `flytekit.LaunchPlan` | `flyte.Trigger` | Different concept |
| `flytekit.CronSchedule` | `flyte.Cron` | Used with Trigger |
| `flytekit.conditional` | Native `if/else` | No longer needed |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/migration/images ===

# Container images

Flyte 1's `ImageSpec` is replaced by Flyte 2's `flyte.Image` with a fluent builder API.

## Basic migration

### Flyte 1

```python
from flytekit import ImageSpec

image_spec = ImageSpec(
    name="my-image",
    registry="ghcr.io/myorg",
    python_version="3.11",
    packages=["pandas", "numpy"],
    apt_packages=["curl", "git"],
    env={"MY_VAR": "value"},
)

@task(container_image=image_spec)
def my_task(): ...
```

### Flyte 2

```python
from flyte import Image, TaskEnvironment

image = (
    Image.from_debian_base(
        name="my-image",
        registry="ghcr.io/myorg",
        python_version=(3, 11),
    )
    .with_pip_packages("pandas", "numpy")
    .with_apt_packages("curl", "git")
    .with_env_vars({"MY_VAR": "value"})
)

env = TaskEnvironment(name="my_env", image=image)

@env.task
def my_task(): ...
```

## Image constructor methods

| Method | Description | Use case |
|--------|-------------|----------|
| `Image.from_debian_base()` | Start from Flyte's Debian base | Most common, includes Flyte SDK |
| `Image.from_base(image_uri)` | Start from any existing image | Custom base images |
| `Image.from_dockerfile(path)` | Build from Dockerfile | Complex custom builds |
| `Image.from_uv_script(path)` | Build from UV script | UV-based projects |

## Image builder methods (chainable)

```python
image = (
    Image.from_debian_base(
        python_version=(3, 12),
        registry="ghcr.io/myorg",
        name="my-image",
    )
    # Python packages
    .with_pip_packages("pandas", "numpy>=1.24.0", pre=True)
    .with_requirements(Path("requirements.txt"))
    .with_uv_project(Path("pyproject.toml"))
    .with_poetry_project(Path("pyproject.toml"))

    # System packages
    .with_apt_packages("curl", "git", "build-essential")

    # Custom commands
    .with_commands([
        "mkdir -p /app/data",
        "chmod +x /app/scripts/*.sh",
    ])

    # Files
    .with_source_file(Path("config.yaml"), dst="/app/config.yaml")
    .with_source_folder(Path("./src"), dst="/app/src")
    .with_dockerignore(Path(".dockerignore"))

    # Environment
    .with_env_vars({"LOG_LEVEL": "INFO", "WORKERS": "4"})
    .with_workdir("/app")
)
```

## Builder configuration (local vs remote)

Flyte 2 supports two build modes:

**Local builder** (default): Builds using local Docker and pushes to registry. Requires Docker installed and authenticated to registry.

**Remote builder** (Union instances): Builds on Union's ImageBuilder. No local Docker required. Faster in CI/CD.

```yaml
# In config file
image:
  builder: local  # or "remote"
```

```python
# Or via code
flyte.init(image_builder="local")  # or "remote"
flyte.init_from_config(image_builder="local")  # or "remote"
```

## Private registry with secrets

### Flyte 1

```python
image_spec = ImageSpec(
    registry="private.registry.com",
    registry_config="/path/to/config.json",
)
```

### Flyte 2

First create the secret:
```shell
flyte create secret --type image_pull my-registry-secret --from-file ~/.docker/config.json
```

Then reference it in the image:
```python
image = Image.from_debian_base(
    registry="private.registry.com",
    name="my-image",
    registry_secret="my-registry-secret",
)
```

## Parameter mapping

| Flyte 1 ImageSpec | Flyte 2 Image | Notes |
|--------------|----------|-------|
| `name` | `name` (in constructor) | Same |
| `registry` | `registry` (in constructor) | Same |
| `python_version` | `python_version` (tuple) | `"3.11"` becomes `(3, 11)` |
| `packages` | `.with_pip_packages()` | Method instead of param |
| `apt_packages` | `.with_apt_packages()` | Method instead of param |
| `conda_packages` | N/A | Use micromamba or custom base |
| `requirements` | `.with_requirements()` | Supports txt, poetry.lock, uv.lock |
| `env` | `.with_env_vars()` | Method instead of param |
| `commands` | `.with_commands()` | Method instead of param |
| `copy` | `.with_source_file/folder()` | More explicit methods |
| `source_root` | `.with_source_folder()` | Method instead of param |
| `pip_index` | `index_url` param in `.with_pip_packages()` | Moved to method |
| `pip_extra_index_url` | `extra_index_urls` param | Moved to method |
| `base_image` | `Image.from_base()` | Different constructor |
| `builder` | Config file or `flyte.init()` | Global setting |
| `platform` | `platform` (in constructor) | Tuple: `("linux/amd64", "linux/arm64")` |

For full details on container images in Flyte 2, see **Configure tasks > Container images**.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/migration/configuration-and-cli ===

# Configuration and CLI

## Configuration files

### Config file location

| Version | Default location | Environment variable |
|---------|-----------------|---------------------|
| Flyte 1 | `~/.flyte/config.yaml` | `FLYTECTL_CONFIG` |
| Flyte 2 | `~/.flyte/config.yaml` | `FLYTE_CONFIG` |

### Config format

### Flyte 1

```yaml
union:
  connection:
    host: dns:///your-cluster.hosted.unionai.cloud
    insecure: false
  auth:
    type: Pkce
admin:
  endpoint: dns:///your-cluster.hosted.unionai.cloud
  insecure: false
  authType: Pkce
```

### Flyte 2

```yaml
admin:
  endpoint: dns:///your-cluster.hosted.unionai.cloud

image:
  builder: remote  # or "local"

task:
  domain: development
  org: your-org
  project: your-project
```

### Key config differences

| Setting | Flyte 1 location | Flyte 2 location |
|---------|-------------|-------------|
| Endpoint | `admin.endpoint` or `union.connection.host` | `admin.endpoint` |
| Auth type | `admin.authType` or `union.auth.type` | Generally auto-detected (PKCE default) |
| Project | CLI flag `-p` | `task.project` (can set default) |
| Domain | CLI flag `-d` | `task.domain` (can set default) |
| Organization | CLI flag `--org` | `task.org` (can set default) |
| Image builder | N/A | `image.builder` (`local` or `remote`) |

### Specifying config via CLI

### Flyte 1

```shell
pyflyte --config ~/.flyte/config.yaml run ...
```

### Flyte 2

```shell
flyte --config ~/.flyte/config.yaml run ...
flyte -c ~/.flyte/config.yaml run ...
```

### Specifying config in code

```python
import flyte

# From config file
flyte.init_from_config()  # Auto-discovers config
flyte.init_from_config("path/to/config.yaml")  # Explicit path

# Programmatic configuration
flyte.init(
    endpoint="flyte.example.com",
    insecure=False,
    project="my-project",
    domain="development",
)
```

## CLI commands

### Command mapping

| Flyte 1 command | Flyte 2 command | Notes |
|------------|------------|-------|
| `pyflyte run` | `flyte run` | Similar but different flags |
| `pyflyte run --remote` | `flyte run` | Remote is default in Flyte 2 |
| `pyflyte run` (no --remote) | `flyte run --local` | Local execution |
| `pyflyte register` | `flyte deploy` | Different concept |
| `pyflyte package` | N/A | Not needed in Flyte 2 |
| `pyflyte serialize` | N/A | Not needed in Flyte 2 |

### Running tasks

### Flyte 1

```shell
# Run locally
pyflyte run my_module.py my_workflow --arg1 value1

# Run remotely
pyflyte --config config.yaml run --remote my_module.py my_workflow --arg1 value1
```

### Flyte 2

```shell
# Run remotely (default)
flyte run my_module.py my_task --arg1 value1

# Run locally
flyte run --local my_module.py my_task --arg1 value1

# With explicit config
flyte --config config.yaml run my_module.py my_task --arg1 value1
```

### Key CLI flag differences

| Flyte 1 flag | Flyte 2 flag | Notes |
|---------|---------|-------|
| `--remote` | (default) | Remote is default in Flyte 2 |
| `--copy-all` | `--copy-style all` | File copying |
| N/A | `--copy-style loaded_modules` | Default: only imported modules |
| N/A | `--copy-style none` | Don't copy files |
| `-p, --project` | `--project` | Same |
| `-d, --domain` | `--domain` | Same |
| `-i, --image` | `--image` | Same format |
| N/A | `--follow, -f` | Follow execution logs |

### Deploying

### Flyte 1

```shell
pyflyte register my_module.py -p my-project -d development
```

### Flyte 2

```shell
# Deploy task environments
flyte deploy my_module.py my_env --project my-project --domain development

# Deploy all environments in file
flyte deploy --all my_module.py

# Deploy with version
flyte deploy --version v1.0.0 my_module.py my_env

# Recursive deployment
flyte deploy --recursive --all ./src

# Dry run (preview)
flyte deploy --dry-run my_module.py my_env
```

### Running deployed tasks

```shell
# Run a deployed task
flyte run deployed-task my_env.my_task --arg1 value1

# Run specific version
flyte run deployed-task my_env.my_task:v1.0.0 --arg1 value1
```

### Complete Flyte 2 CLI options

```shell
# Global options
flyte --endpoint <URL>                     # Override endpoint
flyte --config <PATH>                      # Config file path
flyte --org <TEXT>                          # Organization
flyte -v, --verbose                        # Verbose output (can repeat: -vvv)
flyte --output-format [table|json]         # Output format

# Run command options
flyte run [OPTIONS] <file> <task> [TASK_ARGS]
  --local                                  # Run locally
  --project <TEXT>                         # Project
  --domain <TEXT>                          # Domain
  --copy-style [loaded_modules|all|none]   # File copying
  --root-dir <PATH>                        # Source root directory
  --follow, -f                             # Follow logs
  --image [NAME=]URI                       # Image override
  --name <TEXT>                            # Execution name
  --service-account <TEXT>                 # K8s service account

# Deploy command options
flyte deploy [OPTIONS] <file> [ENV_NAME]
  --project <TEXT>                         # Project
  --domain <TEXT>                          # Domain
  --version <TEXT>                         # Version
  --dry-run                                # Preview without deploying
  --copy-style [loaded_modules|all|none]   # File copying
  --recursive, -r                          # Deploy recursively
  --all                                    # Deploy all environments
  --image [NAME=]URI                       # Image override
```

For full CLI reference, see **Flyte CLI**.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/migration/tasks-and-workflows ===

# Tasks and workflows

## Basic task migration

### Flyte 1

```python
from flytekit import task, Resources

@task(
    cache=True,
    cache_version="1.0",
    retries=3,
    timeout=3600,
    container_image="python:3.11",
    requests=Resources(cpu="1", mem="2Gi"),
    limits=Resources(cpu="2", mem="4Gi"),
)
def my_task(x: int) -> int:
    return x * 2
```

### Flyte 2

```python
import flyte

env = flyte.TaskEnvironment(
    name="my_env",
    image="python:3.11",
    resources=flyte.Resources(cpu="1", memory="2Gi"),
    cache="auto",
)

@env.task(retries=3, timeout=3600)
def my_task(x: int) -> int:
    return x * 2
```

## Workflow to task migration

In Flyte 2 there is no `@workflow` decorator. Workflows are tasks that call other tasks.

### Flyte 1

```python
from flytekit import task, workflow

@task
def step1(x: int) -> int:
    return x + 1

@task
def step2(y: int) -> int:
    return y * 2

@task
def step3(z: int) -> str:
    return f"Result: {z}"

@workflow
def my_workflow(x: int) -> str:
    a = step1(x=x)
    b = step2(y=a)
    c = step3(z=b)
    return c
```

### Flyte 2 Sync

```python
import flyte

env = flyte.TaskEnvironment(name="my_env")

@env.task
def step1(x: int) -> int:
    return x + 1

@env.task
def step2(y: int) -> int:
    return y * 2

@env.task
def step3(z: int) -> str:
    return f"Result: {z}"

@env.task
def main(x: int) -> str:
    a = step1(x)
    b = step2(a)
    c = step3(b)
    return c
```

### Flyte 2 Async

```python
import flyte

env = flyte.TaskEnvironment(name="my_env")

@env.task
async def step1(x: int) -> int:
    return x + 1

@env.task
async def step2(y: int) -> int:
    return y * 2

@env.task
async def step3(z: int) -> str:
    return f"Result: {z}"

@env.task
async def main(x: int) -> str:
    a = await step1(x)
    b = await step2(a)
    c = await step3(b)
    return c
```

> **📝 Note**
>
> You can only `await` async tasks. If you try to `await` a sync task, it will fail. If your subtasks are sync, call them directly without `await` (they will execute synchronously/sequentially).

## TaskEnvironment configuration

```python
import flyte

env = flyte.TaskEnvironment(
    name="my_env",                           # Required: unique name
    image=flyte.Image.from_debian_base(...), # Or string, or "auto"
    resources=flyte.Resources(
        cpu="2",
        memory="4Gi",
        gpu="A100:1",
        disk="10Gi",
        shm="auto",
    ),
    env_vars={"LOG_LEVEL": "INFO"},
    secrets=[
        flyte.Secret(key="api-key", as_env_var="API_KEY"),
    ],
    cache="auto",  # "auto", "override", "disable", or Cache object
    reusable=flyte.ReusePolicy(replicas=5, idle_ttl=60),
    queue="gpu-queue",
    interruptible=True,
)

# Task decorator can override some settings
@env.task(
    short_name="my_task",      # Display name
    cache="disable",           # Override cache
    retries=3,                 # Retry count
    timeout=3600,              # Seconds or timedelta
    report=True,               # Generate HTML report
)
def my_task(x: int) -> int:
    return x
```

## Parameter mapping: @task to TaskEnvironment + @env.task

| Flyte 1 `@task` parameter | Flyte 2 location | Notes |
|--------------------|-------------|-------|
| `container_image` | `TaskEnvironment(image=...)` | Env-level only |
| `requests` | `TaskEnvironment(resources=...)` | Env-level only |
| `limits` | `TaskEnvironment(resources=...)` | Combined with requests |
| `environment` | `TaskEnvironment(env_vars=...)` | Env-level only |
| `secret_requests` | `TaskEnvironment(secrets=...)` | Env-level only |
| `cache` | Both | Can override at task level |
| `cache_version` | `flyte.Cache(version_override=...)` | In Cache object |
| `retries` | `@env.task(retries=...)` | Task-level only |
| `timeout` | `@env.task(timeout=...)` | Task-level only |
| `interruptible` | Both | Can override at task level |
| `pod_template` | Both | Can override at task level |
| `deprecated` | N/A | Not in Flyte 2 |
| `docs` | `@env.task(docs=...)` | Task-level only |

For full details, see [Configure tasks](../../../user-guide/task-configuration/_index).


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/migration/secrets-resources-caching ===

# Secrets, resources, and caching

## Secrets

### Declaring and accessing secrets

### Flyte 1

```python
from flytekit import task, Secret, current_context

@task(secret_requests=[
    Secret(group="mygroup", key="mykey"),
    Secret(group="db", key="password", mount_requirement=Secret.MountType.ENV_VAR),
])
def my_task() -> str:
    ctx = current_context()
    secret_value = ctx.secrets.get(key="mykey", group="mygroup")
    db_password = ctx.secrets.get(key="password", group="db")
    return f"Got secrets"
```

### Flyte 2

```python
import flyte
import os

env = flyte.TaskEnvironment(
    name="my_env",
    secrets=[
        flyte.Secret(key="mykey", as_env_var="MY_SECRET"),
        flyte.Secret(key="db-password", as_env_var="DB_PASSWORD"),
    ],
)

@env.task
def my_task() -> str:
    secret_value = os.environ["MY_SECRET"]
    db_password = os.environ["DB_PASSWORD"]
    return f"Got secrets"
```

### Secret configuration options

```python
# Flyte 2 Secret options
flyte.Secret(
    key="secret-name",                    # Required: secret key in store
    group="optional-group",               # Optional: organizational group
    as_env_var="CUSTOM_ENV_VAR_NAME",    # Mount as this env var name
    # OR
    mount="/etc/flyte/secrets",           # Mount as file (fixed path)
)

# Examples
secrets=[
    # Simple: key becomes uppercase env var (MY_API_KEY)
    flyte.Secret(key="my-api-key"),

    # Custom env var name
    flyte.Secret(key="openai-key", as_env_var="OPENAI_API_KEY"),

    # With group (env var: AWS_ACCESS_KEY)
    flyte.Secret(key="access-key", group="aws"),

    # As file
    flyte.Secret(key="ssl-cert", mount="/etc/flyte/secrets"),
]
```

### Secret name convention changes

| Flyte 1 pattern | Flyte 2 pattern |
|------------|------------|
| `ctx.secrets.get(key="mykey", group="mygroup")` | `os.environ["MYGROUP_MYKEY"]` (auto-named) |
| `ctx.secrets.get(key="mykey")` | `os.environ["MY_SECRET"]` (with `as_env_var`) |

### Creating secrets via CLI

```bash
# Create secret
flyte create secret MY_SECRET_KEY my_secret_value

# From file
flyte create secret MY_SECRET_KEY --from-file /path/to/secret

# Scoped to project/domain
flyte create secret --project my-project --domain development MY_SECRET_KEY value

# List secrets
flyte get secret

# Delete secret
flyte delete secret MY_SECRET_KEY
```

For full details on secrets, see **Configure tasks > Secrets**.

## Resources

### Basic resource configuration

### Flyte 1

```python
from flytekit import task, Resources

# Separate requests and limits
@task(
    requests=Resources(cpu="1", mem="2Gi"),
    limits=Resources(cpu="2", mem="4Gi"),
)
def my_task(): ...

# Unified resources (tuple for request/limit)
@task(resources=Resources(cpu=("1", "2"), mem="2Gi"))
def my_task(): ...
```

### Flyte 2

```python
import flyte

env = flyte.TaskEnvironment(
    name="my_env",
    resources=flyte.Resources(
        cpu="2",           # Request and limit same
        memory="4Gi",      # Note: "memory" not "mem"
        gpu="A100:1",      # GPU type and count
        disk="10Gi",
        shm="auto",        # Shared memory
    ),
)
```

### GPU configuration

### Flyte 1

```python
from flytekit import task, Resources
from flytekit.extras.accelerators import A100

@task(
    requests=Resources(gpu="1"),
    accelerator=A100,
)
def gpu_task(): ...
```

### Flyte 2

```python
import flyte

env = flyte.TaskEnvironment(
    name="gpu_env",
    resources=flyte.Resources(
        cpu="4",
        memory="32Gi",
        gpu="A100:2",         # Type:count format
        # Or: gpu="A100 80G:1"
        # Or: gpu=2            # Count only, no type
    ),
)

# GPU with partition (MIG)
env = flyte.TaskEnvironment(
    name="mig_env",
    resources=flyte.Resources(
        gpu=flyte.GPU("A100", count=1, partition="1g.5gb"),
    ),
)
```

### Supported GPU types (Flyte 2)

- A10, A10G, A100, A100 80G
- B200, H100, H200
- L4, L40s
- T4, V100
- RTX PRO 6000, GB10

### Resource parameter mapping

| Flyte 1 | Flyte 2 | Notes |
|----|----| ------|
| `cpu="1"` | `cpu="1"` | Same |
| `mem="2Gi"` | `memory="2Gi"` | Renamed |
| `gpu="1"` | `gpu="A100:1"` | Type:count format |
| `ephemeral_storage="10Gi"` | `disk="10Gi"` | Renamed |
| N/A | `shm="auto"` | New: shared memory |

For full details on resources, see **Configure tasks > Resources**.

## Caching

### Basic caching

### Flyte 1

```python
from flytekit import task, Cache

@task(cache=True, cache_version="1.0")
def cached_task(x: int) -> int:
    return x * 2

# With Cache object
@task(cache=Cache(
    version="1.0",
    serialize=True,
    ignored_inputs=("debug",),
))
def advanced_cached_task(x: int, debug: bool = False) -> int:
    return x * 2
```

### Flyte 2

```python
import flyte

env = flyte.TaskEnvironment(
    name="my_env",
    cache="auto",  # Enable caching at env level
)

@env.task
def cached_task(x: int) -> int:
    return x * 2

# Override at task level
@env.task(cache="disable")
def uncached_task(x: int) -> int:
    return x * 2

# Advanced caching
@env.task(cache=flyte.Cache(
    behavior="auto",           # "auto", "override", "disable"
    version_override="v1.0",   # Explicit version
    serialize=True,            # Force serial execution
    ignored_inputs=("debug",), # Exclude from hash
    salt="my-salt",            # Additional hash salt
))
def advanced_cached_task(x: int, debug: bool = False) -> int:
    return x * 2
```

### Cache behavior options (Flyte 2)

| Behavior | Description |
|----------|-------------|
| `"auto"` | Cache results and reuse if available |
| `"override"` | Always execute and overwrite cache |
| `"disable"` | No caching (default for TaskEnvironment) |

For full details on caching, see **Configure tasks > Caching**.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/migration/parallelism-and-async ===

# Parallelism and async

## Basic map_task migration

### Flyte 1

```python
from flytekit import task, workflow, map_task

@task
def process_item(x: int) -> int:
    return x * 2

@workflow
def my_workflow(items: list[int]) -> list[int]:
    return map_task(process_item)(x=items)
```

### Flyte 2

```python
import flyte

env = flyte.TaskEnvironment(name="my_env")

@env.task
def process_item(x: int) -> int:
    return x * 2

@env.task
def main(items: list[int]) -> list[int]:
    return list(flyte.map(process_item, items))
```

## map_task with concurrency

### Flyte 1

```python
@workflow
def my_workflow(items: list[int]) -> list[int]:
    return map_task(process_item, concurrency=5)(x=items)
```

### Flyte 2

```python
@env.task
def main(items: list[int]) -> list[int]:
    return list(flyte.map(process_item, items, concurrency=5))
```

## Async parallel execution with asyncio.gather

This is the recommended approach for parallel execution in Flyte 2.

```python
import asyncio
import flyte

env = flyte.TaskEnvironment(name="my_env")

@env.task
async def process_item(item: int) -> str:
    return f"processed_{item}"

@env.task
async def main(items: list[int]) -> list[str]:
    tasks = [process_item(item) for item in items]
    results = await asyncio.gather(*tasks)
    return list(results)
```

## Concurrency control with semaphore

```python
import asyncio

@env.task
async def process_item(item: int) -> str:
    await asyncio.sleep(1)
    return f"processed_{item}"

@env.task
async def main_with_concurrency_limit(
    items: list[int],
    max_concurrent: int = 5
) -> list[str]:
    semaphore = asyncio.Semaphore(max_concurrent)

    async def process_with_limit(item: int) -> str:
        async with semaphore:
            return await process_item(item)

    tasks = [process_with_limit(item) for item in items]
    results = await asyncio.gather(*tasks)
    return list(results)
```

## Error handling with asyncio.gather

```python
@env.task
async def main_with_error_handling(
    items: list[int],
    max_concurrent: int = 5
) -> list[str]:
    semaphore = asyncio.Semaphore(max_concurrent)

    async def process_with_limit(item: int) -> str:
        async with semaphore:
            return await process_item(item)

    tasks = [process_with_limit(item) for item in items]
    results = await asyncio.gather(*tasks, return_exceptions=True)

    processed = []
    for i, result in enumerate(results):
        if isinstance(result, Exception):
            print(f"Item {items[i]} failed: {result}")
            processed.append(f"Failed: {items[i]}")
        else:
            processed.append(result)
    return processed
```

## flyte.map vs asyncio.gather comparison

| Feature | flyte.map (sync) | asyncio.gather (async) |
|---------|------------------|------------------------|
| Syntax | `list(flyte.map(fn, items))` | `await asyncio.gather(*tasks)` |
| Concurrency limit | Built-in `concurrency=N` | Use `asyncio.Semaphore` |
| Streaming/as-completed | No control | Yes, via `asyncio.as_completed()` |
| Error handling | `return_exceptions=True` | Check return type |
| Flexibility | Less flexible | More flexible |

## Recommended pattern selection

Use **flyte.map** when:
- You are forced to use synchronous Python
- You want minimal code changes from Flyte 1 `map_task`

Use **asyncio.gather** when (recommended):
- You want maximum flexibility and control
- You need streaming results (`asyncio.as_completed`)
- You need fine-grained concurrency control (semaphores)
- You're writing new Flyte 2 code

## Sync and async task patterns

Keep task types consistent within a call chain for clarity and predictability.

### Sync tasks calling sync tasks

```python
import flyte

env = flyte.TaskEnvironment(name="my_env")

@env.task
def step1(x: int) -> int:
    return x + 1

@env.task
def step2(y: int) -> int:
    return y * 2

@env.task
def main(x: int) -> int:
    a = step1(x)   # Runs, returns result
    b = step2(a)   # Runs after step1 completes
    return b
```

### Async tasks calling async tasks

```python
import flyte

env = flyte.TaskEnvironment(name="my_env")

@env.task
async def step1(x: int) -> int:
    return x + 1

@env.task
async def step2(y: int) -> int:
    return y * 2

@env.task
async def main(x: int) -> int:
    a = await step1(x)   # Runs, waits for result
    b = await step2(a)   # Runs after step1 completes
    return b
```

### Sequential execution with await

When you `await` async tasks one after another, they run sequentially, just like Flyte 1 workflows:

### Flyte 1

```python
@workflow
def my_workflow(x: int) -> str:
    a = step1(x=x)      # Runs first
    b = step2(y=a)      # Runs second
    c = step3(z=b)      # Runs third
    return c
```

### Flyte 2

```python
@env.task
async def main(x: int) -> str:
    a = await step1(x)      # Runs first
    b = await step2(a)      # Runs second
    c = await step3(b)      # Runs third
    return c
```

> **📝 Note**
>
> `await` means "wait for this to finish before continuing." Sequential `await` calls behave the same as sequential task calls in Flyte 1 workflows.

For full details on async patterns, see **From Flyte 1 to 2 > Asynchronous model**.
For full details on parallel fanout, see **Build tasks > Fanout**.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/migration/triggers-and-dynamic ===

# Triggers and dynamic workflows

## LaunchPlan to Trigger migration

### Flyte 1

```python
from flytekit import workflow, LaunchPlan, CronSchedule, FixedRate
from datetime import timedelta

@workflow
def my_workflow(x: int) -> int:
    return process(x)

# Cron schedule
cron_lp = LaunchPlan.get_or_create(
    workflow=my_workflow,
    name="hourly_run",
    default_inputs={"x": 10},
    schedule=CronSchedule(schedule="0 * * * *"),
)

# Fixed rate
rate_lp = LaunchPlan.get_or_create(
    workflow=my_workflow,
    name="frequent_run",
    default_inputs={"x": 5},
    schedule=FixedRate(duration=timedelta(minutes=30)),
)
```

### Flyte 2

```python
import flyte

env = flyte.TaskEnvironment(name="my_env")

# Hourly trigger (convenience method)
@env.task(triggers=flyte.Trigger.hourly())
def hourly_task(x: int = 10) -> int:
    return process(x)

# Custom cron trigger
cron_trigger = flyte.Trigger(
    name="custom_cron",
    automation=flyte.Cron("0 * * * *"),
    inputs={"x": 10},
    auto_activate=True,
)

@env.task(triggers=cron_trigger)
def scheduled_task(x: int) -> int:
    return process(x)

# Fixed rate trigger
rate_trigger = flyte.Trigger(
    name="frequent",
    automation=flyte.FixedRate(timedelta(minutes=30)),
    inputs={"x": 5},
    auto_activate=True,
)

@env.task(triggers=rate_trigger)
def frequent_task(x: int) -> int:
    return process(x)
```

## Trigger options

```python
# Convenience methods
flyte.Trigger.hourly()           # Every hour
flyte.Trigger.hourly("my_time")  # Custom time parameter name
flyte.Trigger.minutely()         # Every minute

# Custom Trigger
flyte.Trigger(
    name="my_trigger",           # Required: trigger name
    automation=flyte.Cron(...),  # Cron or FixedRate
    inputs={"x": 10},            # Default inputs
    auto_activate=True,          # Activate on deploy
)

# Cron options
flyte.Cron(
    schedule="0 9 * * 1-5",      # 9 AM weekdays
    timezone="America/New_York", # Optional timezone
)

# FixedRate options
flyte.FixedRate(timedelta(hours=1))  # Every hour
```

## Deploying triggers

```bash
# Deploy environment (triggers deploy with it)
flyte deploy my_module.py my_env

# Triggers with auto_activate=True activate automatically
# Otherwise, activate manually via UI or API
```

For full details on triggers, see **Configure tasks > Triggers**.

## Dynamic workflows

In Flyte 1, `@dynamic` was needed for tasks that generate variable numbers of subtask calls at runtime. In Flyte 2, all tasks can have dynamic behavior natively.

### @dynamic to regular tasks

### Flyte 1

```python
from flytekit import dynamic, task, workflow

@task
def get_tiles(n: int) -> list[int]:
    return list(range(n))

@task
def process_tile(tile: int) -> int:
    return tile * 2

@dynamic
def process_all_tiles(tiles: list[int]) -> list[int]:
    results = []
    for tile in tiles:
        results.append(process_tile(tile=tile))
    return results

@workflow
def main_workflow(n: int) -> list[int]:
    tiles = get_tiles(n=n)
    return process_all_tiles(tiles=tiles)
```

### Flyte 2 Sync

```python
import flyte

env = flyte.TaskEnvironment(name="my_env")

@env.task
def process_tile(tile: int) -> int:
    return tile * 2

@env.task
def process_all_tiles(tiles: list[int]) -> list[int]:
    results = []
    for tile in tiles:
        results.append(process_tile(tile))
    return results

@env.task
def main(n: int) -> list[int]:
    tiles = list(range(n))
    return process_all_tiles(tiles)
```

### Flyte 2 Async

```python
import flyte

env = flyte.TaskEnvironment(name="my_env")

@env.task
async def process_tile(tile: int) -> int:
    return tile * 2

@env.task
async def process_all_tiles(tiles: list[int]) -> list[int]:
    results = []
    for tile in tiles:
        results.append(await process_tile(tile))
    return results

@env.task
async def main(n: int) -> list[int]:
    tiles = list(range(n))
    return await process_all_tiles(tiles)
```

## Conditional execution

### Flyte 1

```python
from flytekit import conditional

@workflow
def conditional_wf(x: int) -> int:
    return (
        conditional("test")
        .if_(x > 0)
        .then(positive_task(x=x))
        .else_()
        .then(negative_task(x=x))
    )
```

### Flyte 2

```python
@env.task
def main(x: int) -> int:
    if x > 0:
        return positive_task(x)
    else:
        return negative_task(x)
```

## Subworkflows to nested tasks

### Flyte 1

```python
@workflow
def sub_workflow(x: int) -> int:
    a = step1(x)
    b = step2(a)
    return b

@workflow
def main_workflow(item: int) -> int:
    result = sub_workflow(x=item)
    return result
```

### Flyte 2

```python
@env.task
def sub_task(x: int) -> int:
    a = step1(x)
    b = step2(a)
    return b

@env.task
def main(item: int) -> int:
    result = sub_task(item)
    return result
```


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/migration/examples-and-gotchas ===

# Examples and common gotchas

## Complete migration examples

### Example 1: Simple ML pipeline

### Flyte 1

```python
from flytekit import task, workflow, ImageSpec, Resources, current_context
from flytekit.types.file import FlyteFile
import pandas as pd
from sklearn.ensemble import RandomForestClassifier
import joblib
import os

image = ImageSpec(
    name="ml-image",
    packages=["pandas", "scikit-learn", "joblib", "pyarrow"],
    builder="union",
)

@task(
    container_image=image,
    requests=Resources(cpu="2", mem="4Gi"),
    cache=True,
    cache_version="1.1",
)
def load_data() -> pd.DataFrame:
    CSV_URL = "https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv"
    return pd.read_csv(CSV_URL)

@task(container_image=image)
def train_model(data: pd.DataFrame) -> FlyteFile:
    model = RandomForestClassifier()
    X = data.drop("species", axis=1)
    y = data["species"]
    model.fit(X, y)

    model_path = os.path.join(current_context().working_directory, "model.joblib")
    joblib.dump(model, model_path)
    return FlyteFile(path=model_path)

@task(container_image=image)
def evaluate(model_file: FlyteFile, data: pd.DataFrame) -> float:
    model = joblib.load(model_file.download())
    X = data.drop("species", axis=1)
    y = data["species"]
    return float(model.score(X, y))

@workflow
def ml_pipeline() -> float:
    data = load_data()
    model = train_model(data=data)
    score = evaluate(model_file=model, data=data)
    return score
```

### Flyte 2

```python
import os
import joblib
import pandas as pd
import flyte
from flyte import TaskEnvironment, Resources, Image
from flyte.io import File
from sklearn.ensemble import RandomForestClassifier

# 1. Define the Image using the fluent builder API
image = (
    Image.from_debian_base(
        name="ml-image",
        python_version=(3, 11),
    )
    .with_pip_packages("pandas", "scikit-learn", "joblib", "pyarrow")
)

# 2. Define the TaskEnvironment
env = TaskEnvironment(
    name="ml_env",
    image=image,
    resources=Resources(cpu="2", memory="4Gi"),
    cache="auto",
)

@env.task
async def load_data() -> pd.DataFrame:
    CSV_URL = "https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv"
    return pd.read_csv(CSV_URL)

@env.task
async def train_model(data: pd.DataFrame) -> File:
    model = RandomForestClassifier()
    X = data.drop("species", axis=1)
    y = data["species"]
    model.fit(X, y)

    root_dir = os.getcwd()
    model_path = os.path.join(root_dir, "model.joblib")
    joblib.dump(model, model_path)
    return await File.from_local(model_path)

@env.task
async def evaluate(model_file: File, data: pd.DataFrame) -> float:
    local_path = await model_file.download()
    model = joblib.load(local_path)
    X = data.drop("species", axis=1)
    y = data["species"]
    return float(model.score(X, y))

# 3. The workflow is now just an orchestrating task
@env.task
async def ml_pipeline() -> float:
    data = await load_data()
    model = await train_model(data)
    score = await evaluate(model, data)
    return score
```

### Example 2: Parallel processing with map_task

### Flyte 1

```python
from flytekit import task, workflow, map_task, dynamic
from functools import partial

@task(cache=True, cache_version="1.0")
def get_chunks(n: int) -> list[int]:
    return list(range(n))

@task(cache=True, cache_version="1.0")
def process_chunk(chunk_id: int, multiplier: int) -> int:
    return chunk_id * multiplier

@workflow
def parallel_pipeline(n: int, multiplier: int) -> list[int]:
    chunk_ids = get_chunks(n)
    results = map_task(
        partial(process_chunk, multiplier=multiplier),
        concurrency=10,
    )(chunk_id=chunk_ids)
    return results
```

### Flyte 2 Sync

```python
from functools import partial
import flyte

env = flyte.TaskEnvironment(name="parallel_env", cache="auto")

@env.task
def process_chunk(chunk_id: int, multiplier: int) -> int:
    return chunk_id * multiplier

@env.task
def main(n: int, multiplier: int) -> list[int]:
    chunk_ids = list(range(n))
    bound_task = partial(process_chunk, multiplier=multiplier)
    results = list(flyte.map(bound_task, chunk_ids, concurrency=10))
    return results
```

### Flyte 2 Async

```python
import asyncio
import flyte

env = flyte.TaskEnvironment(name="parallel_env", cache="auto")

@env.task
async def process_chunk(chunk_id: int, multiplier: int) -> int:
    return chunk_id * multiplier

@env.task
async def main(n: int, multiplier: int) -> list[int]:
    chunk_ids = list(range(n))
    sem = asyncio.Semaphore(10)

    async def throttled_task(cid):
        async with sem:
            return await process_chunk(cid, multiplier)

    tasks = [throttled_task(cid) for cid in chunk_ids]
    results = await asyncio.gather(*tasks)
    return list(results)
```

## Common gotchas

### 1. current_context() is replaced

```python
# Flyte 1
ctx = flytekit.current_context()
secret = ctx.secrets.get(key="mykey", group="mygroup")
working_dir = ctx.working_directory
execution_id = ctx.execution_id

# Flyte 2 - Secrets via environment variables
secret = os.environ["MYGROUP_MYKEY"]

# Flyte 2 - Context via flyte.ctx()
ctx = flyte.ctx()
```

### 2. Workflow >> ordering notation is gone

```python
# Flyte 1: Using >> to indicate ordering
@workflow
def my_workflow():
    t1_result = task1()
    t2_result = task2()
    t1_result >> t2_result
    return t2_result

# Flyte 2: Sequential calls are naturally ordered (sync)
@env.task
def main():
    t1_result = task1()  # Runs first
    t2_result = task2()  # Runs second
    return t2_result

# Flyte 2: For async, use await to sequence
@env.task
async def main():
    t1_result = await task1()  # Runs first
    t2_result = await task2()  # Runs second
    return t2_result
```

### 3. flyte.map returns a generator

```python
# Flyte 1: map_task returns list directly
results = map_task(my_task)(items=my_list)

# Flyte 2: flyte.map returns generator - must convert to list
results = list(flyte.map(my_task, my_list))  # Add list()!

# Flyte 2 async: Use asyncio.gather for async parallel execution
tasks = [my_task(item) for item in my_list]
results = await asyncio.gather(*tasks)
```

### 4. Image configuration location

```python
# Flyte 1: Image per task
@task(container_image=my_image)
def task1(): ...

@task(container_image=my_image)  # Repeated
def task2(): ...

# Flyte 2: Image at TaskEnvironment level (DRY)
env = flyte.TaskEnvironment(name="my_env", image=my_image)

@env.task
def task1(): ...  # Uses env's image

@env.task
def task2(): ...  # Uses env's image
```

### 5. Resource configuration

```python
# Flyte 1: Resources per task
@task(requests=Resources(cpu="1"), limits=Resources(cpu="2"))
def my_task(): ...

# Flyte 2: Resources at TaskEnvironment level
env = flyte.TaskEnvironment(
    name="my_env",
    resources=flyte.Resources(cpu="1"),  # No separate limits
)
```

### 6. Cache version

```python
# Flyte 1: Explicit cache_version required
@task(cache=True, cache_version="1.0")
def my_task(): ...

# Flyte 2: Auto-versioning or explicit
@env.task(cache="auto")  # Auto-versioned
def my_task(): ...

@env.task(cache=flyte.Cache(behavior="auto", version_override="1.0"))
def my_task_explicit(): ...
```

### 7. Entrypoint task naming

```python
# Flyte 1: Workflow is the entrypoint
@workflow
def my_workflow(): ...

# Flyte 2: Use a main() task or any task name
@env.task
def main(): ...  # Common convention

# Run with: flyte run my_module.py main
```

### 8. Memory parameter name

```python
# Flyte 1
Resources(mem="2Gi")

# Flyte 2
flyte.Resources(memory="2Gi")  # Note: "memory" not "mem"
```

### 9. Type annotations

```python
# Flyte 1: Strict about type annotations
@task
def my_task(x: int) -> dict:  # Would fail, need dict[str, int]
    return {"a": x}

# Flyte 2: More lenient
@env.task
def my_task(x: int) -> dict:  # Works, v2 will pickle untyped I/O
    return {"a": x}
```

## Quick reference cheat sheet

```python
# FLYTE 2 MINIMAL TEMPLATE
import flyte
import asyncio

# 1. Define image
image = (
    flyte.Image.from_debian_base(python_version=(3, 11))
    .with_pip_packages("pandas", "numpy")
)

# 2. Create TaskEnvironment
env = flyte.TaskEnvironment(
    name="my_env",
    image=image,
    resources=flyte.Resources(cpu="1", memory="2Gi"),
)

# 3. Define tasks
@env.task
async def process(x: int) -> int:
    return x * 2

# 4. Define main entrypoint
@env.task
async def main(items: list[int]) -> list[int]:
    tasks = [process(x) for x in items]
    results = await asyncio.gather(*tasks)
    return list(results)

# 5. Run
if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.run(main, items=[1, 2, 3, 4, 5])
    run.wait()
```

```bash
# CLI COMMANDS
flyte run my_module.py main --items '[1,2,3,4,5]'
flyte run --local my_module.py main --items '[1,2,3,4,5]'
flyte deploy my_module.py my_env
```


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-cli ===

# Flyte CLI

This is the command line interface for Flyte.

| Object | Action |
| ------ | -- |
| `action` | **Flyte CLI > flyte > flyte abort > flyte abort action**, **Flyte CLI > flyte > flyte get > flyte get action**  |
| `run` | **Flyte CLI > flyte > flyte abort > flyte abort run**, **Flyte CLI > flyte > flyte get > flyte get run**  |
| `api-key` | **Flyte CLI > flyte > flyte create > flyte create api-key**, **Flyte CLI > flyte > flyte delete > flyte delete api-key**, **Flyte CLI > flyte > flyte get > flyte get api-key**  |
| `assignment` | **Flyte CLI > flyte > flyte create > flyte create assignment**, **Flyte CLI > flyte > flyte delete > flyte delete assignment**, **Flyte CLI > flyte > flyte get > flyte get assignment**  |
| `config` | **Flyte CLI > flyte > flyte create > flyte create config**, **Flyte CLI > flyte > flyte get > flyte get config**  |
| `policy` | **Flyte CLI > flyte > flyte create > flyte create policy**, **Flyte CLI > flyte > flyte delete > flyte delete policy**, **Flyte CLI > flyte > flyte get > flyte get policy**, **Flyte CLI > flyte > flyte update > flyte update policy**  |
| `project` | **Flyte CLI > flyte > flyte create > flyte create project**, **Flyte CLI > flyte > flyte get > flyte get project**, **Flyte CLI > flyte > flyte update > flyte update project**  |
| `role` | **Flyte CLI > flyte > flyte create > flyte create role**, **Flyte CLI > flyte > flyte delete > flyte delete role**, **Flyte CLI > flyte > flyte get > flyte get role**, **Flyte CLI > flyte > flyte update > flyte update role**  |
| `secret` | **Flyte CLI > flyte > flyte create > flyte create secret**, **Flyte CLI > flyte > flyte delete > flyte delete secret**, **Flyte CLI > flyte > flyte get > flyte get secret**  |
| `trigger` | **Flyte CLI > flyte > flyte create > flyte create trigger**, **Flyte CLI > flyte > flyte delete > flyte delete trigger**, **Flyte CLI > flyte > flyte get > flyte get trigger**, **Flyte CLI > flyte > flyte update > flyte update trigger**  |
| `user` | **Flyte CLI > flyte > flyte create > flyte create user**, **Flyte CLI > flyte > flyte delete > flyte delete user**, **Flyte CLI > flyte > flyte get > flyte get user**  |
| `app` | **Flyte CLI > flyte > flyte delete > flyte delete app**, **Flyte CLI > flyte > flyte get > flyte get app**, **Flyte CLI > flyte > flyte update > flyte update app**  |
| `demo` | **Flyte CLI > flyte > flyte delete > flyte delete demo**, **Flyte CLI > flyte > flyte start > flyte start demo**  |
| `docs` | **Flyte CLI > flyte > flyte gen > flyte gen docs**  |
| `cluster` | **Flyte CLI > flyte > flyte get > flyte get cluster**  |
| `io` | **Flyte CLI > flyte > flyte get > flyte get io**  |
| `logs` | **Flyte CLI > flyte > flyte get > flyte get logs**  |
| `member` | **Flyte CLI > flyte > flyte get > flyte get member**  |
| `task` | **Flyte CLI > flyte > flyte get > flyte get task**  |
| `hf-model` | **Flyte CLI > flyte > flyte prefetch > flyte prefetch hf-model**  |
| `deployed-task` | **Flyte CLI > flyte > flyte run > flyte run deployed-task**  |
| `tui` | **Flyte CLI > flyte > flyte start > flyte start tui**  |

| Action | On |
| ------ | -- |
| `abort` | **Flyte CLI > flyte > flyte abort > flyte abort action**, **Flyte CLI > flyte > flyte abort > flyte abort run**  |
| **Flyte CLI > flyte > flyte build** | - |
| `create` | **Flyte CLI > flyte > flyte create > flyte create api-key**, **Flyte CLI > flyte > flyte create > flyte create assignment**, **Flyte CLI > flyte > flyte create > flyte create config**, **Flyte CLI > flyte > flyte create > flyte create policy**, **Flyte CLI > flyte > flyte create > flyte create project**, **Flyte CLI > flyte > flyte create > flyte create role**, **Flyte CLI > flyte > flyte create > flyte create secret**, **Flyte CLI > flyte > flyte create > flyte create trigger**, **Flyte CLI > flyte > flyte create > flyte create user**  |
| `delete` | **Flyte CLI > flyte > flyte delete > flyte delete api-key**, **Flyte CLI > flyte > flyte delete > flyte delete app**, **Flyte CLI > flyte > flyte delete > flyte delete assignment**, **Flyte CLI > flyte > flyte delete > flyte delete demo**, **Flyte CLI > flyte > flyte delete > flyte delete policy**, **Flyte CLI > flyte > flyte delete > flyte delete role**, **Flyte CLI > flyte > flyte delete > flyte delete secret**, **Flyte CLI > flyte > flyte delete > flyte delete trigger**, **Flyte CLI > flyte > flyte delete > flyte delete user**  |
| **Flyte CLI > flyte > flyte deploy** | - |
| `gen` | **Flyte CLI > flyte > flyte gen > flyte gen docs**  |
| `get` | **Flyte CLI > flyte > flyte get > flyte get action**, **Flyte CLI > flyte > flyte get > flyte get api-key**, **Flyte CLI > flyte > flyte get > flyte get app**, **Flyte CLI > flyte > flyte get > flyte get assignment**, **Flyte CLI > flyte > flyte get > flyte get cluster**, **Flyte CLI > flyte > flyte get > flyte get config**, **Flyte CLI > flyte > flyte get > flyte get io**, **Flyte CLI > flyte > flyte get > flyte get logs**, **Flyte CLI > flyte > flyte get > flyte get member**, **Flyte CLI > flyte > flyte get > flyte get policy**, **Flyte CLI > flyte > flyte get > flyte get project**, **Flyte CLI > flyte > flyte get > flyte get role**, **Flyte CLI > flyte > flyte get > flyte get run**, **Flyte CLI > flyte > flyte get > flyte get secret**, **Flyte CLI > flyte > flyte get > flyte get task**, **Flyte CLI > flyte > flyte get > flyte get trigger**, **Flyte CLI > flyte > flyte get > flyte get user**  |
| `prefetch` | **Flyte CLI > flyte > flyte prefetch > flyte prefetch hf-model**  |
| `run` | **Flyte CLI > flyte > flyte run > flyte run deployed-task**  |
| **Flyte CLI > flyte > flyte serve** | - |
| `start` | **Flyte CLI > flyte > flyte start > flyte start demo**, **Flyte CLI > flyte > flyte start > flyte start tui**  |
| `update` | **Flyte CLI > flyte > flyte update > flyte update app**, **Flyte CLI > flyte > flyte update > flyte update policy**, **Flyte CLI > flyte > flyte update > flyte update project**, **Flyte CLI > flyte > flyte update > flyte update role**, **Flyte CLI > flyte > flyte update > flyte update trigger**  |
| **Flyte CLI > flyte > flyte whoami** | - |

## Union-specific functionality {#plugin-commands}

> [!NOTE]
> Commands marked with **⁺** are provided by the `flyteplugins-union` plugin,
> which adds Union-specific functionality to the Flyte CLI
> (user management, RBAC, API keys).
> Install it with `pip install flyteplugins-union`.
>
> See the [flyteplugins.union API reference](../integrations/union/_index)
> for the programmatic interface.

## flyte

**`flyte [OPTIONS] COMMAND [ARGS]...`**

The Flyte CLI is the command line interface for working with the Flyte SDK and backend.

It follows a simple verb/noun structure,
where the top-level commands are verbs that describe the action to be taken,
and the subcommands are nouns that describe the object of the action.

The root command can be used to configure the CLI for persistent settings,
such as the endpoint, organization, and verbosity level.

Set endpoint and organization:

```bash
$ flyte --endpoint <endpoint> --org <org> get project <project_name>
```

Increase verbosity level (This is useful for debugging,
this will show more logs and exception traces):

```bash
$ flyte -vvv get logs <run-name>
```

Override the default config file:

```bash
$ flyte --config /path/to/config.yaml run ...
```

* [Documentation](https://www.union.ai/docs/flyte/user-guide/)
* [GitHub](https://github.com/flyteorg/flyte): Please leave a star if you like Flyte!
* [Slack](https://slack.flyte.org): Join the community and ask questions.
* [Issues](https://github.com/flyteorg/flyte/issues)

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--version` | `boolean` | `False` | Show the version and exit. |
| `--endpoint` | `text` | `Sentinel.UNSET` | The endpoint to connect to. This will override any configuration file and simply use `pkce` to connect. |
| `--insecure` | `boolean` |  | Use an insecure connection to the endpoint. If not specified, the CLI will use TLS. |
| `--auth-type` | `choice` |  | Authentication type to use for the Flyte backend. Defaults to 'pkce'. |
| `-v`
`--verbose` | `integer` | `0` | Show verbose messages and exception traces. Repeating multiple times increases the verbosity (e.g., -vvv). |
| `--org` | `text` | `Sentinel.UNSET` | The organization to which the command applies. |
| `-c`
`--config` | `file` | `Sentinel.UNSET` | Path to the configuration file to use. If not specified, the default configuration file is used. |
| `--output-format`
`-of` | `choice` | `table` | Output format for commands that support it. Defaults to 'table'. |
| `--log-format` | `choice` | `console` | Formatting for logs, defaults to 'console' which is meant to be human readable. 'json' is meant for machine parsing. |
| `--reset-root-logger` | `boolean` | `False` | If set, the root logger will be reset to use Flyte logging style |
| `--help` | `boolean` | `False` | Show this message and exit. |

### flyte abort

**`flyte abort COMMAND [ARGS]...`**

Abort an ongoing process.

#### flyte abort action

**`flyte abort action [OPTIONS] RUN_NAME ACTION_NAME`**

Abort an action associated with a run.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--reason` | `text` | `Manually aborted from the CLI` | The reason to abort the run. |
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte abort run

**`flyte abort run [OPTIONS] RUN_NAME`**

Abort a run.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--reason` | `text` | `Manually aborted from the CLI` | The reason to abort the run. |
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

### flyte build

**`flyte build [OPTIONS] COMMAND [ARGS]...`**

Build the environments defined in a python file or directory. This will build the images associated with the
environments.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--noop` | `boolean` | `Sentinel.UNSET` | Dummy parameter, placeholder for future use. Does not affect the build process. |
| `--help` | `boolean` | `False` | Show this message and exit. |

### flyte create

**`flyte create COMMAND [ARGS]...`**

Create resources in a Flyte deployment.

#### flyte create api-key

> **Note:** This command is provided by the **Flyte CLI > `flyteplugins.union`** plugin.

**`flyte create api-key [OPTIONS]`**

Create an API key for headless authentication.

This creates OAuth application credentials that can be used to authenticate
with Union without interactive login. The generated API key should be set
as the FLYTE_API_KEY environment variable. Oauth applications should not be
confused with Union Apps, which are a different construct entirely.

Examples:

    # Create an API key named "ci-pipeline"
    $ flyte create api-key --name ci-pipeline

    # The output will include an export command like:
    # export FLYTE_API_KEY="<base64-encoded-credentials>"

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--name` | `text` | `Sentinel.UNSET` | Name for API key |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte create assignment

> **Note:** This command is provided by the **Flyte CLI > `flyteplugins.union`** plugin.

**`flyte create assignment [OPTIONS]`**

Assign a policy to an identity.

    Exactly one of --user-subject, --creds-subject, or --email must be provided.

    Examples:

        $ flyte --org my-org create assignment --user-subject user-123 --policy admin
        $ flyte --org my-org create assignment --creds-subject app-456 --policy admin
        $ flyte --org my-org create assignment --email jane@example.com --policy admin

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--user-subject` | `text` |  | User subject identifier |
| `--creds-subject` | `text` |  | Client credentials application subject |
| `--email` | `text` |  | User email for lookup |
| `--policy` | `text` | `Sentinel.UNSET` | Policy name to assign |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte create config

**`flyte create config [OPTIONS]`**

Creates a configuration file for Flyte CLI.
If the `--output` option is not specified, it will create a file named `config.yaml` in the current directory.
If the file already exists, it will raise an error unless the `--force` option is used.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--endpoint` | `text` | `Sentinel.UNSET` | Endpoint of the Flyte backend. |
| `--insecure` | `boolean` | `False` | Use an insecure connection to the Flyte backend. |
| `--org` | `text` | `Sentinel.UNSET` | Organization to use. This will override the organization in the configuration file. |
| `-o`
`--output` | `path` | `.flyte/config.yaml` | Path to the output directory where the configuration will be saved. Defaults to current directory. |
| `--force` | `boolean` | `False` | Force overwrite of the configuration file if it already exists. |
| `--image-builder`
`--builder` | `choice` | `local` | Image builder to use for building images. Defaults to 'local'. |
| `--auth-type` | `choice` |  | Authentication type to use for the Flyte backend. Defaults to 'pkce'. |
| `--local-persistence` | `boolean` | `False` | Enable SQLite persistence for local run metadata, allowing past runs to be browsed via 'flyte start tui'. |
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte create policy

> **Note:** This command is provided by the **Flyte CLI > `flyteplugins.union`** plugin.

**`flyte create policy [OPTIONS] NAME`**

Create a policy.

    Requires --file or --edit to specify bindings for the policy.

    Examples:

        $ flyte --org my-org create policy my-policy --edit
        $ flyte --org my-org create policy my-policy --file policy.yaml

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--file` | `path` |  | Create policy from a YAML file |
| `--edit` | `boolean` | `False` | Open an editor to configure the policy before creating |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte create project

**`flyte create project [OPTIONS]`**

Create a new project.


Example usage:

```bash
flyte create project --id my_project_id --name "My Project"
flyte create project --id my_project_id --name "My Project" --description "My project" -l team=ml -l env=prod
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--id` | `text` | `Sentinel.UNSET` | Unique identifier for the project (immutable). |
| `--name` | `text` | `Sentinel.UNSET` | Display name for the project. |
| `--description` | `text` | `` | Description for the project. |
| `--label`
`-l` | `text` | `Sentinel.UNSET` | Labels as key=value pairs. Can be specified multiple times. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte create role

> **Note:** This command is provided by the [`flyteplugins.union`](#plugin-commands) plugin.

**`flyte create role [OPTIONS] NAME`**

Create a role.

    Requires --file or --edit to specify actions for the role.

    Examples:

        $ flyte --org my-org create role my-role --edit
        $ flyte --org my-org create role my-role --file role.yaml

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--file` | `path` |  | Create role from a YAML file |
| `--edit` | `boolean` | `False` | Open an editor to configure the role before creating |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte create secret

**`flyte create secret [OPTIONS] NAME`**

Create a new secret. The name of the secret is required. For example:

CODE4

If you don't provide a `--value` flag, you will be prompted to enter the
secret value in the terminal.

CODE5

If `--from-file` is specified, the value will be read from the file instead of being provided directly:

CODE6

The `--type` option can be used to create specific types of secrets.
Either `regular` or `image_pull` can be specified.
Secrets intended to access container images should be specified as `image_pull`.
Other secrets should be specified as `regular`.
If no type is specified, `regular` is assumed.

For image pull secrets, you have several options:

1. Interactive mode (prompts for registry, username, password):
CODE7

2. With explicit credentials:
CODE8

3. Lastly, you can create a secret from your existing Docker installation (i.e., you've run `docker login` in
the past) and you just want to pull from those credentials. Since you may have logged in to multiple registries,
you can specify which registries to include. If no registries are specified, all registries are added.
CODE9

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--value` | `text` | `Sentinel.UNSET` | Secret value Mutually exclusive with from_file, from_docker_config, registry. |
| `--from-file` | `path` | `Sentinel.UNSET` | Path to the file with the binary secret. Mutually exclusive with value, from_docker_config, registry. |
| `--type` | `choice` | `regular` | Type of the secret. |
| `--from-docker-config` | `boolean` | `False` | Create image pull secret from Docker config file (only for --type image_pull). Mutually exclusive with value, from_file, registry, username, password. |
| `--docker-config-path` | `path` | `Sentinel.UNSET` | Path to Docker config file (defaults to ~/.docker/config.json or $DOCKER_CONFIG). Requires from_docker_config. |
| `--registries` | `text` | `Sentinel.UNSET` | Comma-separated list of registries to include (only with --from-docker-config). |
| `--registry` | `text` | `Sentinel.UNSET` | Registry hostname (e.g., ghcr.io, docker.io) for explicit credentials (only for --type image_pull). Mutually exclusive with value, from_file, from_docker_config. |
| `--username` | `text` | `Sentinel.UNSET` | Username for the registry (only with --registry). |
| `--password` | `text` | `Sentinel.UNSET` | Password for the registry (only with --registry). If not provided, will prompt. |
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte create trigger

**`flyte create trigger [OPTIONS] TASK_NAME NAME`**

Create a new trigger for a task. The task name and trigger name are required.

Example:

CODE10

This will create a trigger that runs every day at midnight.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--schedule` | `text` | `Sentinel.UNSET` | Cron schedule for the trigger. Defaults to every minute. |
| `--description` | `text` | `` | Description of the trigger. |
| `--auto-activate` | `boolean` | `True` | Whether the trigger should not be automatically activated. Defaults to True. |
| `--trigger-time-var` | `text` | `trigger_time` | Variable name for the trigger time in the task inputs. Defaults to 'trigger_time'. |
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte create user

> **Note:** This command is provided by the [`flyteplugins.union`](#plugin-commands) plugin.

**`flyte create user [OPTIONS]`**

Create (invite) a new user.

    Examples:

        $ flyte --org my-org create user --first-name Jane --last-name Doe --email jane@example.com
        $ flyte --org my-org create user --first-name Jane --last-name Doe --email jane@example.com --policy admin

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--first-name` | `text` | `Sentinel.UNSET` | First name of the user |
| `--last-name` | `text` | `Sentinel.UNSET` | Last name of the user |
| `--email` | `text` | `Sentinel.UNSET` | Email address of the user |
| `--policy` | `text` |  | Policy to assign to the user after creation |
| `--help` | `boolean` | `False` | Show this message and exit. |

### flyte delete

**`flyte delete COMMAND [ARGS]...`**

Remove resources from a Flyte deployment.

#### flyte delete api-key

> **Note:** This command is provided by the [`flyteplugins.union`](#plugin-commands) plugin.

**`flyte delete api-key [OPTIONS] CLIENT_ID`**

Delete an API key.

Examples:

    # Delete an API key (with confirmation)
    $ flyte delete api-key my-client-id

    # Delete without confirmation
    $ flyte delete api-key my-client-id --yes

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--yes` | `boolean` | `False` | Skip confirmation prompt |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte delete app

**`flyte delete app [OPTIONS] NAME`**

Delete apps from a Flyte deployment.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte delete assignment

> **Note:** This command is provided by the [`flyteplugins.union`](#plugin-commands) plugin.

**`flyte delete assignment [OPTIONS]`**

Unassign a policy from an identity.

    One of --user-subject or --creds-subject must be provided.

    Examples:

        $ flyte --org my-org delete assignment --user-subject user-123 --policy admin
        $ flyte --org my-org delete assignment --creds-subject app-456 --policy admin

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--user-subject` | `text` |  | User subject identifier |
| `--creds-subject` | `text` |  | Client credentials application subject |
| `--policy` | `text` | `Sentinel.UNSET` | Policy name to unassign |
| `--yes` | `boolean` | `False` | Skip confirmation prompt |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte delete demo

**`flyte delete demo`**

Stop and remove the local Flyte demo cluster container.

#### flyte delete policy

> **Note:** This command is provided by the [`flyteplugins.union`](#plugin-commands) plugin.

**`flyte delete policy [OPTIONS] NAME`**

Delete a policy.

    Examples:

        $ flyte --org my-org delete policy my-policy
        $ flyte --org my-org delete policy my-policy --yes

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--yes` | `boolean` | `False` | Skip confirmation prompt |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte delete role

> **Note:** This command is provided by the [`flyteplugins.union`](#plugin-commands) plugin.

**`flyte delete role [OPTIONS] NAME`**

Delete a role.

    Examples:

        $ flyte --org my-org delete role my-role
        $ flyte --org my-org delete role my-role --yes

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--yes` | `boolean` | `False` | Skip confirmation prompt |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte delete secret

**`flyte delete secret [OPTIONS] NAME`**

Delete a secret. The name of the secret is required.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte delete trigger

**`flyte delete trigger [OPTIONS] NAME TASK_NAME`**

Delete a trigger. The name of the trigger is required.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte delete user

> **Note:** This command is provided by the [`flyteplugins.union`](#plugin-commands) plugin.

**`flyte delete user [OPTIONS] SUBJECT`**

Delete a user.

    Examples:

        $ flyte --org my-org delete user user-subject-id
        $ flyte --org my-org delete user user-subject-id --yes

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--yes` | `boolean` | `False` | Skip confirmation prompt |
| `--help` | `boolean` | `False` | Show this message and exit. |

### flyte deploy

**`flyte deploy [OPTIONS] COMMAND [ARGS]...`**

Deploy one or more environments from a python file.

This command will create or update environments in the Flyte system, registering
all tasks and their dependencies.

Example usage:

CODE11

Arguments to the deploy command are provided right after the `deploy` command and before the file name.

To deploy all environments in a file, use the `--all` flag:

CODE12

To recursively deploy all environments in a directory and its subdirectories, use the `--recursive` flag:

CODE13

You can combine `--all` and `--recursive` to deploy everything:

CODE14

You can provide image mappings with `--image` flag. This allows you to specify
the image URI for the task environment during CLI execution without changing
the code. Any images defined with `Image.from_ref_name("name")` will resolve to the
corresponding URIs you specify here.

CODE15

If the image name is not provided, it is regarded as a default image and will
be used when no image is specified in TaskEnvironment:

CODE16

You can specify multiple image arguments:

CODE17

To deploy a specific version, use the `--version` flag:

CODE18

To preview what would be deployed without actually deploying, use the `--dry-run` flag:

CODE19

You can specify the `--config` flag to point to a specific Flyte cluster:

CODE20

You can override the default configured project and domain:

CODE21

If loading some files fails during recursive deployment, you can use the `--ignore-load-errors` flag
to continue deploying the environments that loaded successfully:

CODE22

Other arguments to the deploy command are listed below.

To see the environments available in a file, use `--help` after the file name:

CODE23

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--version` | `text` | `Sentinel.UNSET` | Version of the environment to deploy |
| `--dry-run`
`--dryrun` | `boolean` | `False` | Dry run. Do not actually call the backend service. |
| `--copy-style` | `choice` | `loaded_modules` | Copy style to use when running the task |
| `--root-dir` | `text` | `Sentinel.UNSET` | Override the root source directory, helpful when working with monorepos. |
| `--recursive`
`-r` | `boolean` | `False` | Recursively deploy all environments in the current directory |
| `--all` | `boolean` | `False` | Deploy all environments in the current directory, ignoring the file name |
| `--ignore-load-errors`
`-i` | `boolean` | `False` | Ignore errors when loading environments especially when using --recursive or --all. |
| `--no-sync-local-sys-paths` | `boolean` | `False` | Disable synchronization of local sys.path entries under the root directory to the remote container. |
| `--image` | `text` | `Sentinel.UNSET` | Image to be used in the run. Format: imagename=imageuri. Can be specified multiple times. |
| `--help` | `boolean` | `False` | Show this message and exit. |

### flyte gen

**`flyte gen COMMAND [ARGS]...`**

Generate documentation.

#### flyte gen docs

**`flyte gen docs [OPTIONS]`**

Generate documentation.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--type` | `text` | `Sentinel.UNSET` | Type of documentation (valid: markdown) |
| `--plugin-variants` | `text` |  | Hugo variant names for plugin commands (e.g., 'union'). When set, plugin command sections and index entries are wrapped in {{&lt; variant >}} shortcodes. Core commands appear unconditionally. |
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

### flyte get

**`flyte get COMMAND [ARGS]...`**

Retrieve resources from a Flyte deployment.

You can get information about projects, runs, tasks, actions, secrets, logs and input/output values.

Each command supports optional parameters to filter or specify the resource you want to retrieve.

Using a `get` subcommand without any arguments will retrieve a list of available resources to get.
For example:

* `get project` (without specifying a project), will list all projects.
* `get project my_project` will return the details of the project named `my_project`.

In some cases, a partially specified command will act as a filter and return available further parameters.
For example:

* `get action my_run` will return all actions for the run named `my_run`.
* `get action my_run my_action` will return the details of the action named `my_action` for the run `my_run`.

#### flyte get action

**`flyte get action [OPTIONS] RUN_NAME [ACTION_NAME]`**

Get all actions for a run or details for a specific action.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--in-phase` | `choice` | `Sentinel.UNSET` | Filter actions by their phase. |
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte get api-key

> **Note:** This command is provided by the [`flyteplugins.union`](#plugin-commands) plugin.

**`flyte get api-key [OPTIONS] [CLIENT_ID]`**

Get or list API keys.

If CLIENT-ID is provided, gets a specific API key.
Otherwise, lists all API keys.

Examples:

    # List all API keys
    $ flyte get api-key

    # List with a limit
    $ flyte get api-key --limit 10

    # Get a specific API key
    $ flyte get api-key my-client-id

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--limit` | `integer` | `100` | Maximum number of keys to list |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte get app

**`flyte get app [OPTIONS] [NAME]`**

Get a list of all apps, or details of a specific app by name.

Apps are long-running services deployed on the Flyte platform.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--limit` | `integer` | `100` | Limit the number of apps to fetch when listing. |
| `--only-mine` | `boolean` | `False` | Show only apps created by the current user (you). |
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte get assignment

> **Note:** This command is provided by the [`flyteplugins.union`](#plugin-commands) plugin.

**`flyte get assignment [OPTIONS]`**

Get or list assignments.

    Without --user-subject or --creds-subject, lists all assignments.

    Examples:

        $ flyte --org my-org get assignment
        $ flyte --org my-org get assignment --user-subject user-123
        $ flyte --org my-org get assignment --creds-subject app-456

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--user-subject` | `text` |  | User subject identifier |
| `--creds-subject` | `text` |  | Client credentials application subject |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte get cluster

> **Note:** This command is provided by the [`flyteplugins.union`](#plugin-commands) plugin.

**`flyte get cluster [OPTIONS] [NAME]`**

Get a cluster or list all clusters.

    If NAME is provided, fetch that specific cluster. Otherwise list all clusters.

    Examples:

        $ flyte --org my-org get cluster

        $ flyte --org my-org get cluster my-cluster

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--limit` | `integer` | `100` | Maximum number of clusters to return. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte get config

**`flyte get config`**

Shows the automatically detected configuration to connect with the remote backend.

The configuration will include the endpoint, organization, and other settings that are used by the CLI.

#### flyte get io

**`flyte get io [OPTIONS] RUN_NAME [ACTION_NAME]`**

Get the inputs and outputs of a run or action.
If only the run name is provided, it will show the inputs and outputs of the root action of that run.
If an action name is provided, it will show the inputs and outputs for that action.
If `--inputs-only` or `--outputs-only` is specified, it will only show the inputs or outputs respectively.

Examples:

CODE24

CODE25

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--inputs-only`
`-i` | `boolean` | `False` | Show only inputs |
| `--outputs-only`
`-o` | `boolean` | `False` | Show only outputs |
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte get logs

**`flyte get logs [OPTIONS] RUN_NAME [ACTION_NAME]`**

Stream logs for the provided run or action.
If only the run is provided, only the logs for the parent action will be streamed:

CODE26

If you want to see the logs for a specific action, you can provide the action name as well:

CODE27

By default, logs will be shown in the raw format and will scroll the terminal.
If automatic scrolling and only tailing `--lines` number of lines is desired, use the `--pretty` flag:

CODE28

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--lines`
`-l` | `integer` | `30` | Number of lines to show, only useful for --pretty |
| `--show-ts` | `boolean` | `False` | Show timestamps |
| `--pretty` | `boolean` | `False` | Show logs in an auto-scrolling box, where number of lines is limited to `--lines` |
| `--attempt`
`-a` | `integer` |  | Attempt number to show logs for, defaults to the latest attempt. |
| `--filter-system` | `boolean` | `False` | Filter all system logs from the output. |
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte get member

> **Note:** This command is provided by the [`flyteplugins.union`](#plugin-commands) plugin.

**`flyte get member`**

List all members (users and applications) in an organization.

    Examples:

        $ flyte --org my-org get member

#### flyte get policy

> **Note:** This command is provided by the [`flyteplugins.union`](#plugin-commands) plugin.

**`flyte get policy [OPTIONS] [NAME]`**

Get or list policies.

    If NAME is provided, gets a specific policy. Otherwise, lists all policies.

    Examples:

        $ flyte --org my-org get policy
        $ flyte --org my-org get policy --limit 10
        $ flyte --org my-org get policy my-policy

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--limit` | `integer` | `100` | Maximum number of policies to list |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte get project

**`flyte get project [OPTIONS] [NAME]`**

Get a list of all projects, or details of a specific project by name.

By default, only active (unarchived) projects are shown. Use `--archived` to
show archived projects instead.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--archived` | `boolean` | `False` | Show archived projects instead of active ones. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte get role

> **Note:** This command is provided by the [`flyteplugins.union`](#plugin-commands) plugin.

**`flyte get role [OPTIONS] [NAME]`**

Get or list roles.

    If NAME is provided, gets a specific role. Otherwise, lists all roles.

    Examples:

        $ flyte --org my-org get role
        $ flyte --org my-org get role --limit 10
        $ flyte --org my-org get role my-role

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--limit` | `integer` | `100` | Maximum number of roles to list |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte get run

**`flyte get run [OPTIONS] [NAME]`**

Get a list of all runs, or details of a specific run by name.

The run details will include information about the run, its status, but only the root action will be shown.

If you want to see the actions for a run, use `get action <run_name>`.

You can filter runs by task name and optionally task version:

CODE29

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--limit` | `integer` | `100` | Limit the number of runs to fetch when listing. |
| `--in-phase` | `choice` | `Sentinel.UNSET` | Filter runs by their status. |
| `--only-mine` | `boolean` | `False` | Show only runs created by the current user (you). |
| `--task-name` | `text` |  | Filter runs by task name. |
| `--task-version` | `text` |  | Filter runs by task version. |
| `--created-after` | `datetime` |  | Show runs created at or after this datetime (UTC). Accepts ISO dates, 'now', 'today', or 'now - 1 day'. |
| `--created-before` | `datetime` |  | Show runs created before this datetime (UTC). |
| `--updated-after` | `datetime` |  | Show runs updated at or after this datetime (UTC). Accepts ISO dates, 'now', 'today', or 'now - 1 day'. |
| `--updated-before` | `datetime` |  | Show runs updated before this datetime (UTC). |
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte get secret

**`flyte get secret [OPTIONS] [NAME]`**

Get a list of all secrets, or details of a specific secret by name.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte get task

**`flyte get task [OPTIONS] [NAME] [VERSION]`**

Retrieve a list of all tasks, or details of a specific task by name and version.

Currently, both `name` and `version` are required to get a specific task.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--limit` | `integer` | `100` | Limit the number of tasks to fetch. |
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte get trigger

**`flyte get trigger [OPTIONS] [TASK_NAME] [NAME]`**

Get a list of all triggers, or details of a specific trigger by name.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--limit` | `integer` | `100` | Limit the number of triggers to fetch. |
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte get user

> **Note:** This command is provided by the [`flyteplugins.union`](#plugin-commands) plugin.

**`flyte get user [OPTIONS] [SUBJECT]`**

Get or list users.

    If SUBJECT is provided, gets a specific user. Otherwise, lists all users.

    Examples:

        $ flyte --org my-org get user
        $ flyte --org my-org get user --limit 10
        $ flyte --org my-org get user user-subject-id
        $ flyte --org my-org get user --email jane@example.com

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--limit` | `integer` | `100` | Maximum number of users to list |
| `--email` | `text` |  | Filter by email address |
| `--help` | `boolean` | `False` | Show this message and exit. |

### flyte prefetch

**`flyte prefetch COMMAND [ARGS]...`**

Prefetch artifacts from remote registries.

These commands help you download and prefetch artifacts like HuggingFace models
to your Flyte storage for faster access during task execution.

#### flyte prefetch hf-model

**`flyte prefetch hf-model [OPTIONS] REPO`**

Prefetch a HuggingFace model to Flyte storage.

Downloads a model from the HuggingFace Hub and prefetches it to your configured
Flyte storage backend. This is useful for:

- Pre-fetching large models before running inference tasks
- Sharding models for tensor-parallel inference
- Avoiding repeated downloads during development

**Basic Usage:**

CODE30

**With Sharding:**

Create a shard config file (shard_config.yaml):

CODE31

Then run:

CODE32

**Wait for Completion:**

CODE33

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--raw-data-path` | `text` |  | Object store path to store the model. If not provided, the model will be stored using the default path generated by Flyte storage layer. |
| `--artifact-name` | `text` |  | Artifact name to use for the stored model. Must only contain alphanumeric characters, underscores, and hyphens. If not provided, the repo name will be used (replacing '.' with '-'). |
| `--architecture` | `text` | `Sentinel.UNSET` | Model architecture, as given in HuggingFace config.json. |
| `--task` | `text` | `auto` | Model task, e.g., 'generate', 'classify', 'embed', 'score', etc. Refer to vLLM docs. 'auto' will try to discover this automatically. |
| `--modality` | `text` | `('text',)` | Modalities supported by the model, e.g., 'text', 'image', 'audio', 'video'. Can be specified multiple times. |
| `--format` | `text` | `Sentinel.UNSET` | Model serialization format, e.g., safetensors, onnx, torchscript, joblib, etc. |
| `--model-type` | `text` | `Sentinel.UNSET` | Model type, e.g., 'transformer', 'xgboost', 'custom', etc. For HuggingFace models, this is auto-determined from config.json['model_type']. |
| `--short-description` | `text` | `Sentinel.UNSET` | Short description of the model. |
| `--force` | `integer` | `0` | Force store of the model. Increment value (--force=1, --force=2, ...) to force a new store. |
| `--wait` | `boolean` | `False` | Wait for the model to be stored before returning. |
| `--hf-token-key` | `text` | `HF_TOKEN` | Name of the Flyte secret containing your HuggingFace token. Note: This is not the HuggingFace token itself, but the name of the secret in the Flyte secret store. |
| `--cpu` | `text` | `2` | CPU request for the prefetch task (e.g., '2', '4', '2,4' for 2-4 CPUs). |
| `--mem` | `text` | `8Gi` | Memory request for the prefetch task (e.g., '16Gi', '64Gi', '16Gi,64Gi' for 16-64GB). |
| `--gpu` | `choice` |  | The gpu to use for downloading and (optionally) sharding the model. Format: '{type}:{quantity}' (e.g., 'A100:8', 'L4:1'). |
| `--disk` | `text` | `50Gi` | Disk storage request for the prefetch task (e.g., '100Gi', '500Gi'). |
| `--shm` | `text` |  | Shared memory request for the prefetch task (e.g., '100Gi', 'auto'). |
| `--shard-config` | `path` | `Sentinel.UNSET` | Path to a YAML file containing sharding configuration. The file should have 'engine' (currently only 'vllm') and 'args' keys. |
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

### flyte run

**`flyte run [OPTIONS] COMMAND [ARGS]...`**

Run a task from a python file or deployed task.

Example usage:

CODE34

Arguments to the run command are provided right after the `run` command and before the file name.
Arguments for the task itself are provided after the task name.

To run a task locally, use the `--local` flag. This will run the task in the local environment instead of the remote
Flyte environment:

CODE35

You can provide image mappings with `--image` flag. This allows you to specify
the image URI for the task environment during CLI execution without changing
the code. Any images defined with `Image.from_ref_name("name")` will resolve to the
corresponding URIs you specify here.

CODE36

If the image name is not provided, it is regarded as a default image and will
be used when no image is specified in TaskEnvironment:

CODE37

You can specify multiple image arguments:

CODE38

To run tasks that you've already deployed to Flyte, use the deployed-task command:

CODE39

To run a specific version of a deployed task, use the `env.task:version` syntax:

CODE40

You can specify the `--config` flag to point to a specific Flyte cluster:

CODE41

You can override the default configured project and domain:

CODE42

You can discover what deployed tasks are available by running:

CODE43

To run an arbitrary Python script on a remote cluster (without defining a task), use `python-script`:

CODE44

You can also install extra packages and wait for completion:

CODE45

Other arguments to the run command are listed below.

Arguments for the task itself are provided after the task name and can be retrieved using `--help`. For example:

CODE46

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--local` | `boolean` | `False` | Run the task locally |
| `--copy-style` | `choice` | `loaded_modules` | Copy style to use when running the task |
| `--root-dir` | `text` | `Sentinel.UNSET` | Override the root source directory, helpful when working with monorepos. |
| `--raw-data-path` | `text` | `Sentinel.UNSET` | Override the output prefix used to store offloaded data types. e.g. s3://bucket/ |
| `--service-account` | `text` | `Sentinel.UNSET` | Kubernetes service account. If not provided, the configured default will be used |
| `--name` | `text` | `Sentinel.UNSET` | Name of the run. If not provided, a random name will be generated. |
| `--follow`
`-f` | `boolean` | `False` | Wait and watch logs for the parent action. If not provided, the CLI will exit after successfully launching a remote execution with a link to the UI. |
| `--tui` | `boolean` | `False` | Show interactive TUI for local execution (requires flyte[tui]). |
| `--image` | `text` | `Sentinel.UNSET` | Image to be used in the run. Format: imagename=imageuri. Can be specified multiple times. |
| `--no-sync-local-sys-paths` | `boolean` | `False` | Disable synchronization of local sys.path entries under the root directory to the remote container. |
| `--run-project` | `text` |  | Run the remote task in this project, only applicable when using `deployed-task` subcommand. |
| `--run-domain` | `text` |  | Run the remote task in this domain, only applicable when using `deployed-task` subcommand. |
| `--debug` | `boolean` | `False` | Run the task as a VSCode debug task. Starts a code-server in the container so you can connect via the UI to interactively debug/run the task. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte run deployed-task

**`flyte run deployed-task [OPTIONS] COMMAND [ARGS]...`**

Run remote task from the Flyte backend

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

### flyte serve

**`flyte serve [OPTIONS] COMMAND [ARGS]...`**

Serve an app from a Python file using flyte.serve().

This command allows you to serve apps defined with `flyte.app.AppEnvironment`
in your Python files. The serve command will deploy the app to the Flyte backend
and start it, making it accessible via a URL.

Example usage:

CODE47

**Local serving:** Use the `--local` flag to serve the app on localhost without
deploying to the Flyte backend. This is useful for local development and testing:

CODE48

Arguments to the serve command are provided right after the `serve` command and before the file name.

To follow the logs of the served app, use the `--follow` flag:

CODE49

Note: Log streaming is not yet fully implemented and will be added in a future release.

You can provide image mappings with `--image` flag. This allows you to specify
the image URI for the app environment during CLI execution without changing
the code. Any images defined with `Image.from_ref_name("name")` will resolve to the
corresponding URIs you specify here.

CODE50

If the image name is not provided, it is regarded as a default image and will
be used when no image is specified in AppEnvironment:

CODE51

You can specify multiple image arguments:

CODE52

You can specify the `--config` flag to point to a specific Flyte cluster:

CODE53

You can override the default configured project and domain:

CODE54

Other arguments to the serve command are listed below.

Note: This pattern is primarily useful for serving apps defined in tasks.
Serving deployed apps is not currently supported through this CLI command.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--copy-style` | `choice` | `loaded_modules` | Copy style to use when serving the app |
| `--root-dir` | `text` | `Sentinel.UNSET` | Override the root source directory, helpful when working with monorepos. |
| `--service-account` | `text` | `Sentinel.UNSET` | Kubernetes service account. If not provided, the configured default will be used |
| `--name` | `text` | `Sentinel.UNSET` | Name of the app deployment. If not provided, the app environment name will be used. |
| `--follow`
`-f` | `boolean` | `False` | Wait and watch logs for the app. If not provided, the CLI will exit after successfully deploying the app with a link to the UI. |
| `--image` | `text` | `Sentinel.UNSET` | Image to be used in the serve. Format: imagename=imageuri. Can be specified multiple times. |
| `--no-sync-local-sys-paths` | `boolean` | `False` | Disable synchronization of local sys.path entries under the root directory to the remote container. |
| `--env-var`
`-e` | `text` | `Sentinel.UNSET` | Environment variable to set in the app. Format: KEY=VALUE. Can be specified multiple times. Example: --env-var LOG_LEVEL=DEBUG --env-var DATABASE_URL=postgresql://... |
| `--local` | `boolean` | `False` | Serve the app locally on localhost instead of deploying to the Flyte backend. The app will be served on the port defined in the AppEnvironment. |
| `--help` | `boolean` | `False` | Show this message and exit. |

### flyte start

**`flyte start COMMAND [ARGS]...`**

Start various Flyte services.

#### flyte start demo

**`flyte start demo [OPTIONS]`**

Start a local Flyte demo cluster.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--image` | `text` | `ghcr.io/flyteorg/flyte-sandbox-v2:nightly` | Docker image to use for the demo cluster. |
| `--dev` | `boolean` | `False` | Enable dev mode inside the demo cluster (sets FLYTE_DEV=True). |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte start tui

**`flyte start tui`**

Launch TUI explore mode to browse past local runs. To use the TUI install `pip install flyte[tui]`
TUI, allows you to explore all your local runs if you have persistence enabled.

Persistence can be enabled in 2 ways,
1. By setting it in the config to record every local run
CODE55
2. By passing it in flyte.init(local_persistence=True)
This will record all `flyte.run` runs, that are local and are within the flyte.init being active.

### flyte update

**`flyte update COMMAND [ARGS]...`**

Update various flyte entities.

#### flyte update app

**`flyte update app [OPTIONS] NAME`**

Update an app by starting or stopping it.


Example usage:

CODE56

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--activate`
`--deactivate` | `boolean` |  | Activate or deactivate app. |
| `--wait` | `boolean` | `False` | Wait for the app to reach the desired state. |
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte update policy

> **Note:** This command is provided by the [`flyteplugins.union`](#plugin-commands) plugin.

**`flyte update policy NAME`**

Update a policy interactively.

    Opens the policy in your $EDITOR as YAML. Save and close to apply changes.
    Bindings that are added or removed will be applied to the policy.

    Examples:

        $ flyte --org my-org update policy my-policy

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte update project

**`flyte update project [OPTIONS] ID`**

Update a project's name, description, labels, or archive state.


Example usage:

CODE57

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--name` | `text` |  | Update the project display name. |
| `--description` | `text` |  | Update the project description. |
| `--label`
`-l` | `text` | `Sentinel.UNSET` | Set labels as key=value pairs. Can be specified multiple times. Replaces all existing labels. |
| `--archive`
`--unarchive` | `boolean` |  | Archive or unarchive the project. |
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte update role

> **Note:** This command is provided by the [`flyteplugins.union`](#plugin-commands) plugin.

**`flyte update role NAME`**

Update a role interactively.

    Opens the role in your $EDITOR as YAML. Save and close to apply changes.

    Examples:

        $ flyte --org my-org update role my-role

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--help` | `boolean` | `False` | Show this message and exit. |

#### flyte update trigger

**`flyte update trigger [OPTIONS] NAME TASK_NAME`**

Update a trigger.


Example usage:

CODE58

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--activate`
`--deactivate` | `boolean` | `Sentinel.UNSET` | Activate or deactivate the trigger. |
| `-p`
`--project` | `text` |  | Project to which this command applies. |
| `-d`
`--domain` | `text` |  | Domain to which this command applies. |
| `--help` | `boolean` | `False` | Show this message and exit. |

### flyte whoami

**`flyte whoami`**

Display the current user information.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk ===

# Flyte SDK

These are the docs for Flyte SDK version 2.0

Flyte is the core Python SDK for the Union and Flyte platforms.

## Subpages
- **Flyte SDK > Classes**
- **Flyte SDK > Packages**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/classes ===

# Classes

| Class | Description |
|-|-|
| **Flyte SDK > Packages > flyte > Cache** |Cache configuration for a task. |
| **Flyte SDK > Packages > flyte > Cron** |Cron-based automation schedule for use with `Trigger`. |
| **Flyte SDK > Packages > flyte > Device** |Represents a device type, its quantity and partition if applicable. |
| **Flyte SDK > Packages > flyte > Environment** | |
| **Flyte SDK > Packages > flyte > FixedRate** |Fixed-rate (interval-based) automation schedule for use with `Trigger`. |
| **Flyte SDK > Packages > flyte > Image** |Container image specification built using a fluent, two-step pattern:. |
| **Flyte SDK > Packages > flyte > ImageBuild** |Result of an image build operation. |
| **Flyte SDK > Packages > flyte > PodTemplate** |Custom PodTemplate specification for a Task. |
| **Flyte SDK > Packages > flyte > Resources** |Resources such as CPU, Memory, and GPU that can be allocated to a task. |
| **Flyte SDK > Packages > flyte > RetryStrategy** |Retry strategy for the task or task environment. |
| **Flyte SDK > Packages > flyte > ReusePolicy** |Configure a task environment for container reuse across multiple task invocations. |
| **Flyte SDK > Packages > flyte > Secret** |Secrets are used to inject sensitive information into tasks or image build context. |
| **Flyte SDK > Packages > flyte > TaskEnvironment** |Define an execution environment for a set of tasks. |
| **Flyte SDK > Packages > flyte > Timeout** |Timeout class to define a timeout for a task. |
| **Flyte SDK > Packages > flyte > Trigger** |Specification for a scheduled trigger that can be associated with any Flyte task. |
| **Flyte SDK > Packages > flyte.app > AppEndpoint** |Embed an upstream app's endpoint as an app parameter. |
| **Flyte SDK > Packages > flyte.app > AppEnvironment** |Configure a long-running app environment for APIs, dashboards, or model servers. |
| **Flyte SDK > Packages > flyte.app > ConnectorEnvironment** | |
| **Flyte SDK > Packages > flyte.app > Domain** |Subdomain to use for the domain. |
| **Flyte SDK > Packages > flyte.app > Link** |Custom links to add to the app. |
| **Flyte SDK > Packages > flyte.app > Parameter** |Parameter for application. |
| **Flyte SDK > Packages > flyte.app > Port** | |
| **Flyte SDK > Packages > flyte.app > RunOutput** |Use a run's output for app parameters. |
| **Flyte SDK > Packages > flyte.app > Scaling** |Controls replica count and autoscaling behavior for app environments. |
| **Flyte SDK > Packages > flyte.app > Timeouts** |Timeout configuration for the application. |
| **Flyte SDK > Packages > flyte.app.extras > FastAPIAppEnvironment** | |
| **Flyte SDK > Packages > flyte.app.extras > FastAPIPassthroughAuthMiddleware** |FastAPI middleware that automatically sets Flyte auth metadata from request headers. |
| **Flyte SDK > Packages > flyte.app.extras > FlyteWebhookAppEnvironment** |A pre-built FastAPI app environment for common Flyte webhook operations. |
| **Flyte SDK > Packages > flyte.config > Config** |This the parent configuration object and holds all the underlying configuration object types. |
| **Flyte SDK > Packages > flyte.connectors > AsyncConnector** |This is the base class for all async connectors, and it defines the interface that all connectors must implement. |
| **Flyte SDK > Packages > flyte.connectors > AsyncConnectorExecutorMixin** |This mixin class is used to run the connector task locally, and it's only used for local execution. |
| **Flyte SDK > Packages > flyte.connectors > ConnectorRegistry** |This is the registry for all connectors. |
| **Flyte SDK > Packages > flyte.connectors > ConnectorService** | |
| **Flyte SDK > Packages > flyte.connectors > Resource** |This is the output resource of the job. |
| **Flyte SDK > Packages > flyte.connectors > ResourceMeta** |This is the metadata for the job. |
| **Flyte SDK > Packages > flyte.errors > ActionAbortedError** |This error is raised when an action was aborted, externally. |
| **Flyte SDK > Packages > flyte.errors > ActionNotFoundError** |This error is raised when the user tries to access an action that does not exist. |
| **Flyte SDK > Packages > flyte.errors > BaseRuntimeError** |Base class for all Union runtime errors. |
| **Flyte SDK > Packages > flyte.errors > CodeBundleError** |This error is raised when the code bundle cannot be created, for example when no files are found to bundle. |
| **Flyte SDK > Packages > flyte.errors > CustomError** |This error is raised when the user raises a custom error. |
| **Flyte SDK > Packages > flyte.errors > DeploymentError** |This error is raised when the deployment of a task fails, or some preconditions for deployment are not met. |
| **Flyte SDK > Packages > flyte.errors > ImageBuildError** |This error is raised when the image build fails. |
| **Flyte SDK > Packages > flyte.errors > ImagePullBackOffError** |This error is raised when the image cannot be pulled. |
| **Flyte SDK > Packages > flyte.errors > InitializationError** |This error is raised when the Union system is tried to access without being initialized. |
| **Flyte SDK > Packages > flyte.errors > InlineIOMaxBytesBreached** |This error is raised when the inline IO max bytes limit is breached. |
| **Flyte SDK > Packages > flyte.errors > InvalidImageNameError** |This error is raised when the image name is invalid. |
| **Flyte SDK > Packages > flyte.errors > InvalidPackageError** |Raised when an invalid system package is detected during image build. |
| **Flyte SDK > Packages > flyte.errors > LogsNotYetAvailableError** |This error is raised when the logs are not yet available for a task. |
| **Flyte SDK > Packages > flyte.errors > ModuleLoadError** |This error is raised when the module cannot be loaded, either because it does not exist or because of a. |
| **Flyte SDK > Packages > flyte.errors > NonRecoverableError** |Raised when an error is encountered that is not recoverable. |
| **Flyte SDK > Packages > flyte.errors > NotInTaskContextError** |This error is raised when the user tries to access the task context outside of a task. |
| **Flyte SDK > Packages > flyte.errors > OOMError** |This error is raised when the underlying task execution fails because of an out-of-memory error. |
| **Flyte SDK > Packages > flyte.errors > OnlyAsyncIOSupportedError** |This error is raised when the user tries to use sync IO in an async task. |
| **Flyte SDK > Packages > flyte.errors > ParameterMaterializationError** |This error is raised when the user tries to use a Parameter in an App, that has delayed Materialization,. |
| **Flyte SDK > Packages > flyte.errors > PrimaryContainerNotFoundError** |This error is raised when the primary container is not found. |
| **Flyte SDK > Packages > flyte.errors > RemoteTaskNotFoundError** |This error is raised when the user tries to access a task that does not exist. |
| **Flyte SDK > Packages > flyte.errors > RemoteTaskUsageError** |This error is raised when the user tries to access a task that does not exist. |
| **Flyte SDK > Packages > flyte.errors > RestrictedTypeError** |This error is raised when the user uses a restricted type, for example current a Tuple is not supported for one. |
| **Flyte SDK > Packages > flyte.errors > RetriesExhaustedError** |This error is raised when the underlying task execution fails after all retries have been exhausted. |
| **Flyte SDK > Packages > flyte.errors > RuntimeDataValidationError** |This error is raised when the user tries to access a resource that does not exist or is invalid. |
| **Flyte SDK > Packages > flyte.errors > RuntimeSystemError** |This error is raised when the underlying task execution fails because of a system error. |
| **Flyte SDK > Packages > flyte.errors > RuntimeUnknownError** |This error is raised when the underlying task execution fails because of an unknown error. |
| **Flyte SDK > Packages > flyte.errors > RuntimeUserError** |This error is raised when the underlying task execution fails because of an error in the user's code. |
| **Flyte SDK > Packages > flyte.errors > SlowDownError** |This error is raised when the user tries to access a resource that does not exist or is invalid. |
| **Flyte SDK > Packages > flyte.errors > TaskInterruptedError** |This error is raised when the underlying task execution is interrupted. |
| **Flyte SDK > Packages > flyte.errors > TaskTimeoutError** |This error is raised when the underlying task execution runs for longer than the specified timeout. |
| **Flyte SDK > Packages > flyte.errors > TraceDoesNotAllowNestedTasksError** |This error is raised when the user tries to use a task from within a trace. |
| **Flyte SDK > Packages > flyte.errors > UnionRpcError** |This error is raised when communication with the Union server fails. |
| **Flyte SDK > Packages > flyte.extend > AsyncFunctionTaskTemplate** |A task template that wraps an asynchronous functions. |
| **Flyte SDK > Packages > flyte.extend > ImageBuildEngine** |ImageBuildEngine contains a list of builders that can be used to build an ImageSpec. |
| **Flyte SDK > Packages > flyte.extend > TaskTemplate** |Task template is a template for a task that can be executed. |
| **Flyte SDK > Packages > flyte.extras > BatchStats** |Monitoring statistics exposed by `DynamicBatcher. |
| [`flyte.extras.ContainerTask`](../packages/flyte.extras/containertask/page.md) |This is an intermediate class that represents Flyte Tasks that run a container at execution time. |
| [`flyte.extras.DynamicBatcher`](../packages/flyte.extras/dynamicbatcher/page.md) |Batches records from many concurrent producers and runs them through. |
| [`flyte.extras.Prompt`](../packages/flyte.extras/prompt/page.md) |Simple prompt record with built-in token estimation. |
| [`flyte.extras.TokenBatcher`](../packages/flyte.extras/tokenbatcher/page.md) |Token-aware batcher for LLM inference workloads. |
| [`flyte.git.GitStatus`](../packages/flyte.git/gitstatus/page.md) |A class representing the status of a git repository. |
| [`flyte.io.DataFrame`](../packages/flyte.io/dataframe/page.md) |A Flyte meta DataFrame object, that wraps all other dataframe types (usually available as plugins, pandas. |
| [`flyte.io.Dir`](../packages/flyte.io/dir/page.md) |A generic directory class representing a directory with files of a specified format. |
| [`flyte.io.File`](../packages/flyte.io/file/page.md) |A generic file class representing a file with a specified format. |
| [`flyte.io.HashFunction`](../packages/flyte.io/hashfunction/page.md) |A hash method that wraps a user-provided function to compute hashes. |
| [`flyte.io.extend.DataFrameDecoder`](../packages/flyte.io.extend/dataframedecoder/page.md) | |
| [`flyte.io.extend.DataFrameEncoder`](../packages/flyte.io.extend/dataframeencoder/page.md) | |
| [`flyte.io.extend.DataFrameTransformerEngine`](../packages/flyte.io.extend/dataframetransformerengine/page.md) |Think of this transformer as a higher-level meta transformer that is used for all the dataframe types. |
| [`flyte.models.ActionID`](../packages/flyte.models/actionid/page.md) |A class representing the ID of an Action, nested within a Run. |
| [`flyte.models.ActionPhase`](../packages/flyte.models/actionphase/page.md) |Represents the execution phase of a Flyte action (run). |
| [`flyte.models.Checkpoints`](../packages/flyte.models/checkpoints/page.md) |A class representing the checkpoints for a task. |
| [`flyte.models.CodeBundle`](../packages/flyte.models/codebundle/page.md) |A class representing a code bundle for a task. |
| [`flyte.models.GroupData`](../packages/flyte.models/groupdata/page.md) | |
| [`flyte.models.NativeInterface`](../packages/flyte.models/nativeinterface/page.md) |A class representing the native interface for a task. |
| [`flyte.models.PathRewrite`](../packages/flyte.models/pathrewrite/page.md) |Configuration for rewriting paths during input loading. |
| [`flyte.models.RawDataPath`](../packages/flyte.models/rawdatapath/page.md) |A class representing the raw data path for a task. |
| [`flyte.models.SerializationContext`](../packages/flyte.models/serializationcontext/page.md) |This object holds serialization time contextual information, that can be used when serializing the task and. |
| [`flyte.models.TaskContext`](../packages/flyte.models/taskcontext/page.md) |A context class to hold the current task executions context. |
| [`flyte.notify.Email`](../packages/flyte.notify/email/page.md) |Send email notifications. |
| [`flyte.notify.NamedDelivery`](../packages/flyte.notify/nameddelivery/page.md) |Use a pre-configured delivery channel by name. |
| [`flyte.notify.NamedRule`](../packages/flyte.notify/namedrule/page.md) |Reference a pre-defined notification rule by name. |
| [`flyte.notify.Notification`](../packages/flyte.notify/notification/page.md) |Base notification class. |
| [`flyte.notify.Slack`](../packages/flyte.notify/slack/page.md) |Send Slack notifications with optional Block Kit formatting. |
| [`flyte.notify.Teams`](../packages/flyte.notify/teams/page.md) |Send Microsoft Teams notifications with optional Adaptive Cards. |
| [`flyte.notify.Webhook`](../packages/flyte.notify/webhook/page.md) |Send custom HTTP webhook notifications (most flexible option). |
| [`flyte.prefetch.HuggingFaceModelInfo`](../packages/flyte.prefetch/huggingfacemodelinfo/page.md) |Information about a HuggingFace model to store. |
| [`flyte.prefetch.ShardConfig`](../packages/flyte.prefetch/shardconfig/page.md) |Configuration for model sharding. |
| [`flyte.prefetch.StoredModelInfo`](../packages/flyte.prefetch/storedmodelinfo/page.md) |Information about a stored model. |
| [`flyte.prefetch.VLLMShardArgs`](../packages/flyte.prefetch/vllmshardargs/page.md) |Arguments for sharding a model using vLLM. |
| [`flyte.remote.Action`](../packages/flyte.remote/action/page.md) |A class representing an action. |
| [`flyte.remote.ActionDetails`](../packages/flyte.remote/actiondetails/page.md) |A class representing an action. |
| [`flyte.remote.ActionInputs`](../packages/flyte.remote/actioninputs/page.md) |A class representing the inputs of an action. |
| [`flyte.remote.ActionOutputs`](../packages/flyte.remote/actionoutputs/page.md) |A class representing the outputs of an action. |
| [`flyte.remote.App`](../packages/flyte.remote/app/page.md) | |
| [`flyte.remote.Project`](../packages/flyte.remote/project/page.md) |A class representing a project in the Union API. |
| [`flyte.remote.Run`](../packages/flyte.remote/run/page.md) |A class representing a run of a task. |
| [`flyte.remote.RunDetails`](../packages/flyte.remote/rundetails/page.md) |A class representing a run of a task. |
| [`flyte.remote.Secret`](../packages/flyte.remote/secret/page.md) | |
| [`flyte.remote.Task`](../packages/flyte.remote/task/page.md) | |
| [`flyte.remote.TaskDetails`](../packages/flyte.remote/taskdetails/page.md) | |
| [`flyte.remote.TimeFilter`](../packages/flyte.remote/timefilter/page.md) |Filter for time-based fields (e. |
| [`flyte.remote.Trigger`](../packages/flyte.remote/trigger/page.md) |Represents a trigger in the Flyte platform. |
| [`flyte.remote.User`](../packages/flyte.remote/user/page.md) |Represents a user in the Flyte platform. |
| [`flyte.report.Report`](../packages/flyte.report/report/page.md) | |
| [`flyte.sandbox.CodeTaskTemplate`](../packages/flyte.sandbox/codetasktemplate/page.md) |A sandboxed task created from a code string rather than a decorated function. |
| [`flyte.sandbox.ImageConfig`](../packages/flyte.sandbox/imageconfig/page.md) |Configuration for Docker image building at runtime. |
| [`flyte.sandbox.SandboxedConfig`](../packages/flyte.sandbox/sandboxedconfig/page.md) |Configuration for a sandboxed task executed via Monty. |
| [`flyte.sandbox.SandboxedTaskTemplate`](../packages/flyte.sandbox/sandboxedtasktemplate/page.md) |A task template that executes the function body in a Monty sandbox. |
| [`flyte.storage.ABFS`](../packages/flyte.storage/abfs/page.md) |Any Azure Blob Storage specific configuration. |
| [`flyte.storage.GCS`](../packages/flyte.storage/gcs/page.md) |Any GCS specific configuration. |
| [`flyte.storage.S3`](../packages/flyte.storage/s3/page.md) |S3 specific configuration. |
| [`flyte.storage.Storage`](../packages/flyte.storage/storage/page.md) |Data storage configuration that applies across any provider. |
| [`flyte.syncify.Syncify`](../packages/flyte.syncify/syncify/page.md) |A decorator to convert asynchronous functions or methods into synchronous ones. |
| [`flyte.types.FlytePickle`](../packages/flyte.types/flytepickle/page.md) |This type is only used by flytekit internally. |
| [`flyte.types.TypeEngine`](../packages/flyte.types/typeengine/page.md) |Core Extensible TypeEngine of Flytekit. |
| [`flyte.types.TypeTransformer`](../packages/flyte.types/typetransformer/page.md) |Base transformer type that should be implemented for every python native type that can be handled by flytekit. |
| [`flyte.types.TypeTransformerFailedError`](../packages/flyte.types/typetransformerfailederror/page.md) | |
# Protocols

| Protocol | Description |
|-|-|
| [`flyte.AppHandle`](../packages/flyte/apphandle/page.md) |Protocol defining the common interface between local and remote app handles. |
| [`flyte.CachePolicy`](../packages/flyte/cachepolicy/page.md) |Protocol for custom cache version strategies. |
| [`flyte.Link`](../packages/flyte/link/page.md) | |
| [`flyte.extend.ImageBuilder`](../packages/flyte.extend/imagebuilder/page.md) | |
| [`flyte.extend.ImageChecker`](../packages/flyte.extend/imagechecker/page.md) | |
| [`flyte.extras.CostEstimator`](../packages/flyte.extras/costestimator/page.md) |Protocol for records that can estimate their own processing cost. |
| [`flyte.extras.TokenEstimator`](../packages/flyte.extras/tokenestimator/page.md) |Protocol for records that can estimate their own token count. |
| [`flyte.types.Renderable`](../packages/flyte.types/renderable/page.md) | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages ===

# Packages

| Package | Description |
|-|-|
| **Flyte SDK > Packages > flyte** | Flyte SDK for authoring compound AI applications, services and workflows. |
| **Flyte SDK > Packages > flyte.app** |  |
| **Flyte SDK > Packages > flyte.app.extras** |  |
| **Flyte SDK > Packages > flyte.config** |  |
| **Flyte SDK > Packages > flyte.connectors** |  |
| **Flyte SDK > Packages > flyte.connectors.utils** |  |
| **Flyte SDK > Packages > flyte.durable** | Flyte durable utilities. |
| **Flyte SDK > Packages > flyte.errors** | Exceptions raised by Union. |
| **Flyte SDK > Packages > flyte.extend** |  |
| **Flyte SDK > Packages > flyte.extras** | Flyte extras package. |
| **Flyte SDK > Packages > flyte.git** |  |
| **Flyte SDK > Packages > flyte.io** | ## IO data types. |
| **Flyte SDK > Packages > flyte.io.extend** |  |
| **Flyte SDK > Packages > flyte.models** |  |
| **Flyte SDK > Packages > flyte.notify** | Task Notifications API for Flyte 2. |
| **Flyte SDK > Packages > flyte.prefetch** | Prefetch utilities for Flyte. |
| **Flyte SDK > Packages > flyte.remote** | Remote Entities that are accessible from the Union Server once deployed or created. |
| **Flyte SDK > Packages > flyte.report** |  |
| **Flyte SDK > Packages > flyte.sandbox** | Sandbox utilities for running isolated code inside Flyte tasks. |
| **Flyte SDK > Packages > flyte.storage** |  |
| **Flyte SDK > Packages > flyte.syncify** | # Syncify Module. |
| **Flyte SDK > Packages > flyte.types** | # Flyte Type System. |

## Subpages
- **Flyte SDK > Packages > flyte**
- **Flyte SDK > Packages > flyte.app**
- **Flyte SDK > Packages > flyte.app.extras**
- **Flyte SDK > Packages > flyte.config**
- **Flyte SDK > Packages > flyte.connectors**
- **Flyte SDK > Packages > flyte.connectors.utils**
- **Flyte SDK > Packages > flyte.durable**
- **Flyte SDK > Packages > flyte.errors**
- **Flyte SDK > Packages > flyte.extend**
- **Flyte SDK > Packages > flyte.extras**
- **Flyte SDK > Packages > flyte.git**
- **Flyte SDK > Packages > flyte.io**
- **Flyte SDK > Packages > flyte.io.extend**
- **Flyte SDK > Packages > flyte.models**
- **Flyte SDK > Packages > flyte.notify**
- **Flyte SDK > Packages > flyte.prefetch**
- **Flyte SDK > Packages > flyte.remote**
- **Flyte SDK > Packages > flyte.report**
- **Flyte SDK > Packages > flyte.sandbox**
- **Flyte SDK > Packages > flyte.storage**
- **Flyte SDK > Packages > flyte.syncify**
- **Flyte SDK > Packages > flyte.types**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte ===

# flyte

Flyte SDK for authoring compound AI applications, services and workflows.
## Directory

### Classes

| Class | Description |
|-|-|
| **Flyte SDK > Packages > flyte > Cache** | Cache configuration for a task. |
| **Flyte SDK > Packages > flyte > Cron** | Cron-based automation schedule for use with `Trigger`. |
| **Flyte SDK > Packages > flyte > Device** | Represents a device type, its quantity and partition if applicable. |
| **Flyte SDK > Packages > flyte > Environment** |  |
| **Flyte SDK > Packages > flyte > FixedRate** | Fixed-rate (interval-based) automation schedule for use with `Trigger`. |
| **Flyte SDK > Packages > flyte > Image** | Container image specification built using a fluent, two-step pattern:. |
| **Flyte SDK > Packages > flyte > ImageBuild** | Result of an image build operation. |
| **Flyte SDK > Packages > flyte > PodTemplate** | Custom PodTemplate specification for a Task. |
| **Flyte SDK > Packages > flyte > Resources** | Resources such as CPU, Memory, and GPU that can be allocated to a task. |
| **Flyte SDK > Packages > flyte > RetryStrategy** | Retry strategy for the task or task environment. |
| **Flyte SDK > Packages > flyte > ReusePolicy** | Configure a task environment for container reuse across multiple task invocations. |
| **Flyte SDK > Packages > flyte > Secret** | Secrets are used to inject sensitive information into tasks or image build context. |
| **Flyte SDK > Packages > flyte > TaskEnvironment** | Define an execution environment for a set of tasks. |
| **Flyte SDK > Packages > flyte > Timeout** | Timeout class to define a timeout for a task. |
| **Flyte SDK > Packages > flyte > Trigger** | Specification for a scheduled trigger that can be associated with any Flyte task. |

### Protocols

| Protocol | Description |
|-|-|
| **Flyte SDK > Packages > flyte > AppHandle** | Protocol defining the common interface between local and remote app handles. |
| **Flyte SDK > Packages > flyte > CachePolicy** | Protocol for custom cache version strategies. |
| **Flyte SDK > Packages > flyte > Link** |  |

### Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte > Methods > AMD_GPU()** | Create an AMD GPU device instance. |
| **Flyte SDK > Packages > flyte > Methods > GPU()** | Create a GPU device instance. |
| **Flyte SDK > Packages > flyte > Methods > HABANA_GAUDI()** | Create a Habana Gaudi device instance. |
| **Flyte SDK > Packages > flyte > Methods > Neuron()** | Create a Neuron device instance. |
| **Flyte SDK > Packages > flyte > Methods > TPU()** | Create a TPU device instance. |
| **Flyte SDK > Packages > flyte > Methods > build()** | Build an image. |
| **Flyte SDK > Packages > flyte > Methods > build_images()** | Build the images for the given environments. |
| **Flyte SDK > Packages > flyte > Methods > ctx()** | Returns flyte. |
| **Flyte SDK > Packages > flyte > Methods > current_domain()** | Returns the current domain from Runtime environment (on the cluster) or from the initialized configuration. |
| **Flyte SDK > Packages > flyte > Methods > current_project()** | Returns the current project from the Runtime environment (on the cluster) or from the initialized configuration. |
| **Flyte SDK > Packages > flyte > Methods > custom_context()** | Synchronous context manager to set input context for tasks spawned within this block. |
| **Flyte SDK > Packages > flyte > Methods > deploy()** | Deploy the given environment or list of environments. |
| **Flyte SDK > Packages > flyte > Methods > get_custom_context()** | Get the current input context. |
| **Flyte SDK > Packages > flyte > Methods > group()** | Create a new group with the given name. |
| **Flyte SDK > Packages > flyte > Methods > init()** | Initialize the Flyte system with the given configuration. |
| **Flyte SDK > Packages > flyte > Methods > init_from_api_key()** | Initialize the Flyte system using an API key for authentication. |
| **Flyte SDK > Packages > flyte > Methods > init_from_config()** | Initialize the Flyte system using a configuration file or Config object. |
| **Flyte SDK > Packages > flyte > Methods > init_in_cluster()** |  |
| **Flyte SDK > Packages > flyte > Methods > init_passthrough()** | Initialize the Flyte system with passthrough authentication. |
| **Flyte SDK > Packages > flyte > Methods > map()** | Map a function over the provided arguments with concurrent execution. |
| **Flyte SDK > Packages > flyte > Methods > run()** | Run a task with the given parameters. |
| **Flyte SDK > Packages > flyte > Methods > run_python_script()** | Package and run a Python script on a remote Flyte cluster. |
| **Flyte SDK > Packages > flyte > Methods > serve()** | Serve a Flyte app using an AppEnvironment. |
| **Flyte SDK > Packages > flyte > trace()** | A decorator that traces function execution with timing information. |
| **Flyte SDK > Packages > flyte > version()** | Returns the version of the Flyte SDK. |
| **Flyte SDK > Packages > flyte > with_runcontext()** | Launch a new run with the given parameters as the context. |
| **Flyte SDK > Packages > flyte > with_servecontext()** | Create a serve context with custom configuration. |

### Variables

| Property | Type | Description |
|-|-|-|
| `TimeoutType` | `UnionType` |  |
| `TriggerTime` | `_trigger_time` |  |
| `__version__` | `str` |  |
| `logger` | `Logger` |  |

## Methods

#### AMD_GPU()

```python
def AMD_GPU(
    device: typing.Literal['MI100', 'MI210', 'MI250', 'MI250X', 'MI300A', 'MI300X', 'MI325X', 'MI350X', 'MI355X'],
) -> flyte._resources.Device
```
Create an AMD GPU device instance.

| Parameter | Type | Description |
|-|-|-|
| `device` | `typing.Literal['MI100', 'MI210', 'MI250', 'MI250X', 'MI300A', 'MI300X', 'MI325X', 'MI350X', 'MI355X']` | Device type (e.g., "MI100", "MI210", "MI250", "MI250X", "MI300A", "MI300X", "MI325X", "MI350X", "MI355X"). |

**Returns:** Device instance.

#### GPU()

```python
def GPU(
    device: typing.Literal['A10', 'A10G', 'A100', 'A100 80G', 'B200', 'H100', 'H200', 'L4', 'L40s', 'T4', 'V100', 'RTX PRO 6000', 'GB10'],
    quantity: typing.Literal[1, 2, 3, 4, 5, 6, 7, 8],
    partition: typing.Union[typing.Literal['1g.5gb', '2g.10gb', '3g.20gb', '4g.20gb', '7g.40gb'], typing.Literal['1g.10gb', '2g.20gb', '3g.40gb', '4g.40gb', '7g.80gb'], typing.Literal['1g.10gb', '1g.20gb', '2g.20gb', '3g.40gb', '4g.40gb', '7g.80gb'], typing.Literal['1g.18gb', '1g.35gb', '2g.35gb', '3g.71gb', '4g.71gb', '7g.141gb'], NoneType],
) -> flyte._resources.Device
```
Create a GPU device instance.

| Parameter | Type | Description |
|-|-|-|
| `device` | `typing.Literal['A10', 'A10G', 'A100', 'A100 80G', 'B200', 'H100', 'H200', 'L4', 'L40s', 'T4', 'V100', 'RTX PRO 6000', 'GB10']` | The type of GPU (e.g., "T4", "A100"). |
| `quantity` | `typing.Literal[1, 2, 3, 4, 5, 6, 7, 8]` | The number of GPUs of this type. |
| `partition` | `typing.Union[typing.Literal['1g.5gb', '2g.10gb', '3g.20gb', '4g.20gb', '7g.40gb'], typing.Literal['1g.10gb', '2g.20gb', '3g.40gb', '4g.40gb', '7g.80gb'], typing.Literal['1g.10gb', '1g.20gb', '2g.20gb', '3g.40gb', '4g.40gb', '7g.80gb'], typing.Literal['1g.18gb', '1g.35gb', '2g.35gb', '3g.71gb', '4g.71gb', '7g.141gb'], NoneType]` | The partition of the GPU (e.g., "1g.5gb", "2g.10gb" for gpus) or ("1x1", ... for tpus). |

**Returns:** Device instance.

#### HABANA_GAUDI()

```python
def HABANA_GAUDI(
    device: typing.Literal['Gaudi1'],
) -> flyte._resources.Device
```
Create a Habana Gaudi device instance.

| Parameter | Type | Description |
|-|-|-|
| `device` | `typing.Literal['Gaudi1']` | Device type (e.g., "Gaudi1"). |

**Returns:** Device instance.

#### Neuron()

```python
def Neuron(
    device: typing.Literal['Inf1', 'Inf2', 'Trn1', 'Trn1n', 'Trn2', 'Trn2u'],
) -> flyte._resources.Device
```
Create a Neuron device instance.

| Parameter | Type | Description |
|-|-|-|
| `device` | `typing.Literal['Inf1', 'Inf2', 'Trn1', 'Trn1n', 'Trn2', 'Trn2u']` | Device type (e.g., "Inf1", "Inf2", "Trn1", "Trn1n", "Trn2", "Trn2u"). |

**Returns:** Device instance.

#### TPU()

```python
def TPU(
    device: typing.Literal['V5P', 'V6E'],
    partition: typing.Union[typing.Literal['2x2x1', '2x2x2', '2x4x4', '4x4x4', '4x4x8', '4x8x8', '8x8x8', '8x8x16', '8x16x16', '16x16x16', '16x16x24'], typing.Literal['1x1', '2x2', '2x4', '4x4', '4x8', '8x8', '8x16', '16x16'], NoneType],
)
```
Create a TPU device instance.

| Parameter | Type | Description |
|-|-|-|
| `device` | `typing.Literal['V5P', 'V6E']` | Device type (e.g., "V5P", "V6E"). |
| `partition` | `typing.Union[typing.Literal['2x2x1', '2x2x2', '2x4x4', '4x4x4', '4x4x8', '4x8x8', '8x8x8', '8x8x16', '8x16x16', '16x16x16', '16x16x24'], typing.Literal['1x1', '2x2', '2x4', '4x4', '4x8', '8x8', '8x16', '16x16'], NoneType]` | Partition of the TPU (e.g., "1x1", "2x2", ...). |

**Returns:** Device instance.

#### build()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await build.aio()`.
```python
def build(
    image: Image,
    dry_run: bool,
    force: bool,
    wait: bool,
) -> ImageBuild
```
Build an image. The existing async context will be used.

```
import flyte
image = flyte.Image("example_image")
if __name__ == "__main__":
    result = asyncio.run(flyte.build.aio(image))
    print(result.uri)
```

| Parameter | Type | Description |
|-|-|-|
| `image` | `Image` | The image(s) to build. |
| `dry_run` | `bool` | Tell the builder to not actually build. Different builders will have different behaviors. |
| `force` | `bool` | Skip the existence check and force a rebuild. When using the remote builder, this also sets overwrite_cache=True on the build run. |
| `wait` | `bool` | Wait for the build to finish. If wait is False, the function will return immediately and the build will run in the background. |

**Returns:** An ImageBuild object with the image URI and remote run (if applicable).

#### build_images()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await build_images.aio()`.
```python
def build_images(
    envs: Environment,
) -> ImageCache
```
Build the images for the given environments.

| Parameter | Type | Description |
|-|-|-|
| `envs` | `Environment` | Environment to build images for. |

**Returns:** ImageCache containing the built images.

#### ctx()

```python
def ctx()
```
Returns flyte.models.TaskContext if within a task context, else None
Note: Only use this in task code and not module level.

#### current_domain()

```python
def current_domain()
```
Returns the current domain from Runtime environment (on the cluster) or from the initialized configuration.
This is safe to be used during `deploy`, `run` and within `task` code.

NOTE: This will not work if you deploy a task to a domain and then run it in another domain.

Raises InitializationError if the configuration is not initialized or domain is not set.

**Returns:** The current domain

#### current_project()

```python
def current_project()
```
Returns the current project from the Runtime environment (on the cluster) or from the initialized configuration.
This is safe to be used during `deploy`, `run` and within `task` code.

NOTE: This will not work if you deploy a task to a project and then run it in another project.

Raises InitializationError if the configuration is not initialized or project is not set.

**Returns:** The current project

#### custom_context()

```python
def custom_context(
    context: str,
)
```
Synchronous context manager to set input context for tasks spawned within this block.

```python
import flyte

env = flyte.TaskEnvironment(name="...")

@env.task
def t1():
    ctx = flyte.get_custom_context()
    print(ctx)

@env.task
def main():
    # context can be passed via a context manager
    with flyte.custom_context(project="my-project"):
        t1()  # will have {'project': 'my-project'} as context
```

| Parameter | Type | Description |
|-|-|-|
| `context` | `str` | Key-value pairs to set as input context |

#### deploy()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await deploy.aio()`.
```python
def deploy(
    envs: Environment,
    dryrun: bool,
    version: str | None,
    interactive_mode: bool | None,
    copy_style: CopyFiles,
) -> List[Deployment]
```
Deploy the given environment or list of environments.

| Parameter | Type | Description |
|-|-|-|
| `envs` | `Environment` | Environment or list of environments to deploy. |
| `dryrun` | `bool` | dryrun mode, if True, the deployment will not be applied to the control plane. |
| `version` | `str \| None` | version of the deployment, if None, the version will be computed from the code bundle. TODO: Support for interactive_mode |
| `interactive_mode` | `bool \| None` | Optional, can be forced to True or False. If not provided, it will be set based on the current environment. For example Jupyter notebooks are considered interactive mode, while scripts are not. This is used to determine how the code bundle is created. |
| `copy_style` | `CopyFiles` | Copy style to use when running the task |

**Returns:** Deployment object containing the deployed environments and tasks.

#### get_custom_context()

```python
def get_custom_context()
```
Get the current input context. This can be used within a task to retrieve
context metadata that was passed to the action.

Context will automatically propagate to sub-actions.

```python
import flyte

env = flyte.TaskEnvironment(name="...")

@env.task
def t1():
    # context can be retrieved with `get_custom_context`
    ctx = flyte.get_custom_context()
    print(ctx)  # {'project': '...', 'entity': '...'}
CODE15python
def group(
    name: str,
)
CODE16python
@task
async def my_task():
    ...
    with group("my_group"):
        t1(x,y)  # tasks in this block will be grouped under "my_group"
    ...
```

| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | The name of the group |

#### init()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await init.aio()`.
CODE17
Initialize the Flyte system with the given configuration. This method should be called before any other Flyte
remote API methods are called. Thread-safe implementation.

| Parameter | Type | Description |
|-|-|-|
| `org` | `str \| None` | Optional organization override for the client. Should be set by auth instead. |
| `project` | `str \| None` | Optional project name (not used in this implementation) |
| `domain` | `str \| None` | Optional domain name (not used in this implementation) |
| `root_dir` | `Path \| None` | Optional root directory from which to determine how to load files, and find paths to files. This is useful for determining the root directory for the current project, and for locating files like config etc. also use to determine all the code that needs to be copied to the remote location. defaults to the editable install directory if the cwd is in a Python editable install, else just the cwd. |
| `log_level` | `int \| None` | Optional logging level for the logger, default is set using the default initialization policies |
| `log_format` | `LogFormat \| None` | Optional logging format for the logger, default is "console" |
| `reset_root_logger` | `bool` | By default, we clear out root logger handlers and set up our own. |
| `endpoint` | `str \| None` | Optional API endpoint URL |
| `headless` | `bool` | Optional Whether to run in headless mode |
| `insecure` | `bool` | insecure flag for the client |
| `insecure_skip_verify` | `bool` | Whether to skip SSL certificate verification |
| `ca_cert_file_path` | `str \| None` | [optional] str Root Cert to be loaded and used to verify admin |
| `auth_type` | `AuthType` | The authentication type to use (Pkce, ClientSecret, ExternalCommand, DeviceFlow) |
| `command` | `List[str] \| None` | This command is executed to return a token using an external process |
| `proxy_command` | `List[str] \| None` | This command is executed to return a token for proxy authorization using an external process |
| `api_key` | `str \| None` | Optional API key for authentication |
| `client_id` | `str \| None` | This is the public identifier for the app which handles authorization for a Flyte deployment. More details here: https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/. |
| `client_credentials_secret` | `str \| None` | Used for service auth, which is automatically called during pyflyte. This will allow the Flyte engine to read the password directly from the environment variable. Note that this is less secure! Please only use this if mounting the secret as a file is impossible |
| `auth_client_config` | `ClientConfig \| None` | Optional client configuration for authentication |
| `rpc_retries` | `int` | [optional] int Number of times to retry the platform calls |
| `http_proxy_url` | `str \| None` | [optional] HTTP Proxy to be used for OAuth requests |
| `storage` | `Storage \| None` | Optional blob store (S3, GCS, Azure) configuration if needed to access (i.e. using Minio) |
| `batch_size` | `int` | Optional batch size for operations that use listings, defaults to 1000, so limit larger than batch_size will be split into multiple requests. |
| `image_builder` | `ImageBuildEngine.ImageBuilderType` | Optional image builder configuration, if not provided, the default image builder will be used. |
| `images` | `typing.Dict[str, str] \| None` | Optional dict of images that can be used by referencing the image name. |
| `source_config_path` | `Optional[Path]` | Optional path to the source configuration file (This is only used for documentation) |
| `sync_local_sys_paths` | `bool` | Whether to include and synchronize local sys.path entries under the root directory into the remote container (default: True). |
| `load_plugin_type_transformers` | `bool` | If enabled (default True), load the type transformer plugins registered under the "flyte.plugins.types" entry point group. |
| `local_persistence` | `bool` | Whether to enable SQLite persistence for local run metadata (default |

**Returns:** None

#### init_from_api_key()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await init_from_api_key.aio()`.
CODE18
Initialize the Flyte system using an API key for authentication. This is a convenience
method for API key-based authentication. Thread-safe implementation.

The API key should be an encoded API key that contains the endpoint, client ID, client secret,
and organization information. You can obtain this encoded API key from your Flyte administrator
or cloud provider.

| Parameter | Type | Description |
|-|-|-|
| `api_key` | `str \| None` | Optional encoded API key for authentication. If None, reads from FLYTE_API_KEY environment variable. The API key is a base64-encoded string containing endpoint, client_id, client_secret, and org information. |
| `project` | `str \| None` | Optional project name |
| `domain` | `str \| None` | Optional domain name |
| `root_dir` | `Path \| None` | Optional root directory from which to determine how to load files, and find paths to files. defaults to the editable install directory if the cwd is in a Python editable install, else just the cwd. |
| `log_level` | `int \| None` | Optional logging level for the logger |
| `log_format` | `LogFormat \| None` | Optional logging format for the logger, default is "console" |
| `storage` | `Storage \| None` | Optional blob store (S3, GCS, Azure) configuration |
| `batch_size` | `int` | Optional batch size for operations that use listings, defaults to 1000 |
| `image_builder` | `ImageBuildEngine.ImageBuilderType` | Optional image builder configuration |
| `images` | `typing.Dict[str, str] \| None` | Optional dict of images that can be used by referencing the image name |
| `sync_local_sys_paths` | `bool` | Whether to include and synchronize local sys.path entries under the root directory into the remote container (default: True) |

**Returns:** None

#### init_from_config()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await init_from_config.aio()`.
CODE19
Initialize the Flyte system using a configuration file or Config object. This method should be called before any
other Flyte remote API methods are called. Thread-safe implementation.

| Parameter | Type | Description |
|-|-|-|
| `path_or_config` | `str \| Path \| Config \| None` | Path to the configuration file or Config object |
| `root_dir` | `Path \| None` | Optional root directory from which to determine how to load files, and find paths to files like config etc. For example if one uses the copy-style=="all", it is essential to determine the root directory for the current project. If not provided, it defaults to the editable install directory or if not available, the current working directory. |
| `log_level` | `int \| None` | Optional logging level for the framework logger, default is set using the default initialization policies |
| `log_format` | `LogFormat` | Optional logging format for the logger, default is "console" |
| `project` | `str \| None` | Project name, this will override any project names in the configuration file |
| `domain` | `str \| None` | Domain name, this will override any domain names in the configuration file |
| `storage` | `Storage \| None` | Optional blob store (S3, GCS, Azure) configuration if needed to access (i.e. using Minio) |
| `batch_size` | `int` | Optional batch size for operations that use listings, defaults to 1000 |
| `image_builder` | `ImageBuildEngine.ImageBuilderType \| None` | Optional image builder configuration, if provided, will override any defaults set in the configuration. |
| `images` | `tuple[str, ...] \| None` | List of image strings in format "imagename=imageuri" or just "imageuri". |
| `sync_local_sys_paths` | `bool` | Whether to include and synchronize local sys.path entries under the root directory into the remote container (default: True). |

**Returns:** None

#### init_in_cluster()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await init_in_cluster.aio()`.
CODE20
| Parameter | Type | Description |
|-|-|-|
| `org` | `str \| None` | |
| `project` | `str \| None` | |
| `domain` | `str \| None` | |
| `api_key` | `str \| None` | |
| `endpoint` | `str \| None` | |
| `insecure` | `bool` | |

#### init_passthrough()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await init_passthrough.aio()`.
CODE21
Initialize the Flyte system with passthrough authentication.

This authentication mode allows you to pass custom authentication metadata
using the `flyte.remote.auth_metadata()` context manager.

The endpoint is automatically configured from the environment if in a flyte cluster with endpoint injected.

| Parameter | Type | Description |
|-|-|-|
| `endpoint` | `str \| None` | Optional API endpoint URL |
| `org` | `str \| None` | Optional organization name |
| `project` | `str \| None` | Optional project name |
| `domain` | `str \| None` | Optional domain name |
| `insecure` | `bool` | Whether to use an insecure channel |

**Returns:** Dictionary of remote kwargs used for initialization

#### map()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await flyte.map.aio()`.
CODE22
Map a function over the provided arguments with concurrent execution.

| Parameter | Type | Description |
|-|-|-|
| `func` | `typing.Union[flyte._task.AsyncFunctionTaskTemplate[~P, ~R, ~F], functools.partial[~R]]` | The async function to map. |
| `args` | `*args` | Positional arguments to pass to the function (iterables that will be zipped). |
| `group_name` | `str \| None` | The name of the group for the mapped tasks. |
| `concurrency` | `int` | The maximum number of concurrent tasks to run. If 0, run all tasks concurrently. |
| `return_exceptions` | `bool` | If True, yield exceptions instead of raising them. |

**Returns:** AsyncIterator yielding results in order.

#### run()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await run.aio()`.
CODE23
Run a task with the given parameters

| Parameter | Type | Description |
|-|-|-|
| `task` | `TaskTemplate[P, R, F]` | task to run |
| `args` | `*args` | args to pass to the task |
| `kwargs` | `**kwargs` | kwargs to pass to the task |

**Returns:** Run | Result of the task

#### run_python_script()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await run_python_script.aio()`.
CODE24
Package and run a Python script on a remote Flyte cluster.

Bundles the script into a Flyte code bundle and executes it remotely
with the requested resources.  Unlike `interactive_mode` (which
pickles the task), this approach uses an `InternalTaskResolver`
so the task can be properly debugged with `debug=True`.

Project and domain are read from the init config (set via `flyte.init()`
or `flyte.init_from_config()`), consistent with `flyte.run()`.

| Parameter | Type | Description |
|-|-|-|
| `script` | `pathlib.Path` | Path to the Python script to run. |
| `cpu` | `int` | Number of CPUs to request (default |
| `memory` | `str` | Memory to request, e.g. `"16Gi"` (default |
| `gpu` | `int` | Number of GPUs to request (default |
| `gpu_type` | `str` | GPU accelerator type Only used when `gpu &gt; 0` (default: `"T4"`). |
| `image` | `Union[Image, List[str], None]` | Container image to use. Accepts either  - A `flyte.Image` object for full control over the image. - A `list[str]` of pip package names to install on top of the default Debian base image (e.g. `["torch", "transformers"]`). - `None` to use a plain Debian base image (default). |
| `timeout` | `int` | Task timeout in seconds (default |
| `extra_args` | `Optional[List[str]]` | Extra arguments passed to the script. |
| `queue` | `Optional[str]` | Flyte queue / cluster override. |
| `wait` | `bool` | If True, block until execution completes before returning. |
| `name` | `Optional[str]` | Run name. If omitted, a random name is generated. |
| `debug` | `bool` | If True, run the task as a VS Code debug task, starting a code-server in the container so you can connect via the UI to interactively debug/run the task. |
| `output_dir` | `Optional[str]` | |

**Returns:** A `flyte.remote.Run` handle for the remote execution.

#### serve()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await serve.aio()`.
CODE25
Serve a Flyte app using an AppEnvironment.

This is the simple, direct way to serve an app. For more control over
deployment settings (env vars, cluster pool, etc.), use with_servecontext().

CODE26

See Also:
    with_servecontext: For customizing deployment settings

| Parameter | Type | Description |
|-|-|-|
| `app_env` | `'AppEnvironment'` | The app environment to serve |

**Returns**

An `AppHandle` — either a `_LocalApp` (local) or `App` (remote)

#### trace()

CODE27
A decorator that traces function execution with timing information.
Works with regular functions, sync generators, async functions, and async generators/iterators.

| Parameter | Type | Description |
|-|-|-|
| `func` | `typing.Callable[..., ~T]` | |

#### version()

CODE28
Returns the version of the Flyte SDK.

#### with_runcontext()

CODE29
Launch a new run with the given parameters as the context.

CODE30

| Parameter | Type | Description |
|-|-|-|
| `mode` | `Mode \| None` | Optional The mode to use for the run, if not provided, it will be computed from flyte.init |
| `name` | `Optional[str]` | Optional The name to use for the run |
| `service_account` | `Optional[str]` | Optional The service account to use for the run context |
| `version` | `Optional[str]` | Optional The version to use for the run, if not provided, it will be computed from the code bundle |
| `copy_style` | `CopyFiles` | Optional The copy style to use for the run context |
| `dry_run` | `bool` | Optional If true, the run will not be executed, but the bundle will be created |
| `copy_bundle_to` | `pathlib.Path \| None` | When dry_run is True, the bundle will be copied to this location if specified |
| `interactive_mode` | `bool \| None` | Optional, can be forced to True or False. If not provided, it will be set based on the current environment. For example Jupyter notebooks are considered interactive mode, while scripts are not. This is used to determine how the code bundle is created. |
| `raw_data_path` | `str \| None` | Use this path to store the raw data for the run for local and remote, and can be used to store raw data in specific locations. |
| `run_base_dir` | `str \| None` | Optional The base directory to use for the run. This is used to store the metadata for the run, that is passed between tasks. |
| `overwrite_cache` | `bool` | Optional If true, the cache will be overwritten for the run |
| `project` | `str \| None` | Optional The project to use for the run |
| `domain` | `str \| None` | Optional The domain to use for the run |
| `env_vars` | `Dict[str, str] \| None` | Optional Environment variables to set for the run |
| `labels` | `Dict[str, str] \| None` | Optional Labels to set for the run |
| `annotations` | `Dict[str, str] \| None` | Optional Annotations to set for the run |
| `interruptible` | `bool \| None` | Optional If true, the run can be scheduled on interruptible instances and false implies that all tasks in the run should only be scheduled on non-interruptible instances. If not specified the original setting on all tasks is retained. |
| `log_level` | `int \| None` | Optional Log level to set for the run. If not provided, it will be set to the default log level set using `flyte.init()` |
| `log_format` | `LogFormat` | Optional Log format to set for the run. If not provided, it will be set to the default log format |
| `reset_root_logger` | `bool` | If true, the root logger will be preserved and not modified by Flyte. |
| `disable_run_cache` | `bool` | Optional If true, the run cache will be disabled. This is useful for testing purposes. |
| `queue` | `Optional[str]` | Optional The queue to use for the run. This is used to specify the cluster to use for the run. |
| `notifications` | `Notification \| Tuple[Notification, ...] \| None` | Optional Notification(s) to send when the run reaches specific execution phases. Accepts a single notification or a tuple of notifications. Supports Email, Slack, Teams, and Webhook types. See `flyte.notify` for available notification types and template variables. |
| `custom_context` | `Dict[str, str] \| None` | Optional global input context to pass to the task. This will be available via get_custom_context() within the task and will automatically propagate to sub-tasks. Acts as base/default values that can be overridden by context managers in the code. |
| `cache_lookup_scope` | `CacheLookupScope` | Optional Scope to use for the run. This is used to specify the scope to use for cache lookups. If not specified, it will be set to the default scope (global unless overridden at the system level). |
| `preserve_original_types` | `bool` | Optional If true, the type engine will preserve original types (e.g., pd.DataFrame) when guessing python types from literal types. If false (default), it will return the generic flyte.io.DataFrame. This option is automatically set to True if interactive_mode is True unless overridden explicitly by this parameter. |
| `debug` | `bool` | Optional If true, the task will be run as a VSCode debug task, starting a code-server in the container so users can connect via the UI to interactively debug/run the task. |
| `_tracker` | `Any` | This is an internal only parameter used by the CLI to render the TUI. |

**Returns:** runner

#### with_servecontext()

CODE31
Create a serve context with custom configuration.

This function allows you to customize how an app is served, including
overriding environment variables, cluster pool, logging, and other deployment settings.

Use `mode="local"` to serve the app on localhost (non-blocking) so you can
immediately invoke tasks that call the app endpoint:

CODE32

Use `mode="remote"` (or omit *mode* when a Flyte client is configured) to
deploy the app to the Flyte backend:

CODE33

| Parameter | Type | Description |
|-|-|-|
| `mode` | `ServeMode \| None` | "local" to run on localhost, "remote" to deploy to the Flyte backend. When `None` the mode is inferred from the current configuration. |
| `version` | `Optional[str]` | Optional version override for the app deployment |
| `copy_style` | `CopyFiles` | Code bundle copy style. Options: "loaded_modules", "all", "none" (default: "loaded_modules") |
| `dry_run` | `bool` | If True, don't actually deploy (default: False) |
| `project` | `str \| None` | Optional project override |
| `domain` | `str \| None` | Optional domain override |
| `env_vars` | `dict[str, str] \| None` | Optional environment variables to inject/override in the app container |
| `parameter_values` | `dict[str, dict[str, str \| flyte.io.File \| flyte.io.Dir]] \| None` | Optional parameter values to inject/override in the app container. Must be a dictionary that maps app environment names to a dictionary of parameter names to values. |
| `cluster_pool` | `str \| None` | Optional cluster pool to deploy the app to |
| `log_level` | `int \| None` | Optional log level (e.g., logging.DEBUG, logging.INFO). If not provided, uses init config or default |
| `log_format` | `LogFormat` | Optional log format ("console" or "json", default: "console") |
| `interactive_mode` | `bool \| None` | Optional, can be forced to True or False. If not provided, it will be set based on the current environment. For example Jupyter notebooks are considered interactive mode, while scripts are not. This is used to determine how the code bundle is created. This is used to determine if the app should be served in interactive mode or not. |
| `copy_bundle_to` | `pathlib.Path \| None` | When dry_run is True, the bundle will be copied to this location if specified |
| `deactivate_timeout` | `float \| None` | Timeout in seconds for waiting for the app to stop during `deactivate(wait=True)`. Defaults to 6 s. |
| `activate_timeout` | `float \| None` | Total timeout in seconds when polling the health-check endpoint during `activate(wait=True)`. Defaults to 60 s. |
| `health_check_timeout` | `float \| None` | Per-request timeout in seconds for each health-check HTTP request. Defaults to 2 s. |
| `health_check_interval` | `float \| None` | Interval in seconds between consecutive health-check polls. Defaults to 1 s. |
| `health_check_path` | `str \| None` | URL path used for the local health-check probe (e.g. ``"/healthz"``). Defaults to ``"/health"``. |
| `raw_data_path` | `str \| None` | Raw data path for the app. For local serving, sets ctx().raw_data_path so apps can read it. Defaults to ``/tmp/flyte/raw_data`` when mode is local. For remote serving, the backend provides this via the container command. |

**Returns**

_Serve: Serve context manager with configured settings

**Raises**

| Exception | Description |
|-|-|
| `NotImplementedError` | If called from a notebook/interactive environment (remote mode only) |

> [!NOTE]
> - Apps do not support pickle-based bundling (interactive mode)
> - LOG_LEVEL and LOG_FORMAT are automatically set as env vars if not explicitly provided in env_vars
> - The env_vars and cluster_pool overrides mutate the app IDL after creation
> - This is a temporary solution until the API natively supports these fields

## Subpages
- **Flyte SDK > Packages > flyte > AppHandle**
- **Flyte SDK > Packages > flyte > Cache**
- **Flyte SDK > Packages > flyte > CachePolicy**
- **Flyte SDK > Packages > flyte > Cron**
- **Flyte SDK > Packages > flyte > Device**
- **Flyte SDK > Packages > flyte > Environment**
- **Flyte SDK > Packages > flyte > FixedRate**
- **Flyte SDK > Packages > flyte > Image**
- **Flyte SDK > Packages > flyte > ImageBuild**
- **Flyte SDK > Packages > flyte > Link**
- **Flyte SDK > Packages > flyte > PodTemplate**
- **Flyte SDK > Packages > flyte > Resources**
- **Flyte SDK > Packages > flyte > RetryStrategy**
- **Flyte SDK > Packages > flyte > ReusePolicy**
- **Flyte SDK > Packages > flyte > Secret**
- **Flyte SDK > Packages > flyte > TaskEnvironment**
- **Flyte SDK > Packages > flyte > Timeout**
- **Flyte SDK > Packages > flyte > Trigger**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte/apphandle ===

# AppHandle

**Package:** `flyte`

Protocol defining the common interface between local and remote app handles.

Both `_LocalApp` (local serving) and `App` (remote serving) satisfy this
protocol, enabling calling code to work uniformly regardless of the serving mode.

```python
protocol AppHandle()
```
## Properties

| Property | Type | Description |
|-|-|-|
| `endpoint` | `None` |  |
| `name` | `None` |  |
| `url` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte > AppHandle > Methods > activate()** |  |
| **Flyte SDK > Packages > flyte > AppHandle > Methods > deactivate()** |  |
| **Flyte SDK > Packages > flyte > AppHandle > Methods > ephemeral_ctx()** |  |
| **Flyte SDK > Packages > flyte > AppHandle > Methods > ephemeral_ctx_sync()** |  |
| **Flyte SDK > Packages > flyte > AppHandle > Methods > is_active()** |  |
| **Flyte SDK > Packages > flyte > AppHandle > Methods > is_deactivated()** |  |

### activate()

```python
def activate(
    wait: bool,
) -> AppHandle
```
| Parameter | Type | Description |
|-|-|-|
| `wait` | `bool` | |

### deactivate()

```python
def deactivate(
    wait: bool,
) -> AppHandle
```
| Parameter | Type | Description |
|-|-|-|
| `wait` | `bool` | |

### ephemeral_ctx()

```python
def ephemeral_ctx()
```
### ephemeral_ctx_sync()

```python
def ephemeral_ctx_sync()
```
### is_active()

```python
def is_active()
```
### is_deactivated()

```python
def is_deactivated()
```


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte/cache ===

# Cache

**Package:** `flyte`

Cache configuration for a task.

Three cache behaviors are available:

- `"auto"` — Cache version is computed automatically from cache policies
  (default: `FunctionBodyPolicy`, which hashes the function source code).
  Any change to the function body invalidates the cache.
- `"override"` — You provide an explicit `version_override` string.
  Cache is only invalidated when you change the version.
- `"disable"` — Caching is disabled; task always re-executes.

Set via `TaskEnvironment(cache=...)`, `@env.task(cache=...)`, or
`task.override(cache=...)`.

## Parameters

```python
class Cache(
    behavior: typing.Literal['auto', 'override', 'disable'],
    version_override: typing.Optional[str],
    serialize: bool,
    ignored_inputs: typing.Union[typing.Tuple[str, ...], str],
    salt: str,
    policies: typing.Union[typing.List[flyte._cache.cache.CachePolicy], flyte._cache.cache.CachePolicy, NoneType],
)
```
| Parameter | Type | Description |
|-|-|-|
| `behavior` | `typing.Literal['auto', 'override', 'disable']` | Cache behavior — `"auto"`, `"override"`, or `"disable"`. |
| `version_override` | `typing.Optional[str]` | Explicit cache version string. Only used when `behavior="override"`. |
| `serialize` | `bool` | If `True`, concurrent executions with identical inputs will be serialized — only one runs and the rest wait for and reuse the cached result. Default `False`. |
| `ignored_inputs` | `typing.Union[typing.Tuple[str, ...], str]` | Input parameter names to exclude from the cache key. Useful when some inputs (e.g., timestamps) shouldn't affect caching. |
| `salt` | `str` | Additional salt for cache key generation. Use to create separate cache namespaces (e.g., `salt="v2"` to invalidate all existing caches). |
| `policies` | `typing.Union[typing.List[flyte._cache.cache.CachePolicy], flyte._cache.cache.CachePolicy, NoneType]` | Cache policies for version generation. Defaults to `[FunctionBodyPolicy()]` when `behavior="auto"`. Provide a custom `CachePolicy` implementation for alternative versioning strategies. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte > Cache > Methods > get_ignored_inputs()** |  |
| **Flyte SDK > Packages > flyte > Cache > Methods > get_version()** |  |
| **Flyte SDK > Packages > flyte > Cache > Methods > is_enabled()** | Check if the cache policy is enabled. |

### get_ignored_inputs()

```python
def get_ignored_inputs()
```
### get_version()

```python
def get_version(
    params: typing.Optional[flyte._cache.cache.VersionParameters],
) -> str
```
| Parameter | Type | Description |
|-|-|-|
| `params` | `typing.Optional[flyte._cache.cache.VersionParameters]` | |

### is_enabled()

```python
def is_enabled()
```
Check if the cache policy is enabled.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte/cachepolicy ===

# CachePolicy

**Package:** `flyte`

Protocol for custom cache version strategies.

Implement `get_version(salt, params) -&gt; str` to define how cache versions
are computed. The default implementation is `FunctionBodyPolicy`, which
hashes the function source code.

Example custom policy:

```python
class GitHashPolicy:
    def get_version(self, salt: str, params: VersionParameters) -> str:
        import subprocess
        git_hash = subprocess.check_output(["git", "rev-parse", "HEAD"]).decode().strip()
        return hashlib.sha256(f"{salt}{git_hash}".encode()).hexdigest()
```

```python
protocol CachePolicy()
```
## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte > CachePolicy > Methods > get_version()** |  |

### get_version()

```python
def get_version(
    salt: str,
    params: flyte._cache.cache.VersionParameters,
) -> str
```
| Parameter | Type | Description |
|-|-|-|
| `salt` | `str` | |
| `params` | `flyte._cache.cache.VersionParameters` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte/cron ===

# Cron

**Package:** `flyte`

Cron-based automation schedule for use with `Trigger`.

Cron expressions use the standard five-field format:
`minute hour day-of-month month day-of-week`

Common patterns:

- `"0 * * * *"` — every hour (at minute 0)
- `"0 0 * * *"` — daily at midnight
- `"0 0 * * 1"` — weekly on Monday at midnight
- `"0 0 1 * *"` — monthly on the 1st at midnight
- `"*/5 * * * *"` — every 5 minutes

```python
my_trigger = flyte.Trigger(
    name="my_cron_trigger",
    automation=flyte.Cron("0 * * * *"),  # Runs every hour
    description="A trigger that runs every hour",
)
```

## Parameters

```python
class Cron(
    expression: str,
    timezone: Timezone,
)
```
| Parameter | Type | Description |
|-|-|-|
| `expression` | `str` | Cron expression string (e.g., `"0 * * * *"`). |
| `timezone` | `Timezone` | Timezone for the cron schedule (default `"UTC"`). One of the standard timezone values (e.g., `"US/Eastern"`, `"Europe/London"`). Note that DST transitions may cause skipped or duplicated runs. |

## Properties

| Property | Type | Description |
|-|-|-|
| `timezone_expression` | `None` |  |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte/device ===

# Device

**Package:** `flyte`

Represents a device type, its quantity and partition if applicable.
param device: The type of device (e.g., "T4", "A100").
param quantity: The number of devices of this type.
param partition: The partition of the device (e.g., "1g.5gb", "2g.10gb" for gpus) or ("1x1", ... for tpus).

## Parameters

```python
class Device(
    quantity: int,
    device_class: typing.Literal['GPU', 'TPU', 'NEURON', 'AMD_GPU', 'HABANA_GAUDI'],
    device: str | None,
    partition: str | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `quantity` | `int` | |
| `device_class` | `typing.Literal['GPU', 'TPU', 'NEURON', 'AMD_GPU', 'HABANA_GAUDI']` | |
| `device` | `str \| None` | |
| `partition` | `str \| None` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte/environment ===

# Environment

**Package:** `flyte`

## Parameters

```python
class Environment(
    name: str,
    depends_on: List[Environment],
    pod_template: Optional[Union[str, PodTemplate]],
    description: Optional[str],
    secrets: Optional[SecretRequest],
    env_vars: Optional[Dict[str, str]],
    resources: Optional[Resources],
    interruptible: bool,
    image: Union[str, Image, Literal['auto'], None],
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | Name of the environment |
| `depends_on` | `List[Environment]` | Environment dependencies to hint, so when you deploy the environment, the dependencies are also deployed. This is useful when you have a set of environments that depend on each other. |
| `pod_template` | `Optional[Union[str, PodTemplate]]` | Pod template to use for the environment. |
| `description` | `Optional[str]` | Description of the environment. |
| `secrets` | `Optional[SecretRequest]` | Secrets to inject into the environment. |
| `env_vars` | `Optional[Dict[str, str]]` | Environment variables to set for the environment. |
| `resources` | `Optional[Resources]` | Resources to allocate for the environment. |
| `interruptible` | `bool` | Whether the environment is interruptible and can be scheduled on spot/preemptible instances |
| `image` | `Union[str, Image, Literal['auto'], None]` | Docker image to use for the environment. If set to "auto", will use the default image. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte > Environment > Methods > add_dependency()** | Add a dependency to the environment. |
| **Flyte SDK > Packages > flyte > Environment > Methods > clone_with()** |  |

### add_dependency()

```python
def add_dependency(
    env: Environment,
)
```
Add a dependency to the environment.

| Parameter | Type | Description |
|-|-|-|
| `env` | `Environment` | |

### clone_with()

```python
def clone_with(
    name: str,
    image: Optional[Union[str, Image, Literal['auto']]],
    resources: Optional[Resources],
    env_vars: Optional[Dict[str, str]],
    secrets: Optional[SecretRequest],
    depends_on: Optional[List[Environment]],
    description: Optional[str],
    kwargs: **kwargs,
) -> Environment
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |
| `image` | `Optional[Union[str, Image, Literal['auto']]]` | |
| `resources` | `Optional[Resources]` | |
| `env_vars` | `Optional[Dict[str, str]]` | |
| `secrets` | `Optional[SecretRequest]` | |
| `depends_on` | `Optional[List[Environment]]` | |
| `description` | `Optional[str]` | |
| `kwargs` | `**kwargs` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte/fixedrate ===

# FixedRate

**Package:** `flyte`

Fixed-rate (interval-based) automation schedule for use with `Trigger`.

Unlike `Cron`, which runs at specific clock times, `FixedRate` runs at a
consistent interval regardless of clock time.

```python
my_trigger = flyte.Trigger(
    name="my_fixed_rate_trigger",
    automation=flyte.FixedRate(60),  # Runs every 60 minutes
    description="A trigger that runs every hour",
)
```

## Parameters

```python
class FixedRate(
    interval_minutes: int,
    start_time: datetime | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `interval_minutes` | `int` | Interval between trigger activations, in minutes (e.g., `60` for hourly, `1440` for daily). |
| `start_time` | `datetime \| None` | Optional start time for the first trigger. Subsequent triggers follow the interval from this point. If not set, the first trigger occurs `interval_minutes` after deployment/activation. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte/image ===

# Image

**Package:** `flyte`

Container image specification built using a fluent, two-step pattern:

1. Create a base image with a `from_*` constructor
2. Customize with `with_*` methods (each returns a new `Image`)

```python
image = (
    flyte.Image.from_debian_base(python="3.12")
    .with_pip_packages("pandas", "scikit-learn")
    .with_apt_packages("curl", "git")
)
```

**Base constructors** (`from_*`):

- `from_debian_base()` — Debian-based image with a specified Python version
- `from_base()` — Any base image by name (e.g., `"python:3.12-slim"`)
- `from_uv_script()` — Image from a `uv`-compatible script with inline dependencies
- `from_dockerfile()` — Image from a custom Dockerfile
- `from_ref_name()` — Reference to a pre-built image by name

**Customization methods** (`with_*`):

- `with_pip_packages()` — Add pip packages
- `with_apt_packages()` — Add system packages via apt-get
- `with_commands()` — Run arbitrary shell commands
- `with_env_vars()` — Set environment variables
- `with_requirements()` — Install from a requirements.txt file
- `with_uv_project()` — Install from a uv/pyproject.toml project
- `with_poetry_project()` — Install from a Poetry project
- `with_source_folder()` — Include a source directory
- `with_source_file()` — Include a single source file
- `with_code_bundle()` — Include a code bundle
- `with_workdir()` — Set the working directory
- `with_dockerignore()` — Add a .dockerignore
- `with_local_v2()` — Configure for local v2 execution

## Parameters

```python
class Image(
    base_image: Optional[str],
    dockerfile: Optional[Path],
    registry: Optional[str],
    name: Optional[str],
    platform: Tuple[Architecture, ...],
    python_version: Tuple[int, int],
    extendable: bool,
    _is_flyte_default: bool,
    _ref_name: Optional[str],
    _layers: Tuple[Layer, ...],
    _image_registry_secret: Optional[Secret],
)
```
| Parameter | Type | Description |
|-|-|-|
| `base_image` | `Optional[str]` | |
| `dockerfile` | `Optional[Path]` | |
| `registry` | `Optional[str]` | |
| `name` | `Optional[str]` | |
| `platform` | `Tuple[Architecture, ...]` | |
| `python_version` | `Tuple[int, int]` | |
| `extendable` | `bool` | |
| `_is_flyte_default` | `bool` | |
| `_ref_name` | `Optional[str]` | |
| `_layers` | `Tuple[Layer, ...]` | |
| `_image_registry_secret` | `Optional[Secret]` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `uri` | `None` | Returns the URI of the image in the format &lt;registry&gt;/&lt;name&gt;:&lt;tag&gt; |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte > Image > Methods > clone()** | Use this method to clone the current image and change the registry and name. |
| **Flyte SDK > Packages > flyte > Image > Methods > from_base()** | Use this method to start with a pre-built base image. |
| **Flyte SDK > Packages > flyte > Image > Methods > from_debian_base()** | Use this method to start using the default base image, built from this library's base Dockerfile. |
| **Flyte SDK > Packages > flyte > Image > Methods > from_dockerfile()** | Use this method to create a new image with the specified dockerfile. |
| **Flyte SDK > Packages > flyte > Image > Methods > from_ref_name()** |  |
| **Flyte SDK > Packages > flyte > Image > Methods > from_uv_script()** | Use this method to create a new image with the specified uv script. |
| **Flyte SDK > Packages > flyte > Image > validate()** |  |
| **Flyte SDK > Packages > flyte > Image > with_apt_packages()** | Use this method to create a new image with the specified apt packages layered on top of the current image. |
| **Flyte SDK > Packages > flyte > Image > with_code_bundle()** | Configure this image to automatically copy source code from root_dir. |
| **Flyte SDK > Packages > flyte > Image > with_commands()** | Use this method to create a new image with the specified commands layered on top of the current image. |
| **Flyte SDK > Packages > flyte > Image > with_dockerignore()** |  |
| **Flyte SDK > Packages > flyte > Image > with_env_vars()** | Use this method to create a new image with the specified environment variables layered on top of. |
| **Flyte SDK > Packages > flyte > Image > with_local_v2()** | Use this method to create a new image with the local v2 builder. |
| **Flyte SDK > Packages > flyte > Image > with_local_v2_plugins()** | Use this method to create a new image with the local v2 builder. |
| **Flyte SDK > Packages > flyte > Image > with_pip_packages()** | Use this method to create a new image with the specified pip packages layered on top of the current image. |
| **Flyte SDK > Packages > flyte > Image > with_poetry_project()** | Use this method to create a new image with the specified pyproject. |
| **Flyte SDK > Packages > flyte > Image > with_requirements()** | Use this method to create a new image with the specified requirements file layered on top of the current image. |
| **Flyte SDK > Packages > flyte > Image > with_source_file()** | Use this method to create a new image with the specified local file(s) layered on top of the current image. |
| **Flyte SDK > Packages > flyte > Image > with_source_folder()** | Use this method to create a new image with the specified local directory layered on top of the current image. |
| **Flyte SDK > Packages > flyte > Image > with_uv_project()** | Use this method to create a new image with the specified uv. |
| **Flyte SDK > Packages > flyte > Image > with_workdir()** | Use this method to create a new image with the specified working directory. |

### clone()

```python
def clone(
    registry: Optional[str],
    registry_secret: Optional[str | Secret],
    name: Optional[str],
    base_image: Optional[str],
    python_version: Optional[Tuple[int, int]],
    addl_layer: Optional[Layer],
    extendable: Optional[bool],
) -> Image
```
Use this method to clone the current image and change the registry and name

| Parameter | Type | Description |
|-|-|-|
| `registry` | `Optional[str]` | Registry to use for the image |
| `registry_secret` | `Optional[str \| Secret]` | Secret to use to pull/push the private image. |
| `name` | `Optional[str]` | Name of the image |
| `base_image` | `Optional[str]` | Base image to use for the image |
| `python_version` | `Optional[Tuple[int, int]]` | Python version for the image, if not specified, will use the current Python version |
| `addl_layer` | `Optional[Layer]` | Additional layer to add to the image. This will be added to the end of the layers. |
| `extendable` | `Optional[bool]` | Whether the image is extendable by other images. If True, the image can be used as a base image for other images, and additional layers can be added on top of it. If False, the image cannot be used as a base image for other images, and additional layers cannot be added on top of it. If None (default), defaults to False for safety. |

### from_base()

```python
def from_base(
    image_uri: str,
) -> Image
```
Use this method to start with a pre-built base image. This image must already exist in the registry of course.

| Parameter | Type | Description |
|-|-|-|
| `image_uri` | `str` | The full URI of the image, in the format &lt;registry&gt;/&lt;name&gt; |

### from_debian_base()

```python
def from_debian_base(
    python_version: Optional[Tuple[int, int]],
    flyte_version: Optional[str],
    install_flyte: bool,
    registry: Optional[str],
    registry_secret: Optional[str | Secret],
    name: Optional[str],
    platform: Optional[Tuple[Architecture, ...]],
) -> Image
```
Use this method to start using the default base image, built from this library's base Dockerfile
Default images are multi-arch amd/arm64

| Parameter | Type | Description |
|-|-|-|
| `python_version` | `Optional[Tuple[int, int]]` | If not specified, will use the current Python version |
| `flyte_version` | `Optional[str]` | Flyte version to use |
| `install_flyte` | `bool` | If True, will install the flyte library in the image |
| `registry` | `Optional[str]` | Registry to use for the image |
| `registry_secret` | `Optional[str \| Secret]` | Secret to use to pull/push the private image. |
| `name` | `Optional[str]` | Name of the image if you want to override the default name |
| `platform` | `Optional[Tuple[Architecture, ...]]` | Platform to use for the image, default is linux/amd64, use tuple for multiple values Example: ("linux/amd64", "linux/arm64") |

**Returns:** Image

### from_dockerfile()

```python
def from_dockerfile(
    file: Path,
    registry: str,
    name: str,
    platform: Union[Architecture, Tuple[Architecture, ...], None],
) -> Image
```
Use this method to create a new image with the specified dockerfile. Note you cannot use additional layers
after this, as the system doesn't attempt to parse/understand the Dockerfile, and what kind of setup it has
(python version, uv vs poetry, etc), so please put all logic into the dockerfile itself.

Also since Python sees paths as from the calling directory, please use Path objects with absolute paths. The
context for the builder will be the directory where the dockerfile is located.

| Parameter | Type | Description |
|-|-|-|
| `file` | `Path` | path to the dockerfile |
| `registry` | `str` | registry to use for the image |
| `name` | `str` | name of the image |
| `platform` | `Union[Architecture, Tuple[Architecture, ...], None]` | architecture to use for the image, default is linux/amd64, use tuple for multiple values Example: ("linux/amd64", "linux/arm64") |

### from_ref_name()

```python
def from_ref_name(
    name: str,
) -> Image
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |

### from_uv_script()

```python
def from_uv_script(
    script: Path | str,
    name: str,
    registry: str | None,
    registry_secret: Optional[str | Secret],
    python_version: Optional[Tuple[int, int]],
    index_url: Optional[str],
    extra_index_urls: Union[str, List[str], Tuple[str, ...], None],
    pre: bool,
    extra_args: Optional[str],
    platform: Optional[Tuple[Architecture, ...]],
    secret_mounts: Optional[SecretRequest],
) -> Image
```
Use this method to create a new image with the specified uv script.
It uses the header of the script to determine the python version, dependencies to install.
The script must be a valid uv script, otherwise an error will be raised.

Usually the header of the script will look like this:
```python
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = ["httpx"]
# ///
```

For more information on the uv script format, see the documentation:
[UV: Declaring script dependencies](https://docs.astral.sh/uv/guides/scripts/#declaring-script-dependencies)

| Parameter | Type | Description |
|-|-|-|
| `script` | `Path \| str` | path to the uv script |
| `name` | `str` | name of the image |
| `registry` | `str \| None` | registry to use for the image |
| `registry_secret` | `Optional[str \| Secret]` | Secret to use to pull/push the private image. |
| `python_version` | `Optional[Tuple[int, int]]` | Python version for the image, if not specified, will use the current Python version |
| `index_url` | `Optional[str]` | index url to use for pip install, default is None |
| `extra_index_urls` | `Union[str, List[str], Tuple[str, ...], None]` | extra index urls to use for pip install, default is True |
| `pre` | `bool` | whether to allow pre-release versions, default is False |
| `extra_args` | `Optional[str]` | extra arguments to pass to pip install, default is None |
| `platform` | `Optional[Tuple[Architecture, ...]]` | architecture to use for the image, default is linux/amd64, use tuple for multiple values |
| `secret_mounts` | `Optional[SecretRequest]` | |

**Returns:** Image

### validate()

```python
def validate()
```
### with_apt_packages()

```python
def with_apt_packages(
    packages: str,
    secret_mounts: Optional[SecretRequest],
) -> Image
```
Use this method to create a new image with the specified apt packages layered on top of the current image

| Parameter | Type | Description |
|-|-|-|
| `packages` | `str` | list of apt packages to install |
| `secret_mounts` | `Optional[SecretRequest]` | list of secret mounts to use for the build process. |

**Returns:** Image

### with_code_bundle()

```python
def with_code_bundle(
    copy_style: Literal['loaded_modules', 'all'],
    dst: str,
) -> Image
```
Configure this image to automatically copy source code from root_dir
when the runner's copy_style is "none".

When the runner's copy_style is not "none", this is a no-op.

| Parameter | Type | Description |
|-|-|-|
| `copy_style` | `Literal['loaded_modules', 'all']` | Which files to copy into the image. "loaded_modules" copies only imported Python modules. "all" copies all files from root_dir. |
| `dst` | `str` | Destination directory in the container. Defaults to working dir. |

**Returns:** Image

### with_commands()

```python
def with_commands(
    commands: List[str],
    secret_mounts: Optional[SecretRequest],
) -> Image
```
Use this method to create a new image with the specified commands layered on top of the current image
Be sure not to use RUN in your command.

| Parameter | Type | Description |
|-|-|-|
| `commands` | `List[str]` | list of commands to run |
| `secret_mounts` | `Optional[SecretRequest]` | list of secret mounts to use for the build process. |

**Returns:** Image

### with_dockerignore()

```python
def with_dockerignore(
    path: Path,
) -> Image
```
| Parameter | Type | Description |
|-|-|-|
| `path` | `Path` | |

### with_env_vars()

```python
def with_env_vars(
    env_vars: Dict[str, str],
) -> Image
```
Use this method to create a new image with the specified environment variables layered on top of
the current image. Cannot be used in conjunction with conda

| Parameter | Type | Description |
|-|-|-|
| `env_vars` | `Dict[str, str]` | dictionary of environment variables to set |

**Returns:** Image

### with_local_v2()

```python
def with_local_v2()
```
Use this method to create a new image with the local v2 builder
This will override any existing builder

**Returns:** Image

### with_local_v2_plugins()

```python
def with_local_v2_plugins(
    plugins: str | list[str] | None,
) -> Image
```
Use this method to create a new image with the local v2 builder
This will override any existing builder

| Parameter | Type | Description |
|-|-|-|
| `plugins` | `str \| list[str] \| None` | plugin name or list of plugin names to install, default is None, e.g. flyteplugins-hitl, flyteplugins-vllm, flyteplugins-sglang, etc. |

**Returns:** Image

### with_pip_packages()

```python
def with_pip_packages(
    packages: str,
    index_url: Optional[str],
    extra_index_urls: Union[str, List[str], Tuple[str, ...], None],
    pre: bool,
    extra_args: Optional[str],
    secret_mounts: Optional[SecretRequest],
) -> Image
```
Use this method to create a new image with the specified pip packages layered on top of the current image
Cannot be used in conjunction with conda

```python
@flyte.task(image=(flyte.Image.from_debian_base().with_pip_packages("requests", "numpy")))
def my_task(x: int) -> int:
    import numpy as np
    return np.sum([x, 1])
```

To mount secrets during the build process to download private packages, you can use the `secret_mounts`.
In the below example, "GITHUB_PAT" will be mounted as env var "GITHUB_PAT",
 and "apt-secret" will be mounted at /etc/apt/apt-secret.
```python
private_package = "git+https://$GITHUB_PAT@github.com/flyteorg/flytex.git@2e20a2acebfc3877d84af643fdd768edea41d533"
@flyte.task(
    image=(
        flyte.Image.from_debian_base()
        .with_pip_packages("private_package", secret_mounts=[Secret(key="GITHUB_PAT")])
        .with_apt_packages("git", secret_mounts=[Secret(key="apt-secret", mount="/etc/apt/apt-secret")])
)
def my_task(x: int) -> int:
    import numpy as np
    return np.sum([x, 1])
```

| Parameter | Type | Description |
|-|-|-|
| `packages` | `str` | list of pip packages to install, follows pip install syntax |
| `index_url` | `Optional[str]` | index url to use for pip install, default is None |
| `extra_index_urls` | `Union[str, List[str], Tuple[str, ...], None]` | extra index urls to use for pip install, default is None |
| `pre` | `bool` | whether to allow pre-release versions, default is False |
| `extra_args` | `Optional[str]` | extra arguments to pass to pip install, default is None |
| `secret_mounts` | `Optional[SecretRequest]` | list of secret to mount for the build process. |

**Returns:** Image

### with_poetry_project()

```python
def with_poetry_project(
    pyproject_file: str | Path,
    poetry_lock: Path | None,
    extra_args: Optional[str],
    secret_mounts: Optional[SecretRequest],
    project_install_mode: typing.Literal['dependencies_only', 'install_project'],
)
```
Use this method to create a new image with the specified pyproject.toml layered on top of the current image.
Must have a corresponding pyproject.toml file in the same directory.
Cannot be used in conjunction with conda.

By default, this method copies the entire project into the image,
including files such as pyproject.toml, poetry.lock, and the src/ directory.

If you prefer not to install the current project, you can pass through `extra_args`
`--no-root`. In this case, the image builder will only copy pyproject.toml and poetry.lock
into the image.

| Parameter | Type | Description |
|-|-|-|
| `pyproject_file` | `str \| Path` | Path to the pyproject.toml file. A poetry.lock file must exist in the same directory unless `poetry_lock` is explicitly provided. |
| `poetry_lock` | `Path \| None` | Path to the poetry.lock file. If not specified, the default is the file named 'poetry.lock' in the same directory as `pyproject_file` (pyproject.parent / "poetry.lock"). |
| `extra_args` | `Optional[str]` | Extra arguments to pass through to the package installer/resolver, default is None. |
| `secret_mounts` | `Optional[SecretRequest]` | Secrets to make available during dependency resolution/build (e.g., private indexes). |
| `project_install_mode` | `typing.Literal['dependencies_only', 'install_project']` | whether to install the project as a package or only dependencies, default is "dependencies_only" |

**Returns:** Image

### with_requirements()

```python
def with_requirements(
    file: str | Path,
    index_url: Optional[str],
    extra_index_urls: Union[str, List[str], Tuple[str, ...], None],
    pre: bool,
    extra_args: Optional[str],
    secret_mounts: Optional[SecretRequest],
) -> Image
```
Use this method to create a new image with the specified requirements file layered on top of the current image
Cannot be used in conjunction with conda

| Parameter | Type | Description |
|-|-|-|
| `file` | `str \| Path` | path to the requirements file, must be a .txt file |
| `index_url` | `Optional[str]` | index url to use for pip install, default is None |
| `extra_index_urls` | `Union[str, List[str], Tuple[str, ...], None]` | extra index urls to use for pip install, default is None |
| `pre` | `bool` | if True, install pre-release packages, default is False |
| `extra_args` | `Optional[str]` | extra arguments to pass to pip install, default is None |
| `secret_mounts` | `Optional[SecretRequest]` | list of secret to mount for the build process. |

### with_source_file()

```python
def with_source_file(
    src: typing.Union[Path, typing.List[Path]],
    dst: str,
) -> Image
```
Use this method to create a new image with the specified local file(s) layered on top of the current image.
If dest is not specified, it will be copied to the working directory of the image

| Parameter | Type | Description |
|-|-|-|
| `src` | `typing.Union[Path, typing.List[Path]]` | file or list of files from the build context to be copied |
| `dst` | `str` | destination folder in the image |

**Returns:** Image

### with_source_folder()

```python
def with_source_folder(
    src: Path,
    dst: str,
    copy_contents_only: bool,
) -> Image
```
Use this method to create a new image with the specified local directory layered on top of the current image.
If dest is not specified, it will be copied to the working directory of the image

| Parameter | Type | Description |
|-|-|-|
| `src` | `Path` | root folder of the source code from the build context to be copied |
| `dst` | `str` | destination folder in the image |
| `copy_contents_only` | `bool` | If True, will copy the contents of the source folder to the destination folder, instead of the folder itself. Default is False. |

**Returns:** Image

### with_uv_project()

```python
def with_uv_project(
    pyproject_file: str | Path,
    uvlock: Path | None,
    index_url: Optional[str],
    extra_index_urls: Union[List[str], Tuple[str, ...], None],
    pre: bool,
    extra_args: Optional[str],
    secret_mounts: Optional[SecretRequest],
    project_install_mode: typing.Literal['dependencies_only', 'install_project'],
) -> Image
```
Use this method to create a new image with the specified uv.lock file layered on top of the current image
Must have a corresponding pyproject.toml file in the same directory
Cannot be used in conjunction with conda

By default, this method copies the pyproject.toml and uv.lock files into the image.

If `project_install_mode` is "install_project", it will also copy directory
 where the pyproject.toml file is located into the image.

| Parameter | Type | Description |
|-|-|-|
| `pyproject_file` | `str \| Path` | path to the pyproject.toml file |
| `uvlock` | `Path \| None` | path to the uv.lock file, if not specified, will use the default uv.lock file in the same directory as the pyproject.toml file if it exists. (pyproject.parent / uv.lock) |
| `index_url` | `Optional[str]` | index url to use for pip install, default is None |
| `extra_index_urls` | `Union[List[str], Tuple[str, ...], None]` | extra index urls to use for pip install, default is None |
| `pre` | `bool` | whether to allow pre-release versions, default is False |
| `extra_args` | `Optional[str]` | extra arguments to pass to pip install, default is None |
| `secret_mounts` | `Optional[SecretRequest]` | list of secret mounts to use for the build process. |
| `project_install_mode` | `typing.Literal['dependencies_only', 'install_project']` | whether to install the project as a package or only dependencies, default is "dependencies_only" |

**Returns:** Image

### with_workdir()

```python
def with_workdir(
    workdir: str,
) -> Image
```
Use this method to create a new image with the specified working directory
This will override any existing working directory

| Parameter | Type | Description |
|-|-|-|
| `workdir` | `str` | working directory to use |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte/imagebuild ===

# ImageBuild

**Package:** `flyte`

Result of an image build operation.

## Parameters

```python
class ImageBuild(
    uri: str | None,
    remote_run: Optional['remote.Run'],
)
```
| Parameter | Type | Description |
|-|-|-|
| `uri` | `str \| None` | The fully qualified image URI. None if the build was started asynchronously and hasn't completed yet. |
| `remote_run` | `Optional['remote.Run']` | The Run object that kicked off an image build job when using the remote builder. None when using the local builder. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte/link ===

# Link

**Package:** `flyte`

```python
protocol Link()
```
## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte > Link > Methods > get_link()** | Returns a task log link given the action. |

### get_link()

```python
def get_link(
    run_name: str,
    project: str,
    domain: str,
    context: typing.Dict[str, str],
    parent_action_name: str,
    action_name: str,
    pod_name: str,
    kwargs,
) -> str
```
Returns a task log link given the action.
Link can have template variables that are replaced by the backend.

| Parameter | Type | Description |
|-|-|-|
| `run_name` | `str` | The name of the run. |
| `project` | `str` | The project name. |
| `domain` | `str` | The domain name. |
| `context` | `typing.Dict[str, str]` | Additional context for generating the link. |
| `parent_action_name` | `str` | The name of the parent action. |
| `action_name` | `str` | The name of the action. |
| `pod_name` | `str` | The name of the pod. |
| `kwargs` | `**kwargs` | Additional keyword arguments. |

**Returns:** The generated link.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte/podtemplate ===

# PodTemplate

**Package:** `flyte`

Custom PodTemplate specification for a Task.

## Parameters

```python
class PodTemplate(
    pod_spec: typing.Optional[ForwardRef('V1PodSpec')],
    primary_container_name: str,
    labels: typing.Optional[typing.Dict[str, str]],
    annotations: typing.Optional[typing.Dict[str, str]],
)
```
| Parameter | Type | Description |
|-|-|-|
| `pod_spec` | `typing.Optional[ForwardRef('V1PodSpec')]` | |
| `primary_container_name` | `str` | |
| `labels` | `typing.Optional[typing.Dict[str, str]]` | |
| `annotations` | `typing.Optional[typing.Dict[str, str]]` | |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte > PodTemplate > Methods > to_k8s_pod()** |  |

### to_k8s_pod()

```python
def to_k8s_pod()
```


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte/resources ===

# Resources

**Package:** `flyte`

Resources such as CPU, Memory, and GPU that can be allocated to a task.

Set via `TaskEnvironment(resources=...)` or `task.override(resources=...)`.

```python
# Simple: 1 CPU, 1 GiB memory, 1 T4 GPU
Resources(cpu=1, memory="1Gi", gpu="T4:1")

# Range: request 1 CPU (limit 2), 2 GiB memory, 8 A100 GPUs, 10 GiB disk
Resources(cpu=(1, 2), memory="2Gi", gpu="A100:8", disk="10Gi")

# Advanced GPU with partitioning
Resources(gpu=GPU(device="A100", quantity=1, partition="1g.5gb"))

# TPU
Resources(gpu=TPU(device="V5P", partition="2x2x1"))
```

## Parameters

```python
class Resources(
    cpu: typing.Union[int, float, str, typing.Tuple[int | float | str, int | float | str], NoneType],
    memory: typing.Union[str, typing.Tuple[str, str], NoneType],
    gpu: typing.Union[typing.Literal['A10:1', 'A10:2', 'A10:3', 'A10:4', 'A10:5', 'A10:6', 'A10:7', 'A10:8', 'A10G:1', 'A10G:2', 'A10G:3', 'A10G:4', 'A10G:5', 'A10G:6', 'A10G:7', 'A10G:8', 'A100:1', 'A100:2', 'A100:3', 'A100:4', 'A100:5', 'A100:6', 'A100:7', 'A100:8', 'A100 80G:1', 'A100 80G:2', 'A100 80G:3', 'A100 80G:4', 'A100 80G:5', 'A100 80G:6', 'A100 80G:7', 'A100 80G:8', 'B200:1', 'B200:2', 'B200:3', 'B200:4', 'B200:5', 'B200:6', 'B200:7', 'B200:8', 'H100:1', 'H100:2', 'H100:3', 'H100:4', 'H100:5', 'H100:6', 'H100:7', 'H100:8', 'H200:1', 'H200:2', 'H200:3', 'H200:4', 'H200:5', 'H200:6', 'H200:7', 'H200:8', 'L4:1', 'L4:2', 'L4:3', 'L4:4', 'L4:5', 'L4:6', 'L4:7', 'L4:8', 'L40s:1', 'L40s:2', 'L40s:3', 'L40s:4', 'L40s:5', 'L40s:6', 'L40s:7', 'L40s:8', 'V100:1', 'V100:2', 'V100:3', 'V100:4', 'V100:5', 'V100:6', 'V100:7', 'V100:8', 'RTX PRO 6000:1', 'GB10:1', 'T4:1', 'T4:2', 'T4:3', 'T4:4', 'T4:5', 'T4:6', 'T4:7', 'T4:8', 'Trn1:1', 'Trn1:4', 'Trn1:8', 'Trn1:16', 'Trn1n:1', 'Trn1n:4', 'Trn1n:8', 'Trn1n:16', 'Trn2:1', 'Trn2:4', 'Trn2:8', 'Trn2:16', 'Trn2u:1', 'Trn2u:4', 'Trn2u:8', 'Trn2u:16', 'Inf1:1', 'Inf1:2', 'Inf1:3', 'Inf1:4', 'Inf1:5', 'Inf1:6', 'Inf1:7', 'Inf1:8', 'Inf1:9', 'Inf1:10', 'Inf1:11', 'Inf1:12', 'Inf1:13', 'Inf1:14', 'Inf1:15', 'Inf1:16', 'Inf2:1', 'Inf2:2', 'Inf2:3', 'Inf2:4', 'Inf2:5', 'Inf2:6', 'Inf2:7', 'Inf2:8', 'Inf2:9', 'Inf2:10', 'Inf2:11', 'Inf2:12', 'MI100:1', 'MI210:1', 'MI250:1', 'MI250X:1', 'MI300A:1', 'MI300X:1', 'MI325X:1', 'MI350X:1', 'MI355X:1', 'Gaudi1:1'], int, flyte._resources.Device, NoneType],
    disk: typing.Optional[str],
    shm: typing.Union[str, typing.Literal['auto'], NoneType],
)
```
| Parameter | Type | Description |
|-|-|-|
| `cpu` | `typing.Union[int, float, str, typing.Tuple[int \| float \| str, int \| float \| str], NoneType]` | CPU allocation. Accepts several formats  - `int` or `float`: CPU cores (e.g., `1`, `0.5`) - `str`: Kubernetes-style (e.g., `"500m"` for 0.5 cores, `"2"` for 2 cores) - `tuple`: Request/limit range (e.g., `(1, 4)` requests 1 core, limits to 4) |
| `memory` | `typing.Union[str, typing.Tuple[str, str], NoneType]` | Memory allocation using Kubernetes unit conventions  - Binary units: `"512Mi"`, `"1Gi"`, `"4Gi"` - Decimal units: `"500M"`, `"1G"` - `tuple`: Request/limit range (e.g., `("1Gi", "4Gi")`) |
| `gpu` | `typing.Union[typing.Literal['A10:1', 'A10:2', 'A10:3', 'A10:4', 'A10:5', 'A10:6', 'A10:7', 'A10:8', 'A10G:1', 'A10G:2', 'A10G:3', 'A10G:4', 'A10G:5', 'A10G:6', 'A10G:7', 'A10G:8', 'A100:1', 'A100:2', 'A100:3', 'A100:4', 'A100:5', 'A100:6', 'A100:7', 'A100:8', 'A100 80G:1', 'A100 80G:2', 'A100 80G:3', 'A100 80G:4', 'A100 80G:5', 'A100 80G:6', 'A100 80G:7', 'A100 80G:8', 'B200:1', 'B200:2', 'B200:3', 'B200:4', 'B200:5', 'B200:6', 'B200:7', 'B200:8', 'H100:1', 'H100:2', 'H100:3', 'H100:4', 'H100:5', 'H100:6', 'H100:7', 'H100:8', 'H200:1', 'H200:2', 'H200:3', 'H200:4', 'H200:5', 'H200:6', 'H200:7', 'H200:8', 'L4:1', 'L4:2', 'L4:3', 'L4:4', 'L4:5', 'L4:6', 'L4:7', 'L4:8', 'L40s:1', 'L40s:2', 'L40s:3', 'L40s:4', 'L40s:5', 'L40s:6', 'L40s:7', 'L40s:8', 'V100:1', 'V100:2', 'V100:3', 'V100:4', 'V100:5', 'V100:6', 'V100:7', 'V100:8', 'RTX PRO 6000:1', 'GB10:1', 'T4:1', 'T4:2', 'T4:3', 'T4:4', 'T4:5', 'T4:6', 'T4:7', 'T4:8', 'Trn1:1', 'Trn1:4', 'Trn1:8', 'Trn1:16', 'Trn1n:1', 'Trn1n:4', 'Trn1n:8', 'Trn1n:16', 'Trn2:1', 'Trn2:4', 'Trn2:8', 'Trn2:16', 'Trn2u:1', 'Trn2u:4', 'Trn2u:8', 'Trn2u:16', 'Inf1:1', 'Inf1:2', 'Inf1:3', 'Inf1:4', 'Inf1:5', 'Inf1:6', 'Inf1:7', 'Inf1:8', 'Inf1:9', 'Inf1:10', 'Inf1:11', 'Inf1:12', 'Inf1:13', 'Inf1:14', 'Inf1:15', 'Inf1:16', 'Inf2:1', 'Inf2:2', 'Inf2:3', 'Inf2:4', 'Inf2:5', 'Inf2:6', 'Inf2:7', 'Inf2:8', 'Inf2:9', 'Inf2:10', 'Inf2:11', 'Inf2:12', 'MI100:1', 'MI210:1', 'MI250:1', 'MI250X:1', 'MI300A:1', 'MI300X:1', 'MI325X:1', 'MI350X:1', 'MI355X:1', 'Gaudi1:1'], int, flyte._resources.Device, NoneType]` | GPU, TPU, or other accelerator allocation. Accepts  - `int`: GPU count, any available type (e.g., `1`, `4`) - `str`: Type and quantity (e.g., `"T4:1"`, `"A100:2"`, `"H100:8"`) - `Device`: Advanced config via `GPU()`, `TPU()`, or `Device()` for partitioning and custom device types. See `GPU`, `TPU`, `Device` for details.  Supported GPU types include T4, L4, L40s, A10, A10G, A100, A100 80G, B200, H100, H200, V100. GPU partitioning (MIG) is available on A100, A100 80G, H100, and H200. |
| `disk` | `typing.Optional[str]` | Ephemeral disk storage as a string with Kubernetes units (e.g., `"10Gi"`, `"100Gi"`, `"1Ti"`). Automatically cleaned up when the task completes. |
| `shm` | `typing.Union[str, typing.Literal['auto'], NoneType]` | Shared memory (`/dev/shm`) allocation. Useful for ML data loading and inter-process communication:  - `str`: Size with units (e.g., `"1Gi"`, `"16Gi"`) - `"auto"`: Set to the maximum shared memory available on the node |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte > Resources > Methods > get_device()** | Get the accelerator string for the task. |
| **Flyte SDK > Packages > flyte > Resources > Methods > get_shared_memory()** | Get the shared memory string for the task. |

### get_device()

```python
def get_device()
```
Get the accelerator string for the task.

         Default cloud provider labels typically use the following values: `1g.5gb`, `2g.10gb`, etc.

**Returns:** If GPUs are requested, return a tuple of the device name, and potentially a partition string.

### get_shared_memory()

```python
def get_shared_memory()
```
Get the shared memory string for the task.

**Returns:** The shared memory string.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte/retrystrategy ===

# RetryStrategy

**Package:** `flyte`

Retry strategy for the task or task environment. Retry strategy is optional or can be a simple number of retries.

- This will retry the task 5 times.
```
@task(retries=5)
def my_task():
    pass
```
- This will retry the task 5 times with a maximum backoff of 10 seconds and a backoff factor of 2.
```
@task(retries=RetryStrategy(count=5))
def my_task():
    pass
```

## Parameters

```python
class RetryStrategy(
    count: int,
)
```
| Parameter | Type | Description |
|-|-|-|
| `count` | `int` | The number of retries. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte/reusepolicy ===

# ReusePolicy

**Package:** `flyte`

Configure a task environment for container reuse across multiple task invocations.

When environment creation is expensive relative to task runtime, reusable containers
keep a pool of warm containers ready, avoiding cold-start overhead. The Python process
may be reused by subsequent task invocations.

Total concurrent capacity is `max_replicas * concurrency`. For example,
`ReusePolicy(replicas=(1, 3), concurrency=2)` supports up to 6 concurrent tasks.

Caution: The environment is shared across invocations — manage memory and resources carefully.

```python
env = flyte.TaskEnvironment(
    name="fast_env",
    reusable=flyte.ReusePolicy(replicas=(1, 3), concurrency=2),
)
```

## Parameters

```python
class ReusePolicy(
    replicas: typing.Union[int, typing.Tuple[int, int]],
    idle_ttl: typing.Union[int, datetime.timedelta],
    concurrency: int,
    scaledown_ttl: typing.Union[int, datetime.timedelta],
)
```
| Parameter | Type | Description |
|-|-|-|
| `replicas` | `typing.Union[int, typing.Tuple[int, int]]` | Number of container replicas to maintain.  - `int`: Fixed replica count, always running (e.g., `replicas=3`). - `tuple(min, max)`: Auto-scaling range (e.g., `replicas=(1, 5)`). Scales between min and max based on demand.  Default is `2`. A minimum of 2 replicas is recommended to avoid starvation when the parent task occupies one replica. |
| `idle_ttl` | `typing.Union[int, datetime.timedelta]` | Environment-level idle timeout — shuts down **all** replicas when the entire environment has been idle for this duration. Specified as seconds (`int`) or `timedelta`. Minimum 30 seconds. Default is 30 seconds. |
| `concurrency` | `int` | Maximum concurrent tasks per replica. Values greater than 1 are only supported for `async` tasks. Default is `1`. |
| `scaledown_ttl` | `typing.Union[int, datetime.timedelta]` | Per-replica scale-down delay — minimum time to wait before removing an **individual** idle replica. Prevents rapid scale-down when tasks arrive in bursts. Specified as seconds (`int`) or `timedelta`. Default is 30 seconds.  Note the distinction: `idle_ttl` controls when the whole environment shuts down; `scaledown_ttl` controls when individual replicas are removed during auto-scaling. |

## Properties

| Property | Type | Description |
|-|-|-|
| `max_replicas` | `None` | Returns the maximum number of replicas. |
| `min_replicas` | `None` | Returns the minimum number of replicas. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte > ReusePolicy > Methods > get_scaledown_ttl()** | Returns the scaledown TTL as a timedelta. |

### get_scaledown_ttl()

```python
def get_scaledown_ttl()
```
Returns the scaledown TTL as a timedelta. If scaledown_ttl is not set, returns None.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte/secret ===

# Secret

**Package:** `flyte`

Secrets are used to inject sensitive information into tasks or image build context.
Secrets can be mounted as environment variables or files.
 The secret key is the name of the secret in the secret store. The group is optional and maybe used with some
secret stores to organize secrets. The as_env_var is an optional parameter that can be used to specify the
name of the environment variable that the secret should be mounted as.

```python
@task(secrets="my-secret")
async def my_task():
    # This will be set to the value of the secret. Note: The env var is always uppercase, and - is replaced with _.
    os.environ["MY_SECRET"]

@task(secrets=Secret("my-openai-api-key", as_env_var="OPENAI_API_KEY"))
async def my_task2():
    os.environ["OPENAI_API_KEY"]
```

TODO: Add support for secret versioning (some stores) and secret groups (some stores) and mounting as files.

## Parameters

```python
class Secret(
    key: str,
    group: typing.Optional[str],
    mount: pathlib.Path | None,
    as_env_var: typing.Optional[str],
)
```
| Parameter | Type | Description |
|-|-|-|
| `key` | `str` | The name of the secret in the secret store. |
| `group` | `typing.Optional[str]` | The group of the secret in the secret store. |
| `mount` | `pathlib.Path \| None` | For now, the only supported mount path is "/etc/flyte/secrets". TODO: support arbitrary mount paths. Today only "/etc/flyte/secrets" is supported |
| `as_env_var` | `typing.Optional[str]` | The name of the environment variable that the secret should be mounted as. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte > Secret > Methods > stable_hash()** | Deterministic, process-independent hash (as hex string). |

### stable_hash()

```python
def stable_hash()
```
Deterministic, process-independent hash (as hex string).


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte/taskenvironment ===

# TaskEnvironment

**Package:** `flyte`

Define an execution environment for a set of tasks.

Task configuration in Flyte has three levels (most general to most specific):

1. **TaskEnvironment** — sets defaults for all tasks in the environment
2. **@env.task decorator** — overrides per-task settings
3. **task.override()** — overrides at invocation time

For shared parameters, the more specific level overrides the more general one.

```python
env = flyte.TaskEnvironment(
    name="my_env",
    image=flyte.Image.from_debian_base(python="3.12").with_pip_packages("pandas"),
    resources=flyte.Resources(cpu="1", memory="1Gi"),
)

@env.task
async def my_task():
    pass
```

## Parameters

```python
class TaskEnvironment(
    name: str,
    depends_on: List[Environment],
    pod_template: Optional[Union[str, PodTemplate]],
    description: Optional[str],
    secrets: Optional[SecretRequest],
    env_vars: Optional[Dict[str, str]],
    resources: Optional[Resources],
    interruptible: bool,
    image: Union[str, Image, Literal['auto'], None],
    cache: CacheRequest,
    reusable: ReusePolicy | None,
    plugin_config: Optional[Any],
    queue: Optional[str],
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | Name of the environment (required). Must be snake_case or kebab-case. TaskEnvironment level only. |
| `depends_on` | `List[Environment]` | List of other environments this one depends on. Used at deploy time to ensure dependencies are also deployed. TaskEnvironment level only. |
| `pod_template` | `Optional[Union[str, PodTemplate]]` | Kubernetes pod template for advanced configuration (sidecars, volumes, etc.). Also settable in `@env.task` and `task.override`. |
| `description` | `Optional[str]` | Human-readable description (max 255 characters). TaskEnvironment level only. |
| `secrets` | `Optional[SecretRequest]` | Secrets to inject. Overridable via `task.override(secrets=...)` when not using reusable containers. |
| `env_vars` | `Optional[Dict[str, str]]` | Environment variables as `dict[str, str]`. Overridable via `task.override(env_vars=...)` when not using reusable containers. |
| `resources` | `Optional[Resources]` | Compute resources (CPU, memory, GPU, disk). Overridable via `task.override(resources=...)` when not using reusable containers. |
| `interruptible` | `bool` | Whether tasks can run on spot/preemptible instances. Also settable in `@env.task` and `task.override`. |
| `image` | `Union[str, Image, Literal['auto'], None]` | Docker image for the environment. Can be a string (image URI), an `Image` object, or `"auto"` to use the default image. TaskEnvironment level only. |
| `cache` | `CacheRequest` | Cache policy — `"auto"`, `"override"`, `"disable"`, or a `Cache` object. Also settable in `@env.task(cache=...)` and `task.override(cache=...)`. |
| `reusable` | `ReusePolicy \| None` | `ReusePolicy` for container reuse. Also overridable via `task.override(reusable=...)`. |
| `plugin_config` | `Optional[Any]` | Plugin configuration for custom task types (e.g., Ray, Spark). Cannot be combined with `reusable`. TaskEnvironment level only. |
| `queue` | `Optional[str]` | Queue name for scheduling. Also settable in `@env.task` and `task.override`. |

## Properties

| Property | Type | Description |
|-|-|-|
| `sandbox` | `None` | Access the sandbox namespace for creating sandboxed tasks. |
| `tasks` | `None` | Get all tasks defined in the environment. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte > TaskEnvironment > Methods > add_dependency()** | Add a dependency to the environment. |
| **Flyte SDK > Packages > flyte > TaskEnvironment > Methods > clone_with()** | Clone the TaskEnvironment with new parameters. |
| **Flyte SDK > Packages > flyte > TaskEnvironment > Methods > from_task()** | Create a TaskEnvironment from a list of tasks. |
| **Flyte SDK > Packages > flyte > TaskEnvironment > Methods > task()** | Decorate a function to be a task. |

### add_dependency()

```python
def add_dependency(
    env: Environment,
)
```
Add a dependency to the environment.

| Parameter | Type | Description |
|-|-|-|
| `env` | `Environment` | |

### clone_with()

```python
def clone_with(
    name: str,
    image: Optional[Union[str, Image, Literal['auto']]],
    resources: Optional[Resources],
    env_vars: Optional[Dict[str, str]],
    secrets: Optional[SecretRequest],
    depends_on: Optional[List[Environment]],
    description: Optional[str],
    interruptible: Optional[bool],
    kwargs: **kwargs,
) -> TaskEnvironment
```
Clone the TaskEnvironment with new parameters.

Besides the base environment parameters, you can override kwargs like `cache`, `reusable`, etc.

| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | The name of the environment. |
| `image` | `Optional[Union[str, Image, Literal['auto']]]` | The image to use for the environment. |
| `resources` | `Optional[Resources]` | The resources to allocate for the environment. |
| `env_vars` | `Optional[Dict[str, str]]` | The environment variables to set for the environment. |
| `secrets` | `Optional[SecretRequest]` | The secrets to inject into the environment. |
| `depends_on` | `Optional[List[Environment]]` | The environment dependencies to hint, so when you deploy the environment, the dependencies are also deployed. This is useful when you have a set of environments that depend on each other. |
| `description` | `Optional[str]` | The description of the environment. |
| `interruptible` | `Optional[bool]` | Whether the environment is interruptible and can be scheduled on spot/preemptible instances. |
| `kwargs` | `**kwargs` | Additional parameters to override the environment (e.g., cache, reusable, plugin_config). |

### from_task()

```python
def from_task(
    name: str,
    tasks: TaskTemplate,
    depends_on: Optional[List['Environment']],
) -> TaskEnvironment
```
Create a TaskEnvironment from a list of tasks. All tasks should have the same image or no Image defined.
Similarity of Image is determined by the python reference, not by value.

If images are different, an error is raised. If no image is defined, the image is set to "auto".

For any other tasks that need to be use these tasks, the returned environment can be used in the `depends_on`
attribute of the other TaskEnvironment.

| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | The name of the environment. |
| `tasks` | `TaskTemplate` | The list of tasks to create the environment from. |
| `depends_on` | `Optional[List['Environment']]` | Optional list of environments that this environment depends on. |

**Returns:** The created TaskEnvironment.

**Raises**

| Exception | Description |
|-|-|
| `ValueError` | If tasks are assigned to multiple environments or have different images. |

### task()

```python
def task(
    _func: F | None,
    short_name: Optional[str],
    cache: CacheRequest | None,
    retries: Union[int, RetryStrategy],
    timeout: Union[timedelta, int],
    docs: Optional[Documentation],
    pod_template: Optional[Union[str, PodTemplate]],
    report: bool,
    interruptible: bool | None,
    max_inline_io_bytes: int,
    queue: Optional[str],
    triggers: Tuple[Trigger, ...] | Trigger,
    links: Tuple[Link, ...] | Link,
    task_resolver: Any | None,
) -> Callable[[F], AsyncFunctionTaskTemplate[P, R, F]] | AsyncFunctionTaskTemplate[P, R, F]
```
Decorate a function to be a task.

| Parameter | Type | Description |
|-|-|-|
| `_func` | `F \| None` | Optional The function to decorate. If not provided, the decorator will return a callable that accepts a function to be decorated. |
| `short_name` | `Optional[str]` | Optional A friendly name for the task (defaults to the function name) |
| `cache` | `CacheRequest \| None` | Optional The cache policy for the task, defaults to auto, which will cache the results of the task. |
| `retries` | `Union[int, RetryStrategy]` | Optional The number of retries for the task, defaults to 0, which means no retries. |
| `timeout` | `Union[timedelta, int]` | Optional The timeout for the task. |
| `docs` | `Optional[Documentation]` | Optional The documentation for the task, if not provided the function docstring will be used. |
| `pod_template` | `Optional[Union[str, PodTemplate]]` | Optional The pod template for the task, if not provided the default pod template will be used. |
| `report` | `bool` | Optional Whether to generate the html report for the task, defaults to False. |
| `interruptible` | `bool \| None` | Optional Whether the task is interruptible, defaults to environment setting. |
| `max_inline_io_bytes` | `int` | Maximum allowed size (in bytes) for all inputs and outputs passed directly to the task (e.g., primitives, strings, dicts). Does not apply to files, directories, or dataframes. |
| `queue` | `Optional[str]` | Optional queue name to use for this task. If not set, the environment's queue will be used. |
| `triggers` | `Tuple[Trigger, ...] \| Trigger` | Optional A tuple of triggers to associate with the task. This allows the task to be run on a schedule or in response to events. Triggers can be defined using the `flyte.trigger` module. |
| `links` | `Tuple[Link, ...] \| Link` | Optional A tuple of links to associate with the task. Links can be used to provide additional context or information about the task. Links should implement the `flyte.Link` protocol |
| `task_resolver` | `Any \| None` | |

**Returns:** A TaskTemplate that can be used to deploy the task.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte/timeout ===

# Timeout

**Package:** `flyte`

Timeout class to define a timeout for a task.
The task timeout can be set to a maximum runtime and a maximum queued time.
Maximum runtime is the maximum time the task can run for (in one attempt).
Maximum queued time is the maximum time the task can stay in the queue before it starts executing.

Example usage:
```python
timeout = Timeout(max_runtime=timedelta(minutes=5), max_queued_time=timedelta(minutes=10))
@env.task(timeout=timeout)
async def my_task():
    pass
```

## Parameters

```python
class Timeout(
    max_runtime: datetime.timedelta | int,
    max_queued_time: datetime.timedelta | int | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `max_runtime` | `datetime.timedelta \| int` | timedelta or int - Maximum runtime for the task. If specified int, it will be converted to timedelta as seconds. |
| `max_queued_time` | `datetime.timedelta \| int \| None` | optional, timedelta or int - Maximum queued time for the task. If specified int, it will be converted to timedelta as seconds. Defaults to None. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte/trigger ===

# Trigger

**Package:** `flyte`

Specification for a scheduled trigger that can be associated with any Flyte task.

Triggers run tasks on a schedule (cron or fixed-rate). They are set only in the
`@env.task` decorator via the `triggers` parameter. The same `Trigger` object
can be associated with multiple tasks.

Predefined convenience constructors are available: `Trigger.hourly()`,
`Trigger.daily()`, `Trigger.weekly()`, `Trigger.monthly()`, and
`Trigger.minutely()`.

```python
my_trigger = flyte.Trigger(
    name="my_trigger",
    description="A trigger that runs every hour",
    inputs={"start_time": flyte.TriggerTime, "x": 1},
    automation=flyte.FixedRate(60),
)

@env.task(triggers=[my_trigger])
async def my_task(start_time: datetime, x: int) -> str:
    ...
```

## Parameters

```python
class Trigger(
    name: str,
    automation: Union[Cron, FixedRate],
    description: str,
    auto_activate: bool,
    inputs: Dict[str, Any] | None,
    env_vars: Dict[str, str] | None,
    interruptible: bool | None,
    overwrite_cache: bool,
    queue: str | None,
    labels: Mapping[str, str] | None,
    annotations: Mapping[str, str] | None,
    notifications: NamedRule | Notification | Tuple[Notification, ...] | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | Unique name for the trigger (required). |
| `automation` | `Union[Cron, FixedRate]` | Schedule type — `Cron(...)` or `FixedRate(...)` (required). |
| `description` | `str` | Human-readable description (max 255 characters). Default `""`. |
| `auto_activate` | `bool` | Whether to activate the trigger automatically on deployment. Default `True`. |
| `inputs` | `Dict[str, Any] \| None` | Default input values for triggered runs. Use `flyte.TriggerTime` to bind the trigger's scheduled time to an input parameter. |
| `env_vars` | `Dict[str, str] \| None` | Environment variables for triggered runs (overrides the task's configured values). |
| `interruptible` | `bool \| None` | Whether triggered runs use spot/preemptible instances. `None` (default) preserves the task's configured behavior. Overrides the task's configured value. |
| `overwrite_cache` | `bool` | Force cache refresh on triggered runs. Default `False`. |
| `queue` | `str \| None` | Queue name for triggered runs (overrides the task's configured value). |
| `labels` | `Mapping[str, str] \| None` | Kubernetes labels to attach to triggered runs. |
| `annotations` | `Mapping[str, str] \| None` | Kubernetes annotations to attach to triggered runs. |
| `notifications` | `NamedRule \| Notification \| Tuple[Notification, ...] \| None` | |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte > Trigger > Methods > daily()** | Creates a Cron trigger that runs daily at midnight. |
| **Flyte SDK > Packages > flyte > Trigger > Methods > hourly()** | Creates a Cron trigger that runs every hour. |
| **Flyte SDK > Packages > flyte > Trigger > Methods > minutely()** | Creates a Cron trigger that runs every minute. |
| **Flyte SDK > Packages > flyte > Trigger > Methods > monthly()** | Creates a Cron trigger that runs monthly on the 1st at midnight. |
| **Flyte SDK > Packages > flyte > Trigger > Methods > weekly()** | Creates a Cron trigger that runs weekly on Sundays at midnight. |

### daily()

```python
def daily(
    trigger_time_input_key: str | None,
    name: str,
    description: str,
    auto_activate: bool,
    inputs: Dict[str, Any] | None,
    env_vars: Dict[str, str] | None,
    interruptible: bool | None,
    overwrite_cache: bool,
    queue: str | None,
    labels: Mapping[str, str] | None,
    annotations: Mapping[str, str] | None,
) -> Trigger
```
Creates a Cron trigger that runs daily at midnight.

| Parameter | Type | Description |
|-|-|-|
| `trigger_time_input_key` | `str \| None` | The input key for the trigger time. If None, no trigger time input is added. |
| `name` | `str` | The name of the trigger, default is "daily". |
| `description` | `str` | A description of the trigger. |
| `auto_activate` | `bool` | Whether the trigger should be automatically activated. |
| `inputs` | `Dict[str, Any] \| None` | Optional inputs for the trigger. |
| `env_vars` | `Dict[str, str] \| None` | Optional environment variables. |
| `interruptible` | `bool \| None` | Whether the triggered run is interruptible. |
| `overwrite_cache` | `bool` | Whether to overwrite the cache. |
| `queue` | `str \| None` | Optional queue to run the trigger in. |
| `labels` | `Mapping[str, str] \| None` | Optional labels to attach to the trigger. |
| `annotations` | `Mapping[str, str] \| None` | Optional annotations to attach to the trigger. |

**Returns:** Trigger: A trigger that runs daily at midnight.

### hourly()

```python
def hourly(
    trigger_time_input_key: str | None,
    name: str,
    description: str,
    auto_activate: bool,
    inputs: Dict[str, Any] | None,
    env_vars: Dict[str, str] | None,
    interruptible: bool | None,
    overwrite_cache: bool,
    queue: str | None,
    labels: Mapping[str, str] | None,
    annotations: Mapping[str, str] | None,
) -> Trigger
```
Creates a Cron trigger that runs every hour.

| Parameter | Type | Description |
|-|-|-|
| `trigger_time_input_key` | `str \| None` | The input parameter for the trigger time. If None, no trigger time input is added. |
| `name` | `str` | The name of the trigger, default is "hourly". |
| `description` | `str` | A description of the trigger. |
| `auto_activate` | `bool` | Whether the trigger should be automatically activated. |
| `inputs` | `Dict[str, Any] \| None` | Optional inputs for the trigger. |
| `env_vars` | `Dict[str, str] \| None` | Optional environment variables. |
| `interruptible` | `bool \| None` | Whether the trigger is interruptible. |
| `overwrite_cache` | `bool` | Whether to overwrite the cache. |
| `queue` | `str \| None` | Optional queue to run the trigger in. |
| `labels` | `Mapping[str, str] \| None` | Optional labels to attach to the trigger. |
| `annotations` | `Mapping[str, str] \| None` | Optional annotations to attach to the trigger. |

**Returns:** Trigger: A trigger that runs every hour, on the hour.

### minutely()

```python
def minutely(
    trigger_time_input_key: str | None,
    name: str,
    description: str,
    auto_activate: bool,
    inputs: Dict[str, Any] | None,
    env_vars: Dict[str, str] | None,
    interruptible: bool | None,
    overwrite_cache: bool,
    queue: str | None,
    labels: Mapping[str, str] | None,
    annotations: Mapping[str, str] | None,
) -> Trigger
```
Creates a Cron trigger that runs every minute.

| Parameter | Type | Description |
|-|-|-|
| `trigger_time_input_key` | `str \| None` | The input parameter for the trigger time. If None, no trigger time input is added. |
| `name` | `str` | The name of the trigger, default is "every_minute". |
| `description` | `str` | A description of the trigger. |
| `auto_activate` | `bool` | Whether the trigger should be automatically activated. |
| `inputs` | `Dict[str, Any] \| None` | Optional inputs for the trigger. |
| `env_vars` | `Dict[str, str] \| None` | Optional environment variables. |
| `interruptible` | `bool \| None` | Whether the trigger is interruptible. |
| `overwrite_cache` | `bool` | Whether to overwrite the cache. |
| `queue` | `str \| None` | Optional queue to run the trigger in. |
| `labels` | `Mapping[str, str] \| None` | Optional labels to attach to the trigger. |
| `annotations` | `Mapping[str, str] \| None` | Optional annotations to attach to the trigger. |

**Returns:** Trigger: A trigger that runs every minute.

### monthly()

```python
def monthly(
    trigger_time_input_key: str | None,
    name: str,
    description: str,
    auto_activate: bool,
    inputs: Dict[str, Any] | None,
    env_vars: Dict[str, str] | None,
    interruptible: bool | None,
    overwrite_cache: bool,
    queue: str | None,
    labels: Mapping[str, str] | None,
    annotations: Mapping[str, str] | None,
) -> Trigger
```
Creates a Cron trigger that runs monthly on the 1st at midnight.

| Parameter | Type | Description |
|-|-|-|
| `trigger_time_input_key` | `str \| None` | The input parameter for the trigger time. If None, no trigger time input is added. |
| `name` | `str` | The name of the trigger, default is "monthly". |
| `description` | `str` | A description of the trigger. |
| `auto_activate` | `bool` | Whether the trigger should be automatically activated. |
| `inputs` | `Dict[str, Any] \| None` | Optional inputs for the trigger. |
| `env_vars` | `Dict[str, str] \| None` | Optional environment variables. |
| `interruptible` | `bool \| None` | Whether the trigger is interruptible. |
| `overwrite_cache` | `bool` | Whether to overwrite the cache. |
| `queue` | `str \| None` | Optional queue to run the trigger in. |
| `labels` | `Mapping[str, str] \| None` | Optional labels to attach to the trigger. |
| `annotations` | `Mapping[str, str] \| None` | Optional annotations to attach to the trigger. |

**Returns:** Trigger: A trigger that runs monthly on the 1st at midnight.

### weekly()

```python
def weekly(
    trigger_time_input_key: str | None,
    name: str,
    description: str,
    auto_activate: bool,
    inputs: Dict[str, Any] | None,
    env_vars: Dict[str, str] | None,
    interruptible: bool | None,
    overwrite_cache: bool,
    queue: str | None,
    labels: Mapping[str, str] | None,
    annotations: Mapping[str, str] | None,
) -> Trigger
```
Creates a Cron trigger that runs weekly on Sundays at midnight.

| Parameter | Type | Description |
|-|-|-|
| `trigger_time_input_key` | `str \| None` | The input parameter for the trigger time. If None, no trigger time input is added. |
| `name` | `str` | The name of the trigger, default is "weekly". |
| `description` | `str` | A description of the trigger. |
| `auto_activate` | `bool` | Whether the trigger should be automatically activated. |
| `inputs` | `Dict[str, Any] \| None` | Optional inputs for the trigger. |
| `env_vars` | `Dict[str, str] \| None` | Optional environment variables. |
| `interruptible` | `bool \| None` | Whether the trigger is interruptible. |
| `overwrite_cache` | `bool` | Whether to overwrite the cache. |
| `queue` | `str \| None` | Optional queue to run the trigger in. |
| `labels` | `Mapping[str, str] \| None` | Optional labels to attach to the trigger. |
| `annotations` | `Mapping[str, str] \| None` | Optional annotations to attach to the trigger. |

**Returns:** Trigger: A trigger that runs weekly on Sundays at midnight.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.app ===

# flyte.app

## Directory

### Classes

| Class | Description |
|-|-|
| **Flyte SDK > Packages > flyte.app > AppEndpoint** | Embed an upstream app's endpoint as an app parameter. |
| **Flyte SDK > Packages > flyte.app > AppEnvironment** | Configure a long-running app environment for APIs, dashboards, or model servers. |
| **Flyte SDK > Packages > flyte.app > ConnectorEnvironment** |  |
| **Flyte SDK > Packages > flyte.app > Domain** | Subdomain to use for the domain. |
| **Flyte SDK > Packages > flyte.app > Link** | Custom links to add to the app. |
| **Flyte SDK > Packages > flyte.app > Parameter** | Parameter for application. |
| **Flyte SDK > Packages > flyte.app > Port** |  |
| **Flyte SDK > Packages > flyte.app > RunOutput** | Use a run's output for app parameters. |
| **Flyte SDK > Packages > flyte.app > Scaling** | Controls replica count and autoscaling behavior for app environments. |
| **Flyte SDK > Packages > flyte.app > Timeouts** | Timeout configuration for the application. |

### Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.app > Methods > ctx()** | Returns the current app context. |
| **Flyte SDK > Packages > flyte.app > Methods > get_parameter()** | Get parameters for application or endpoint. |

## Methods

#### ctx()

```python
def ctx()
```
Returns the current app context.
Returns: AppContext

#### get_parameter()

```python
def get_parameter(
    name: str,
) -> str
```
Get parameters for application or endpoint.

| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |

## Subpages
- **Flyte SDK > Packages > flyte.app > AppEndpoint**
- **Flyte SDK > Packages > flyte.app > AppEnvironment**
- **Flyte SDK > Packages > flyte.app > ConnectorEnvironment**
- **Flyte SDK > Packages > flyte.app > Domain**
- **Flyte SDK > Packages > flyte.app > Link**
- **Flyte SDK > Packages > flyte.app > Parameter**
- **Flyte SDK > Packages > flyte.app > Port**
- **Flyte SDK > Packages > flyte.app > RunOutput**
- **Flyte SDK > Packages > flyte.app > Scaling**
- **Flyte SDK > Packages > flyte.app > Timeouts**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.app/appendpoint ===

# AppEndpoint

**Package:** `flyte.app`

Embed an upstream app's endpoint as an app parameter.

This enables the declaration of an app parameter dependency on a the endpoint of
an upstream app, given by a specific app name. This gives the app access to
the upstream app's endpoint as a public or private url.

## Parameters

```python
class AppEndpoint(
    type: typing.Literal['string'],
    app_name: str,
    public: bool,
)
```
Create a new model by parsing and validating input data from keyword arguments.

Raises [`ValidationError`](https://docs.pydantic.dev/latest/api/pydantic_core/#pydantic_core.ValidationError) if the input data cannot be
validated to form a valid model.

`self` is explicitly positional-only to allow `self` as a field name.

| Parameter | Type | Description |
|-|-|-|
| `type` | `typing.Literal['string']` | |
| `app_name` | `str` | |
| `public` | `bool` | |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.app > AppEndpoint > Methods > check_type()** |  |
| **Flyte SDK > Packages > flyte.app > AppEndpoint > Methods > get()** |  |
| **Flyte SDK > Packages > flyte.app > AppEndpoint > Methods > materialize()** | Returns the AppEndpoint object, the endpoint is retrieved at serving time by the fserve executable. |

### check_type()

```python
def check_type(
    data: typing.Any,
) -> typing.Any
```
| Parameter | Type | Description |
|-|-|-|
| `data` | `typing.Any` | |

### get()

```python
def get()
```
### materialize()

```python
def materialize()
```
Returns the AppEndpoint object, the endpoint is retrieved at serving time by the fserve executable.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.app/appenvironment ===

# AppEnvironment

**Package:** `flyte.app`

Configure a long-running app environment for APIs, dashboards, or model servers.

```python
app_env = flyte.app.AppEnvironment(
    name="my-api",
    image=flyte.Image.from_debian_base(python="3.12").with_pip_packages("fastapi", "uvicorn"),
    port=8080,
    scaling=flyte.app.Scaling(replicas=(1, 3)),
)
```

## Parameters

```python
class AppEnvironment(
    name: str,
    depends_on: List[Environment],
    pod_template: Optional[Union[str, PodTemplate]],
    description: Optional[str],
    secrets: Optional[SecretRequest],
    env_vars: Optional[Dict[str, str]],
    resources: Optional[Resources],
    interruptible: bool,
    image: Union[str, Image, Literal['auto'], None],
    type: Optional[str],
    port: int | Port,
    args: *args,
    command: Optional[Union[List[str], str]],
    requires_auth: bool,
    scaling: Scaling,
    domain: Domain | None,
    links: List[Link],
    include: List[str],
    parameters: List[Parameter],
    cluster_pool: str,
    timeouts: Timeouts,
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | Name of the app (required). Must be lowercase alphanumeric with hyphens. Inherited from Environment. |
| `depends_on` | `List[Environment]` | Dependencies on other environments (deployed together). Inherited from Environment. |
| `pod_template` | `Optional[Union[str, PodTemplate]]` | |
| `description` | `Optional[str]` | |
| `secrets` | `Optional[SecretRequest]` | Secrets to inject. Inherited from Environment. |
| `env_vars` | `Optional[Dict[str, str]]` | Environment variables. Inherited from Environment. |
| `resources` | `Optional[Resources]` | Compute resources (CPU, memory, GPU). Inherited from Environment. |
| `interruptible` | `bool` | |
| `image` | `Union[str, Image, Literal['auto'], None]` | Docker image for the environment. Inherited from Environment. |
| `type` | `Optional[str]` | App type identifier (e.g., `"streamlit"`, `"fastapi"`). When set, the platform may apply framework-specific defaults. |
| `port` | `int \| Port` | Port for the app server. Default `8080`. Ports 8012, 8022, 8112, 9090, and 9091 are reserved and cannot be used. Can also be a `Port` object for advanced configuration. |
| `args` | `*args` | Arguments passed to the app process. Can be a list of strings or a single string. Used for script-based apps (e.g., Streamlit's `["--server.port", "8080"]`). |
| `command` | `Optional[Union[List[str], str]]` | Full command to run in the container. Alternative to `args` — use when you need to override the container's entrypoint entirely. |
| `requires_auth` | `bool` | Whether the app endpoint requires authentication. Default `True`. Set to `False` for public endpoints. |
| `scaling` | `Scaling` | `Scaling` object controlling replicas and autoscaling behavior. Default is `Scaling()` (scale-to-zero, max 1 replica). |
| `domain` | `Domain \| None` | `Domain` object for custom domain configuration. |
| `links` | `List[Link]` | List of `Link` objects for connecting to other environments. |
| `include` | `List[str]` | List of additional file paths to bundle with the app (e.g., utility modules, config files, data files). |
| `parameters` | `List[Parameter]` | List of `Parameter` objects for app inputs. Use `RunOutput` to connect app parameters to task outputs, or `AppEndpoint` to reference other app endpoints. |
| `cluster_pool` | `str` | Cluster pool for scheduling. Default `"default"`. |
| `timeouts` | `Timeouts` | `Timeouts` object for startup/health check timeouts. |

## Properties

| Property | Type | Description |
|-|-|-|
| `endpoint` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.app > AppEnvironment > Methods > add_dependency()** | Add a dependency to the environment. |
| **Flyte SDK > Packages > flyte.app > AppEnvironment > Methods > clone_with()** |  |
| **Flyte SDK > Packages > flyte.app > AppEnvironment > Methods > container_args()** |  |
| **Flyte SDK > Packages > flyte.app > AppEnvironment > Methods > container_cmd()** |  |
| **Flyte SDK > Packages > flyte.app > AppEnvironment > Methods > get_port()** |  |
| **Flyte SDK > Packages > flyte.app > AppEnvironment > Methods > on_shutdown()** | Decorator to define the shutdown function for the app environment. |
| **Flyte SDK > Packages > flyte.app > AppEnvironment > Methods > on_startup()** | Decorator to define the startup function for the app environment. |
| **Flyte SDK > Packages > flyte.app > AppEnvironment > Methods > server()** | Decorator to define the server function for the app environment. |

### add_dependency()

```python
def add_dependency(
    env: Environment,
)
```
Add a dependency to the environment.

| Parameter | Type | Description |
|-|-|-|
| `env` | `Environment` | |

### clone_with()

```python
def clone_with(
    name: str,
    image: Optional[Union[str, Image, Literal['auto']]],
    resources: Optional[Resources],
    env_vars: Optional[dict[str, str]],
    secrets: Optional[SecretRequest],
    depends_on: Optional[List[Environment]],
    description: Optional[str],
    interruptible: Optional[bool],
    kwargs: **kwargs,
) -> AppEnvironment
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |
| `image` | `Optional[Union[str, Image, Literal['auto']]]` | |
| `resources` | `Optional[Resources]` | |
| `env_vars` | `Optional[dict[str, str]]` | |
| `secrets` | `Optional[SecretRequest]` | |
| `depends_on` | `Optional[List[Environment]]` | |
| `description` | `Optional[str]` | |
| `interruptible` | `Optional[bool]` | |
| `kwargs` | `**kwargs` | |

### container_args()

```python
def container_args(
    serialize_context: SerializationContext,
) -> List[str]
```
| Parameter | Type | Description |
|-|-|-|
| `serialize_context` | `SerializationContext` | |

### container_cmd()

```python
def container_cmd(
    serialize_context: SerializationContext,
    parameter_overrides: list[Parameter] | None,
) -> List[str]
```
| Parameter | Type | Description |
|-|-|-|
| `serialize_context` | `SerializationContext` | |
| `parameter_overrides` | `list[Parameter] \| None` | |

### get_port()

```python
def get_port()
```
### on_shutdown()

```python
def on_shutdown(
    fn: Callable[..., None],
) -> Callable[..., None]
```
Decorator to define the shutdown function for the app environment.

This function is called after the server function is called.

This decorated function can be a sync or async function, and accepts input
parameters based on the Parameters defined in the AppEnvironment
definition.

| Parameter | Type | Description |
|-|-|-|
| `fn` | `Callable[..., None]` | |

### on_startup()

```python
def on_startup(
    fn: Callable[..., None],
) -> Callable[..., None]
```
Decorator to define the startup function for the app environment.

This function is called before the server function is called.

The decorated function can be a sync or async function, and accepts input
parameters based on the Parameters defined in the AppEnvironment
definition.

| Parameter | Type | Description |
|-|-|-|
| `fn` | `Callable[..., None]` | |

### server()

```python
def server(
    fn: Callable[..., None],
) -> Callable[..., None]
```
Decorator to define the server function for the app environment.

This decorated function can be a sync or async function, and accepts input
parameters based on the Parameters defined in the AppEnvironment
definition.

| Parameter | Type | Description |
|-|-|-|
| `fn` | `Callable[..., None]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.app/connectorenvironment ===

# ConnectorEnvironment

**Package:** `flyte.app`

## Parameters

```python
class ConnectorEnvironment(
    name: str,
    depends_on: List[Environment],
    pod_template: Optional[Union[str, PodTemplate]],
    description: Optional[str],
    secrets: Optional[SecretRequest],
    env_vars: Optional[Dict[str, str]],
    resources: Optional[Resources],
    interruptible: bool,
    image: Union[str, Image, Literal['auto'], None],
    type: str,
    port: int | flyte.app._types.Port,
    args: *args,
    command: Optional[Union[List[str], str]],
    requires_auth: bool,
    scaling: Scaling,
    domain: Domain | None,
    links: List[Link],
    include: List[str],
    parameters: List[Parameter],
    cluster_pool: str,
    timeouts: Timeouts,
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |
| `depends_on` | `List[Environment]` | |
| `pod_template` | `Optional[Union[str, PodTemplate]]` | |
| `description` | `Optional[str]` | |
| `secrets` | `Optional[SecretRequest]` | |
| `env_vars` | `Optional[Dict[str, str]]` | |
| `resources` | `Optional[Resources]` | |
| `interruptible` | `bool` | |
| `image` | `Union[str, Image, Literal['auto'], None]` | |
| `type` | `str` | |
| `port` | `int \| flyte.app._types.Port` | |
| `args` | `*args` | |
| `command` | `Optional[Union[List[str], str]]` | |
| `requires_auth` | `bool` | |
| `scaling` | `Scaling` | |
| `domain` | `Domain \| None` | |
| `links` | `List[Link]` | |
| `include` | `List[str]` | |
| `parameters` | `List[Parameter]` | |
| `cluster_pool` | `str` | |
| `timeouts` | `Timeouts` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `endpoint` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.app > ConnectorEnvironment > Methods > add_dependency()** | Add a dependency to the environment. |
| **Flyte SDK > Packages > flyte.app > ConnectorEnvironment > Methods > clone_with()** |  |
| **Flyte SDK > Packages > flyte.app > ConnectorEnvironment > Methods > container_args()** |  |
| **Flyte SDK > Packages > flyte.app > ConnectorEnvironment > Methods > container_cmd()** |  |
| **Flyte SDK > Packages > flyte.app > ConnectorEnvironment > Methods > get_port()** |  |
| **Flyte SDK > Packages > flyte.app > ConnectorEnvironment > Methods > on_shutdown()** | Decorator to define the shutdown function for the app environment. |
| **Flyte SDK > Packages > flyte.app > ConnectorEnvironment > Methods > on_startup()** | Decorator to define the startup function for the app environment. |
| **Flyte SDK > Packages > flyte.app > ConnectorEnvironment > Methods > server()** | Decorator to define the server function for the app environment. |

### add_dependency()

```python
def add_dependency(
    env: Environment,
)
```
Add a dependency to the environment.

| Parameter | Type | Description |
|-|-|-|
| `env` | `Environment` | |

### clone_with()

```python
def clone_with(
    name: str,
    image: Optional[Union[str, Image, Literal['auto']]],
    resources: Optional[Resources],
    env_vars: Optional[dict[str, str]],
    secrets: Optional[SecretRequest],
    depends_on: Optional[List[Environment]],
    description: Optional[str],
    interruptible: Optional[bool],
    kwargs: **kwargs,
) -> AppEnvironment
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |
| `image` | `Optional[Union[str, Image, Literal['auto']]]` | |
| `resources` | `Optional[Resources]` | |
| `env_vars` | `Optional[dict[str, str]]` | |
| `secrets` | `Optional[SecretRequest]` | |
| `depends_on` | `Optional[List[Environment]]` | |
| `description` | `Optional[str]` | |
| `interruptible` | `Optional[bool]` | |
| `kwargs` | `**kwargs` | |

### container_args()

```python
def container_args(
    serialize_context: flyte.models.SerializationContext,
) -> typing.List[str]
```
| Parameter | Type | Description |
|-|-|-|
| `serialize_context` | `flyte.models.SerializationContext` | |

### container_cmd()

```python
def container_cmd(
    serialize_context: flyte.models.SerializationContext,
    parameter_overrides: list[flyte.app._parameter.Parameter] | None,
) -> typing.List[str]
```
| Parameter | Type | Description |
|-|-|-|
| `serialize_context` | `flyte.models.SerializationContext` | |
| `parameter_overrides` | `list[flyte.app._parameter.Parameter] \| None` | |

### get_port()

```python
def get_port()
```
### on_shutdown()

```python
def on_shutdown(
    fn: Callable[..., None],
) -> Callable[..., None]
```
Decorator to define the shutdown function for the app environment.

This function is called after the server function is called.

This decorated function can be a sync or async function, and accepts input
parameters based on the Parameters defined in the AppEnvironment
definition.

| Parameter | Type | Description |
|-|-|-|
| `fn` | `Callable[..., None]` | |

### on_startup()

```python
def on_startup(
    fn: Callable[..., None],
) -> Callable[..., None]
```
Decorator to define the startup function for the app environment.

This function is called before the server function is called.

The decorated function can be a sync or async function, and accepts input
parameters based on the Parameters defined in the AppEnvironment
definition.

| Parameter | Type | Description |
|-|-|-|
| `fn` | `Callable[..., None]` | |

### server()

```python
def server(
    fn: Callable[..., None],
) -> Callable[..., None]
```
Decorator to define the server function for the app environment.

This decorated function can be a sync or async function, and accepts input
parameters based on the Parameters defined in the AppEnvironment
definition.

| Parameter | Type | Description |
|-|-|-|
| `fn` | `Callable[..., None]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.app/domain ===

# Domain

**Package:** `flyte.app`

Subdomain to use for the domain. If not set, the default subdomain will be used.

## Parameters

```python
class Domain(
    subdomain: typing.Optional[str],
    custom_domain: typing.Optional[str],
)
```
| Parameter | Type | Description |
|-|-|-|
| `subdomain` | `typing.Optional[str]` | |
| `custom_domain` | `typing.Optional[str]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.app/link ===

# Link

**Package:** `flyte.app`

Custom links to add to the app

## Parameters

```python
class Link(
    path: str,
    title: str,
    is_relative: bool,
)
```
| Parameter | Type | Description |
|-|-|-|
| `path` | `str` | |
| `title` | `str` | |
| `is_relative` | `bool` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.app/parameter ===

# Parameter

**Package:** `flyte.app`

Parameter for application.

## Parameters

```python
class Parameter(
    name: str,
    value: ParameterTypes | _DelayedValue,
    env_var: Optional[str],
    download: bool,
    mount: Optional[str],
    ignore_patterns: list[str],
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | Name of parameter. |
| `value` | `ParameterTypes \| _DelayedValue` | Value for parameter. |
| `env_var` | `Optional[str]` | Environment name to set the value in the serving environment. |
| `download` | `bool` | When True, the parameter will be automatically downloaded. This only works if the value refers to an item in a object store. i.e. `s3://...` |
| `mount` | `Optional[str]` | If `value` is a directory, then the directory will be available at `mount`. If `value` is a file, then the file will be downloaded into the `mount` directory. |
| `ignore_patterns` | `list[str]` | If `value` is a directory, then this is a list of glob patterns to ignore. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.app/port ===

# Port

**Package:** `flyte.app`

## Parameters

```python
class Port(
    port: int,
    name: typing.Optional[str],
)
```
| Parameter | Type | Description |
|-|-|-|
| `port` | `int` | |
| `name` | `typing.Optional[str]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.app/runoutput ===

# RunOutput

**Package:** `flyte.app`

Use a run's output for app parameters.

This enables the declaration of an app parameter dependency on the output of
a run, given by a specific run name, or a task name and version. If
`task_auto_version == 'latest'`, the latest version of the task will be used.
If `task_auto_version == 'current'`, the version will be derived from the callee
app or task context. To get the latest task run for ephemeral task runs, set
`task_version` and `task_auto_version` should both be set to `None` (which is the default).

Get the output of a specific run:

```python
run_output = RunOutput(type="directory", run_name="my-run-123")
```

Get the latest output of an ephemeral task run:

```python
run_output = RunOutput(type="file", task_name="env.my_task")
```

Get the latest output of a deployed task run:

```python
run_output = RunOutput(type="file", task_name="env.my_task", task_auto_version="latest")
```

Get the output of a specific task run:

```python
run_output = RunOutput(type="file", task_name="env.my_task", task_version="xyz")
```

## Parameters

```python
class RunOutput(
    type: typing.Literal['string', 'file', 'directory', 'app_endpoint'],
    run_name: str | None,
    task_name: str | None,
    task_version: str | None,
    task_auto_version: typing.Optional[typing.Literal['latest', 'current']],
    getter: tuple[typing.Any, ...],
)
```
Create a new model by parsing and validating input data from keyword arguments.

Raises [`ValidationError`](https://docs.pydantic.dev/latest/api/pydantic_core/#pydantic_core.ValidationError) if the input data cannot be
validated to form a valid model.

`self` is explicitly positional-only to allow `self` as a field name.

| Parameter | Type | Description |
|-|-|-|
| `type` | `typing.Literal['string', 'file', 'directory', 'app_endpoint']` | |
| `run_name` | `str \| None` | |
| `task_name` | `str \| None` | |
| `task_version` | `str \| None` | |
| `task_auto_version` | `typing.Optional[typing.Literal['latest', 'current']]` | |
| `getter` | `tuple[typing.Any, ...]` | |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.app > RunOutput > Methods > check_type()** |  |
| **Flyte SDK > Packages > flyte.app > RunOutput > Methods > get()** |  |
| **Flyte SDK > Packages > flyte.app > RunOutput > Methods > materialize()** |  |

### check_type()

```python
def check_type(
    data: typing.Any,
) -> typing.Any
```
| Parameter | Type | Description |
|-|-|-|
| `data` | `typing.Any` | |

### get()

```python
def get()
```
### materialize()

```python
def materialize()
```


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.app/scaling ===

# Scaling

**Package:** `flyte.app`

Controls replica count and autoscaling behavior for app environments.

Common scaling patterns:

- **Scale-to-zero** (default): `Scaling(replicas=(0, 1))` — no replicas when idle,
  scales to 1 on demand.
- **Always-on**: `Scaling(replicas=(1, 1))` — exactly 1 replica at all times.
- **Burstable**: `Scaling(replicas=(1, 5))` — 1 replica minimum, scales up to 5.
- **High-availability**: `Scaling(replicas=(2, 10))` — at least 2 replicas always running.
- **Fixed size**: `Scaling(replicas=3)` — exactly 3 replicas.

## Parameters

```python
class Scaling(
    replicas: typing.Union[int, typing.Tuple[int, int]],
    metric: typing.Union[flyte.app._types.Scaling.Concurrency, flyte.app._types.Scaling.RequestRate, NoneType],
    scaledown_after: int | datetime.timedelta | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `replicas` | `typing.Union[int, typing.Tuple[int, int]]` | Number of replicas. An `int` for fixed count, or a `(min, max)` tuple for autoscaling. Default `(0, 1)`. |
| `metric` | `typing.Union[flyte.app._types.Scaling.Concurrency, flyte.app._types.Scaling.RequestRate, NoneType]` | Autoscaling metric — `Scaling.Concurrency(val)` (scale when concurrent requests per replica exceeds `val`) or `Scaling.RequestRate(val)` (scale when requests per second per replica exceeds `val`). Default `None`. |
| `scaledown_after` | `int \| datetime.timedelta \| None` | Time to wait after the last request before scaling down. Seconds (`int`) or `timedelta`. Default `None` (platform default). |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.app > Scaling > Methods > get_replicas()** |  |

### get_replicas()

```python
def get_replicas()
```


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.app/timeouts ===

# Timeouts

**Package:** `flyte.app`

Timeout configuration for the application.

## Parameters

```python
class Timeouts(
    request: int | datetime.timedelta | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `request` | `int \| datetime.timedelta \| None` | Timeout for requests to the application. Can be an int (seconds) or timedelta. Must not exceed 1 hour. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.app.extras ===

# flyte.app.extras

## Directory

### Classes

| Class | Description |
|-|-|
| **Flyte SDK > Packages > flyte.app.extras > FastAPIAppEnvironment** |  |
| **Flyte SDK > Packages > flyte.app.extras > FastAPIPassthroughAuthMiddleware** | FastAPI middleware that automatically sets Flyte auth metadata from request headers. |
| **Flyte SDK > Packages > flyte.app.extras > FlyteWebhookAppEnvironment** | A pre-built FastAPI app environment for common Flyte webhook operations. |

## Subpages
- **Flyte SDK > Packages > flyte.app.extras > FastAPIAppEnvironment**
- **Flyte SDK > Packages > flyte.app.extras > FastAPIPassthroughAuthMiddleware**
- **Flyte SDK > Packages > flyte.app.extras > FlyteWebhookAppEnvironment**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.app.extras/fastapiappenvironment ===

# FastAPIAppEnvironment

**Package:** `flyte.app.extras`

## Parameters

```python
class FastAPIAppEnvironment(
    name: str,
    depends_on: List[Environment],
    pod_template: Optional[Union[str, PodTemplate]],
    description: Optional[str],
    secrets: Optional[SecretRequest],
    env_vars: Optional[Dict[str, str]],
    resources: Optional[Resources],
    interruptible: bool,
    image: Union[str, Image, Literal['auto'], None],
    port: int | Port,
    args: *args,
    command: Optional[Union[List[str], str]],
    requires_auth: bool,
    scaling: Scaling,
    domain: Domain | None,
    links: List[Link],
    include: List[str],
    parameters: List[Parameter],
    cluster_pool: str,
    timeouts: Timeouts,
    type: str,
    app: fastapi.FastAPI,
    uvicorn_config: uvicorn.Config | None,
    _caller_frame: inspect.FrameInfo | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |
| `depends_on` | `List[Environment]` | |
| `pod_template` | `Optional[Union[str, PodTemplate]]` | |
| `description` | `Optional[str]` | |
| `secrets` | `Optional[SecretRequest]` | |
| `env_vars` | `Optional[Dict[str, str]]` | |
| `resources` | `Optional[Resources]` | |
| `interruptible` | `bool` | |
| `image` | `Union[str, Image, Literal['auto'], None]` | |
| `port` | `int \| Port` | |
| `args` | `*args` | |
| `command` | `Optional[Union[List[str], str]]` | |
| `requires_auth` | `bool` | |
| `scaling` | `Scaling` | |
| `domain` | `Domain \| None` | |
| `links` | `List[Link]` | |
| `include` | `List[str]` | |
| `parameters` | `List[Parameter]` | |
| `cluster_pool` | `str` | |
| `timeouts` | `Timeouts` | |
| `type` | `str` | |
| `app` | `fastapi.FastAPI` | |
| `uvicorn_config` | `uvicorn.Config \| None` | |
| `_caller_frame` | `inspect.FrameInfo \| None` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `endpoint` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.app.extras > FastAPIAppEnvironment > Methods > add_dependency()** | Add a dependency to the environment. |
| **Flyte SDK > Packages > flyte.app.extras > FastAPIAppEnvironment > Methods > clone_with()** |  |
| **Flyte SDK > Packages > flyte.app.extras > FastAPIAppEnvironment > Methods > container_args()** |  |
| **Flyte SDK > Packages > flyte.app.extras > FastAPIAppEnvironment > Methods > container_cmd()** |  |
| **Flyte SDK > Packages > flyte.app.extras > FastAPIAppEnvironment > Methods > container_command()** |  |
| **Flyte SDK > Packages > flyte.app.extras > FastAPIAppEnvironment > Methods > get_port()** |  |
| **Flyte SDK > Packages > flyte.app.extras > FastAPIAppEnvironment > Methods > on_shutdown()** | Decorator to define the shutdown function for the app environment. |
| **Flyte SDK > Packages > flyte.app.extras > FastAPIAppEnvironment > Methods > on_startup()** | Decorator to define the startup function for the app environment. |
| **Flyte SDK > Packages > flyte.app.extras > FastAPIAppEnvironment > Methods > server()** | Decorator to define the server function for the app environment. |

### add_dependency()

```python
def add_dependency(
    env: Environment,
)
```
Add a dependency to the environment.

| Parameter | Type | Description |
|-|-|-|
| `env` | `Environment` | |

### clone_with()

```python
def clone_with(
    name: str,
    image: Optional[Union[str, Image, Literal['auto']]],
    resources: Optional[Resources],
    env_vars: Optional[dict[str, str]],
    secrets: Optional[SecretRequest],
    depends_on: Optional[List[Environment]],
    description: Optional[str],
    interruptible: Optional[bool],
    kwargs: **kwargs,
) -> AppEnvironment
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |
| `image` | `Optional[Union[str, Image, Literal['auto']]]` | |
| `resources` | `Optional[Resources]` | |
| `env_vars` | `Optional[dict[str, str]]` | |
| `secrets` | `Optional[SecretRequest]` | |
| `depends_on` | `Optional[List[Environment]]` | |
| `description` | `Optional[str]` | |
| `interruptible` | `Optional[bool]` | |
| `kwargs` | `**kwargs` | |

### container_args()

```python
def container_args(
    serialize_context: SerializationContext,
) -> List[str]
```
| Parameter | Type | Description |
|-|-|-|
| `serialize_context` | `SerializationContext` | |

### container_cmd()

```python
def container_cmd(
    serialize_context: SerializationContext,
    parameter_overrides: list[Parameter] | None,
) -> List[str]
```
| Parameter | Type | Description |
|-|-|-|
| `serialize_context` | `SerializationContext` | |
| `parameter_overrides` | `list[Parameter] \| None` | |

### container_command()

```python
def container_command(
    serialization_context: SerializationContext,
) -> list[str]
```
| Parameter | Type | Description |
|-|-|-|
| `serialization_context` | `SerializationContext` | |

### get_port()

```python
def get_port()
```
### on_shutdown()

```python
def on_shutdown(
    fn: Callable[..., None],
) -> Callable[..., None]
```
Decorator to define the shutdown function for the app environment.

This function is called after the server function is called.

This decorated function can be a sync or async function, and accepts input
parameters based on the Parameters defined in the AppEnvironment
definition.

| Parameter | Type | Description |
|-|-|-|
| `fn` | `Callable[..., None]` | |

### on_startup()

```python
def on_startup(
    fn: Callable[..., None],
) -> Callable[..., None]
```
Decorator to define the startup function for the app environment.

This function is called before the server function is called.

The decorated function can be a sync or async function, and accepts input
parameters based on the Parameters defined in the AppEnvironment
definition.

| Parameter | Type | Description |
|-|-|-|
| `fn` | `Callable[..., None]` | |

### server()

```python
def server(
    fn: Callable[..., None],
) -> Callable[..., None]
```
Decorator to define the server function for the app environment.

This decorated function can be a sync or async function, and accepts input
parameters based on the Parameters defined in the AppEnvironment
definition.

| Parameter | Type | Description |
|-|-|-|
| `fn` | `Callable[..., None]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.app.extras/fastapipassthroughauthmiddleware ===

# FastAPIPassthroughAuthMiddleware

**Package:** `flyte.app.extras`

FastAPI middleware that automatically sets Flyte auth metadata from request headers.

This middleware extracts authentication headers from incoming HTTP requests and
sets them in the Flyte context using the auth_metadata() context manager. This
eliminates the need to manually wrap endpoint handlers with auth_metadata().

The middleware is highly configurable:
- Custom header extractors can be provided
- Specific paths can be excluded from auth requirements
- Auth can be optional or required

Thread Safety:
    This middleware is async-safe and properly isolates auth metadata per request
    using Python's contextvars. Multiple concurrent requests with different
    authentication will not interfere with each other.

## Parameters

```python
class FastAPIPassthroughAuthMiddleware(
    app,
    header_extractors: list[HeaderExtractor] | None,
    excluded_paths: set[str] | None,
)
```
Initialize the Flyte authentication middleware.

| Parameter | Type | Description |
|-|-|-|
| `app` |  | The FastAPI application (this is a mandatory framework parameter) |
| `header_extractors` | `list[HeaderExtractor] \| None` | List of functions to extract headers from requests |
| `excluded_paths` | `set[str] \| None` | Set of URL paths that bypass auth extraction |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.app.extras > FastAPIPassthroughAuthMiddleware > Methods > dispatch()** | Process each request, extracting auth headers and setting Flyte context. |
| **Flyte SDK > Packages > flyte.app.extras > FastAPIPassthroughAuthMiddleware > Methods > extract_authorization_header()** | Extract the Authorization header from the request. |
| **Flyte SDK > Packages > flyte.app.extras > FastAPIPassthroughAuthMiddleware > Methods > extract_cookie_header()** | Extract the Cookie header from the request. |
| **Flyte SDK > Packages > flyte.app.extras > FastAPIPassthroughAuthMiddleware > Methods > extract_custom_header()** | Create a header extractor for a custom header name. |

### dispatch()

```python
def dispatch(
    request: 'Request',
    call_next,
) -> 'Response'
```
Process each request, extracting auth headers and setting Flyte context.

| Parameter | Type | Description |
|-|-|-|
| `request` | `'Request'` | The incoming HTTP request |
| `call_next` |  | The next middleware or route handler to call |

**Returns:** The HTTP response from the handler

### extract_authorization_header()

```python
def extract_authorization_header(
    request: 'Request',
) -> tuple[str, str] | None
```
Extract the Authorization header from the request.

| Parameter | Type | Description |
|-|-|-|
| `request` | `'Request'` | The FastAPI/Starlette request object |

**Returns:** Tuple of ("authorization", header_value) if present, None otherwise

### extract_cookie_header()

```python
def extract_cookie_header(
    request: 'Request',
) -> tuple[str, str] | None
```
Extract the Cookie header from the request.

| Parameter | Type | Description |
|-|-|-|
| `request` | `'Request'` | The FastAPI/Starlette request object |

**Returns:** Tuple of ("cookie", header_value) if present, None otherwise

### extract_custom_header()

```python
def extract_custom_header(
    header_name: str,
) -> HeaderExtractor
```
Create a header extractor for a custom header name.

| Parameter | Type | Description |
|-|-|-|
| `header_name` | `str` | The name of the header to extract (case-insensitive) |

**Returns**

A header extractor function that extracts the specified header


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.app.extras/flytewebhookappenvironment ===

# FlyteWebhookAppEnvironment

**Package:** `flyte.app.extras`

A pre-built FastAPI app environment for common Flyte webhook operations.

This environment provides a ready-to-use FastAPI application with endpoints for:
- Running tasks in a specific domain/project/version
- Getting run I/O and metadata
- Aborting runs
- Getting task metadata
- Building images
- Activating/deactivating apps (except itself)
- Getting app status
- Calling other app endpoints
- Activating/deactivating triggers
- Prefetching HuggingFace models (run, status, I/O, abort)

All endpoints use FastAPIPassthroughAuthMiddleware for authentication.

## Parameters

```python
class FlyteWebhookAppEnvironment(
    name: str,
    depends_on: List[Environment],
    pod_template: Optional[Union[str, PodTemplate]],
    description: Optional[str],
    secrets: Optional[SecretRequest],
    env_vars: Optional[Dict[str, str]],
    resources: Optional[Resources],
    interruptible: bool,
    port: int | Port,
    args: *args,
    command: Optional[Union[List[str], str]],
    requires_auth: bool,
    scaling: Scaling,
    domain: Domain | None,
    links: List[Link],
    include: List[str],
    parameters: List[Parameter],
    cluster_pool: str,
    timeouts: Timeouts,
    image: flyte.Image,
    type: str,
    uvicorn_config: 'uvicorn.Config | None',
    _caller_frame: inspect.FrameInfo | None,
    title: str | None,
    endpoint_groups: list[WebhookEndpointGroup] | tuple[WebhookEndpointGroup, ...] | None,
    endpoints: list[WebhookEndpoint] | tuple[WebhookEndpoint, ...] | None,
    task_allowlist: list[str] | None,
    app_allowlist: list[str] | None,
    trigger_allowlist: list[str] | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | Name of the webhook app environment |
| `depends_on` | `List[Environment]` | Environment dependencies |
| `pod_template` | `Optional[Union[str, PodTemplate]]` | |
| `description` | `Optional[str]` | Description for the FastAPI app (optional) |
| `secrets` | `Optional[SecretRequest]` | Secrets to inject into the environment |
| `env_vars` | `Optional[Dict[str, str]]` | |
| `resources` | `Optional[Resources]` | Resources to allocate for the environment |
| `interruptible` | `bool` | |
| `port` | `int \| Port` | |
| `args` | `*args` | |
| `command` | `Optional[Union[List[str], str]]` | |
| `requires_auth` | `bool` | Whether the app requires authentication (default: True) |
| `scaling` | `Scaling` | Scaling configuration for the app environment |
| `domain` | `Domain \| None` | |
| `links` | `List[Link]` | |
| `include` | `List[str]` | |
| `parameters` | `List[Parameter]` | |
| `cluster_pool` | `str` | |
| `timeouts` | `Timeouts` | |
| `image` | `flyte.Image` | Docker image to use for the environment |
| `type` | `str` | |
| `uvicorn_config` | `'uvicorn.Config \| None'` | |
| `_caller_frame` | `inspect.FrameInfo \| None` | |
| `title` | `str \| None` | Title for the FastAPI app (optional) |
| `endpoint_groups` | `list[WebhookEndpointGroup] \| tuple[WebhookEndpointGroup, ...] \| None` | List of endpoint groups to enable. If None (and endpoints is None), all endpoints are enabled. Available groups (see WebhookEndpointGroup type): - "all": All available endpoints - "core": Health check and user info ("health", "me") - "task": Task operations ("run_task", "get_task") - "run": Run operations ("get_run", "get_run_io", "abort_run") - "app": App operations ("get_app", "activate_app", "deactivate_app", "call_app") - "trigger": Trigger operations ("activate_trigger", "deactivate_trigger") - "build": Image build operations ("build_image") - "prefetch": HuggingFace prefetch operations ("prefetch_hf_model",              "get_prefetch_hf_model", "get_prefetch_hf_model_io", "abort_prefetch_hf_model") |
| `endpoints` | `list[WebhookEndpoint] \| tuple[WebhookEndpoint, ...] \| None` | List of individual endpoints to enable. Can be used alone or combined with endpoint_groups. Available endpoints (see WebhookEndpoint type): - "health": Health check endpoint - "me": Get current user info - "run_task": Run a task - "get_task": Get task metadata - "get_run": Get run status - "get_run_io": Get run inputs/outputs - "abort_run": Abort a run - "get_app": Get app status - "activate_app": Activate an app - "deactivate_app": Deactivate an app - "call_app": Call another app's endpoint - "activate_trigger": Activate a trigger - "deactivate_trigger": Deactivate a trigger - "build_image": Build a container image - "prefetch_hf_model": Prefetch a HuggingFace model - "get_prefetch_hf_model": Get prefetch run status - "get_prefetch_hf_model_io": Get prefetch run I/O - "abort_prefetch_hf_model": Abort a prefetch run |
| `task_allowlist` | `list[str] \| None` | List of allowed task identifiers. When set, only tasks matching the allowlist can be accessed via task endpoints. Supports formats: - "domain/project/name" for exact match - "project/name" for project/name match (any domain) - "name" for name-only match (any domain/project) |
| `app_allowlist` | `list[str] \| None` | List of allowed app names. When set, only apps matching the allowlist can be accessed via app endpoints. |
| `trigger_allowlist` | `list[str] \| None` | List of allowed trigger identifiers. When set, only triggers matching the allowlist can be accessed via trigger endpoints. Supports formats: - "task_name/trigger_name" for exact match - "trigger_name" for name-only match (any task) |

## Properties

| Property | Type | Description |
|-|-|-|
| `endpoint` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.app.extras > FlyteWebhookAppEnvironment > Methods > add_dependency()** | Add a dependency to the environment. |
| **Flyte SDK > Packages > flyte.app.extras > FlyteWebhookAppEnvironment > Methods > clone_with()** |  |
| **Flyte SDK > Packages > flyte.app.extras > FlyteWebhookAppEnvironment > Methods > container_args()** |  |
| **Flyte SDK > Packages > flyte.app.extras > FlyteWebhookAppEnvironment > Methods > container_cmd()** |  |
| **Flyte SDK > Packages > flyte.app.extras > FlyteWebhookAppEnvironment > Methods > container_command()** |  |
| **Flyte SDK > Packages > flyte.app.extras > FlyteWebhookAppEnvironment > Methods > get_port()** |  |
| **Flyte SDK > Packages > flyte.app.extras > FlyteWebhookAppEnvironment > Methods > on_shutdown()** | Decorator to define the shutdown function for the app environment. |
| **Flyte SDK > Packages > flyte.app.extras > FlyteWebhookAppEnvironment > Methods > on_startup()** | Decorator to define the startup function for the app environment. |
| **Flyte SDK > Packages > flyte.app.extras > FlyteWebhookAppEnvironment > Methods > server()** | Decorator to define the server function for the app environment. |

### add_dependency()

```python
def add_dependency(
    env: Environment,
)
```
Add a dependency to the environment.

| Parameter | Type | Description |
|-|-|-|
| `env` | `Environment` | |

### clone_with()

```python
def clone_with(
    name: str,
    image: Optional[Union[str, Image, Literal['auto']]],
    resources: Optional[Resources],
    env_vars: Optional[dict[str, str]],
    secrets: Optional[SecretRequest],
    depends_on: Optional[List[Environment]],
    description: Optional[str],
    interruptible: Optional[bool],
    kwargs: **kwargs,
) -> AppEnvironment
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |
| `image` | `Optional[Union[str, Image, Literal['auto']]]` | |
| `resources` | `Optional[Resources]` | |
| `env_vars` | `Optional[dict[str, str]]` | |
| `secrets` | `Optional[SecretRequest]` | |
| `depends_on` | `Optional[List[Environment]]` | |
| `description` | `Optional[str]` | |
| `interruptible` | `Optional[bool]` | |
| `kwargs` | `**kwargs` | |

### container_args()

```python
def container_args(
    serialize_context: SerializationContext,
) -> List[str]
```
| Parameter | Type | Description |
|-|-|-|
| `serialize_context` | `SerializationContext` | |

### container_cmd()

```python
def container_cmd(
    serialize_context: SerializationContext,
    parameter_overrides: list[Parameter] | None,
) -> List[str]
```
| Parameter | Type | Description |
|-|-|-|
| `serialize_context` | `SerializationContext` | |
| `parameter_overrides` | `list[Parameter] \| None` | |

### container_command()

```python
def container_command(
    serialization_context: SerializationContext,
) -> list[str]
```
| Parameter | Type | Description |
|-|-|-|
| `serialization_context` | `SerializationContext` | |

### get_port()

```python
def get_port()
```
### on_shutdown()

```python
def on_shutdown(
    fn: Callable[..., None],
) -> Callable[..., None]
```
Decorator to define the shutdown function for the app environment.

This function is called after the server function is called.

This decorated function can be a sync or async function, and accepts input
parameters based on the Parameters defined in the AppEnvironment
definition.

| Parameter | Type | Description |
|-|-|-|
| `fn` | `Callable[..., None]` | |

### on_startup()

```python
def on_startup(
    fn: Callable[..., None],
) -> Callable[..., None]
```
Decorator to define the startup function for the app environment.

This function is called before the server function is called.

The decorated function can be a sync or async function, and accepts input
parameters based on the Parameters defined in the AppEnvironment
definition.

| Parameter | Type | Description |
|-|-|-|
| `fn` | `Callable[..., None]` | |

### server()

```python
def server(
    fn: Callable[..., None],
) -> Callable[..., None]
```
Decorator to define the server function for the app environment.

This decorated function can be a sync or async function, and accepts input
parameters based on the Parameters defined in the AppEnvironment
definition.

| Parameter | Type | Description |
|-|-|-|
| `fn` | `Callable[..., None]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.config ===

# flyte.config

## Directory

### Classes

| Class | Description |
|-|-|
| **Flyte SDK > Packages > flyte.config > Config** | This the parent configuration object and holds all the underlying configuration object types. |

### Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.config > Methods > auto()** | Automatically constructs the Config Object. |
| **Flyte SDK > Packages > flyte.config > Methods > set_if_exists()** | Given a dict `d` sets the key `k` with value of config `v`, if the config value `v` is set. |

## Methods

#### auto()

```python
def auto(
    config_file: typing.Union[str, pathlib.Path, ConfigFile, None],
) -> Config
```
Automatically constructs the Config Object. The order of precedence is as follows
  1. If specified, read the config from the provided file path.
  2. If not specified, the config file is searched in the default locations.
        a. ./config.yaml if it exists  (current working directory)
        b. ./.flyte/config.yaml if it exists (current working directory)
        c. &lt;git_root&gt;/.flyte/config.yaml if it exists
        d. `UCTL_CONFIG` environment variable
        e. `FLYTECTL_CONFIG` environment variable
        f. ~/.union/config.yaml if it exists
        g. ~/.flyte/config.yaml if it exists
3. If any value is not found in the config file, the default value is used.
4. For any value there are environment variables that match the config variable names, those will override

| Parameter | Type | Description |
|-|-|-|
| `config_file` | `typing.Union[str, pathlib.Path, ConfigFile, None]` | file path to read the config from, if not specified default locations are searched |

**Returns:** Config

#### set_if_exists()

```python
def set_if_exists(
    d: dict,
    k: str,
    val: typing.Any,
) -> dict
```
Given a dict `d` sets the key `k` with value of config `v`, if the config value `v` is set
and return the updated dictionary.

| Parameter | Type | Description |
|-|-|-|
| `d` | `dict` | |
| `k` | `str` | |
| `val` | `typing.Any` | |

## Subpages
- **Flyte SDK > Packages > flyte.config > Config**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.config/config ===

# Config

**Package:** `flyte.config`

This the parent configuration object and holds all the underlying configuration object types. An instance of
this object holds all the config necessary to

1. Interactive session with Flyte backend
2. Some parts are required for Serialization, for example Platform Config is not required
3. Runtime of a task

## Parameters

```python
class Config(
    platform: PlatformConfig,
    task: TaskConfig,
    image: ImageConfig,
    local: LocalConfig,
    source: pathlib.Path | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `platform` | `PlatformConfig` | |
| `task` | `TaskConfig` | |
| `image` | `ImageConfig` | |
| `local` | `LocalConfig` | |
| `source` | `pathlib.Path \| None` | |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.config > Config > Methods > auto()** | Automatically constructs the Config Object. |
| **Flyte SDK > Packages > flyte.config > Config > Methods > with_params()** |  |

### auto()

```python
def auto(
    config_file: typing.Union[str, pathlib.Path, ConfigFile, None],
) -> 'Config'
```
Automatically constructs the Config Object. The order of precedence is as follows
  1. first try to find any env vars that match the config vars specified in the FLYTE_CONFIG format.
  2. If not found in environment then values ar read from the config file
  3. If not found in the file, then the default values are used.

| Parameter | Type | Description |
|-|-|-|
| `config_file` | `typing.Union[str, pathlib.Path, ConfigFile, None]` | file path to read the config from, if not specified default locations are searched |

**Returns:** Config

### with_params()

```python
def with_params(
    platform: PlatformConfig | None,
    task: TaskConfig | None,
    image: ImageConfig | None,
) -> 'Config'
```
| Parameter | Type | Description |
|-|-|-|
| `platform` | `PlatformConfig \| None` | |
| `task` | `TaskConfig \| None` | |
| `image` | `ImageConfig \| None` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.connectors ===

# flyte.connectors

## Directory

### Classes

| Class | Description |
|-|-|
| **Flyte SDK > Packages > flyte.connectors > AsyncConnector** | This is the base class for all async connectors, and it defines the interface that all connectors must implement. |
| **Flyte SDK > Packages > flyte.connectors > AsyncConnectorExecutorMixin** | This mixin class is used to run the connector task locally, and it's only used for local execution. |
| **Flyte SDK > Packages > flyte.connectors > ConnectorRegistry** | This is the registry for all connectors. |
| **Flyte SDK > Packages > flyte.connectors > ConnectorService** |  |
| **Flyte SDK > Packages > flyte.connectors > Resource** | This is the output resource of the job. |
| **Flyte SDK > Packages > flyte.connectors > ResourceMeta** | This is the metadata for the job. |

## Subpages
- **Flyte SDK > Packages > flyte.connectors > AsyncConnector**
- **Flyte SDK > Packages > flyte.connectors > AsyncConnectorExecutorMixin**
- **Flyte SDK > Packages > flyte.connectors > ConnectorRegistry**
- **Flyte SDK > Packages > flyte.connectors > ConnectorService**
- **Flyte SDK > Packages > flyte.connectors > Resource**
- **Flyte SDK > Packages > flyte.connectors > ResourceMeta**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.connectors/asyncconnector ===

# AsyncConnector

**Package:** `flyte.connectors`

This is the base class for all async connectors, and it defines the interface that all connectors must implement.
The connector service is responsible for invoking connectors.
The executor will communicate with the connector service to create tasks, get the status of tasks, and delete tasks.

All the connectors should be registered in the ConnectorRegistry.
Connector Service will look up the connector based on the task type and version.

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.connectors > AsyncConnector > Methods > create()** | Return a resource meta that can be used to get the status of the task. |
| **Flyte SDK > Packages > flyte.connectors > AsyncConnector > Methods > delete()** | Delete the task. |
| **Flyte SDK > Packages > flyte.connectors > AsyncConnector > Methods > get()** | Return the status of the task, and return the outputs in some cases. |
| **Flyte SDK > Packages > flyte.connectors > AsyncConnector > Methods > get_logs()** | Return the metrics for the task. |
| **Flyte SDK > Packages > flyte.connectors > AsyncConnector > Methods > get_metrics()** | Return the metrics for the task. |

### create()

```python
def create(
    task_template: flyteidl2.core.tasks_pb2.TaskTemplate,
    output_prefix: str,
    inputs: typing.Optional[typing.Dict[str, typing.Any]],
    task_execution_metadata: typing.Optional[flyteidl2.connector.connector_pb2.TaskExecutionMetadata],
    kwargs,
) -> flyte.connectors._connector.ResourceMeta
```
Return a resource meta that can be used to get the status of the task.

| Parameter | Type | Description |
|-|-|-|
| `task_template` | `flyteidl2.core.tasks_pb2.TaskTemplate` | |
| `output_prefix` | `str` | |
| `inputs` | `typing.Optional[typing.Dict[str, typing.Any]]` | |
| `task_execution_metadata` | `typing.Optional[flyteidl2.connector.connector_pb2.TaskExecutionMetadata]` | |
| `kwargs` | `**kwargs` | |

### delete()

```python
def delete(
    resource_meta: flyte.connectors._connector.ResourceMeta,
    kwargs,
)
```
Delete the task. This call should be idempotent. It should raise an error if fails to delete the task.

| Parameter | Type | Description |
|-|-|-|
| `resource_meta` | `flyte.connectors._connector.ResourceMeta` | |
| `kwargs` | `**kwargs` | |

### get()

```python
def get(
    resource_meta: flyte.connectors._connector.ResourceMeta,
    kwargs,
) -> flyte.connectors._connector.Resource
```
Return the status of the task, and return the outputs in some cases. For example, bigquery job
can't write the structured dataset to the output location, so it returns the output literals to the propeller,
and the propeller will write the structured dataset to the blob store.

| Parameter | Type | Description |
|-|-|-|
| `resource_meta` | `flyte.connectors._connector.ResourceMeta` | |
| `kwargs` | `**kwargs` | |

### get_logs()

```python
def get_logs(
    resource_meta: flyte.connectors._connector.ResourceMeta,
    kwargs,
) -> flyteidl2.connector.connector_pb2.GetTaskLogsResponse
```
Return the metrics for the task.

| Parameter | Type | Description |
|-|-|-|
| `resource_meta` | `flyte.connectors._connector.ResourceMeta` | |
| `kwargs` | `**kwargs` | |

### get_metrics()

```python
def get_metrics(
    resource_meta: flyte.connectors._connector.ResourceMeta,
    kwargs,
) -> flyteidl2.connector.connector_pb2.GetTaskMetricsResponse
```
Return the metrics for the task.

| Parameter | Type | Description |
|-|-|-|
| `resource_meta` | `flyte.connectors._connector.ResourceMeta` | |
| `kwargs` | `**kwargs` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.connectors/asyncconnectorexecutormixin ===

# AsyncConnectorExecutorMixin

**Package:** `flyte.connectors`

This mixin class is used to run the connector task locally, and it's only used for local execution.
Task should inherit from this class if the task can be run in the connector.

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.connectors > AsyncConnectorExecutorMixin > Methods > execute()** |  |

### execute()

```python
def execute(
    kwargs,
) -> typing.Any
```
| Parameter | Type | Description |
|-|-|-|
| `kwargs` | `**kwargs` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.connectors/connectorregistry ===

# ConnectorRegistry

**Package:** `flyte.connectors`

This is the registry for all connectors.
The connector service will look up the connector registry based on the task type and version.

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.connectors > ConnectorRegistry > Methods > get_connector()** |  |
| **Flyte SDK > Packages > flyte.connectors > ConnectorRegistry > Methods > register()** |  |

### get_connector()

```python
def get_connector(
    task_type_name: str,
    task_type_version: int,
) -> flyte.connectors._connector.AsyncConnector
```
| Parameter | Type | Description |
|-|-|-|
| `task_type_name` | `str` | |
| `task_type_version` | `int` | |

### register()

```python
def register(
    connector: flyte.connectors._connector.AsyncConnector,
    override: bool,
)
```
| Parameter | Type | Description |
|-|-|-|
| `connector` | `flyte.connectors._connector.AsyncConnector` | |
| `override` | `bool` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.connectors/connectorservice ===

# ConnectorService

**Package:** `flyte.connectors`

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.connectors > ConnectorService > Methods > run()** |  |

### run()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await ConnectorService.run.aio()`.
```python
def run(
    cls,
    port: int,
    prometheus_port: int,
    worker: int,
    timeout: int | None,
    modules: typing.Optional[typing.List[str]],
)
```
| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `port` | `int` | |
| `prometheus_port` | `int` | |
| `worker` | `int` | |
| `timeout` | `int \| None` | |
| `modules` | `typing.Optional[typing.List[str]]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.connectors/resource ===

# Resource

**Package:** `flyte.connectors`

This is the output resource of the job.

Attributes
----------
    phase : TaskExecution.Phase
        The phase of the job.
    message : Optional[str]
        The return message from the job.
    log_links : Optional[List[TaskLog]]
        The log links of the job. For example, the link to the BigQuery Console.
    outputs : Optional[Union[LiteralMap, typing.Dict[str, Any]]]
        The outputs of the job. If return python native types, the agent will convert them to flyte literals.
    custom_info : Optional[typing.Dict[str, Any]]
        The custom info of the job. For example, the job config.

## Parameters

```python
class Resource(
    phase: google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper,
    message: typing.Optional[str],
    log_links: typing.Optional[typing.List[flyteidl2.core.execution_pb2.TaskLog]],
    outputs: typing.Optional[typing.Dict[str, typing.Any]],
    custom_info: typing.Optional[typing.Dict[str, typing.Any]],
)
```
| Parameter | Type | Description |
|-|-|-|
| `phase` | `google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper` | |
| `message` | `typing.Optional[str]` | |
| `log_links` | `typing.Optional[typing.List[flyteidl2.core.execution_pb2.TaskLog]]` | |
| `outputs` | `typing.Optional[typing.Dict[str, typing.Any]]` | |
| `custom_info` | `typing.Optional[typing.Dict[str, typing.Any]]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.connectors/resourcemeta ===

# ResourceMeta

**Package:** `flyte.connectors`

This is the metadata for the job. For example, the id of the job.

## Parameters

```python
def ResourceMeta()
```
## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.connectors > ResourceMeta > Methods > decode()** | Decode the resource meta from bytes. |
| **Flyte SDK > Packages > flyte.connectors > ResourceMeta > Methods > encode()** | Encode the resource meta to bytes. |

### decode()

```python
def decode(
    data: bytes,
) -> ResourceMeta
```
Decode the resource meta from bytes.

| Parameter | Type | Description |
|-|-|-|
| `data` | `bytes` | |

### encode()

```python
def encode()
```
Encode the resource meta to bytes.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.connectors.utils ===

# flyte.connectors.utils

## Directory

### Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.connectors.utils > Methods > convert_to_flyte_phase()** | Convert the state from the connector to the phase in flyte. |
| **Flyte SDK > Packages > flyte.connectors.utils > Methods > is_terminal_phase()** | Return true if the phase is terminal. |
| **Flyte SDK > Packages > flyte.connectors.utils > Methods > print_metadata()** |  |

## Methods

#### convert_to_flyte_phase()

```python
def convert_to_flyte_phase(
    state: str,
) -> google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper
```
Convert the state from the connector to the phase in flyte.

| Parameter | Type | Description |
|-|-|-|
| `state` | `str` | |

#### is_terminal_phase()

```python
def is_terminal_phase(
    phase: google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper,
) -> bool
```
Return true if the phase is terminal.

| Parameter | Type | Description |
|-|-|-|
| `phase` | `google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper` | |

#### print_metadata()

```python
def print_metadata()
```


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.durable ===

# flyte.durable

Flyte durable utilities.

This module provides deterministic, crash-resilient replacements for time-related functions.
Usage of `time.time()`, `time.sleep()` or `asyncio.sleep()` introduces non-determinism.
The utilities here persist state across crashes and restarts, making workflows durable.

- `sleep` - a durable replacement for `time.sleep` / `asyncio.sleep`
- `time` - a durable replacement for `time.time`
- `now` - a durable replacement for `datetime.now`
## Directory

### Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.durable > Methods > now()** | Returns the current time for every unique invocation of durable_time. |
| **Flyte SDK > Packages > flyte.durable > Methods > sleep()** | durable_sleep enables the process to sleep for `seconds` seconds even if the process recovers from a crash. |
| **Flyte SDK > Packages > flyte.durable > Methods > time()** | Returns the current time for every unique invocation of durable_time. |

## Methods

#### now()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await now.aio()`.
```python
def now()
```
Returns the current time for every unique invocation of durable_time. If the same invocation is encountered
the previously returned time is returned again, ensuring determinism.
Similar to using `datetime.now()` just durable!
Returns: datetime.datetime

#### sleep()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await sleep.aio()`.
```python
def sleep(
    seconds: float,
)
```
durable_sleep enables the process to sleep for `seconds` seconds even if the process recovers from a crash.
This method can be invoked multiple times. If the process crashes, the invocation of durable_sleep will behave
like as-if the process has been sleeping since the first time this method was invoked.

```python
    import flyte.durable

    env = flyte.TaskEnvironment("env")

    @env.task
    async def main():
        # Do something
        my_work()
        # Now we need to sleep for 1 hour before proceeding.
        await flyte.durable.sleep.aio(3600)  # Even if process crashes, it will resume and only sleep for
                                              # 1 hour in agregate. If the scheduling takes longer, it
                                              # will simply return immediately.
        # thing to be done after 1 hour
        my_work()
```

| Parameter | Type | Description |
|-|-|-|
| `seconds` | `float` | float time to sleep for |

#### time()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await time.aio()`.
```python
def time()
```
Returns the current time for every unique invocation of durable_time. If the same invocation is encountered again
the previously returned time is returned again, ensuring determinism.
Similar to using `time.time()` just durable!
Returns: float


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors ===

# flyte.errors

Exceptions raised by Union.

These errors are raised when the underlying task execution fails, either because of a user error, system error or an
unknown error.
## Directory

### Errors

| Exception | Description |
|-|-|
| **Flyte SDK > Packages > flyte.errors > ActionAbortedError** | This error is raised when an action was aborted, externally. |
| **Flyte SDK > Packages > flyte.errors > ActionNotFoundError** | This error is raised when the user tries to access an action that does not exist. |
| **Flyte SDK > Packages > flyte.errors > BaseRuntimeError** | Base class for all Union runtime errors. |
| **Flyte SDK > Packages > flyte.errors > CodeBundleError** | This error is raised when the code bundle cannot be created, for example when no files are found to bundle. |
| **Flyte SDK > Packages > flyte.errors > CustomError** | This error is raised when the user raises a custom error. |
| **Flyte SDK > Packages > flyte.errors > DeploymentError** | This error is raised when the deployment of a task fails, or some preconditions for deployment are not met. |
| **Flyte SDK > Packages > flyte.errors > ImageBuildError** | This error is raised when the image build fails. |
| **Flyte SDK > Packages > flyte.errors > ImagePullBackOffError** | This error is raised when the image cannot be pulled. |
| **Flyte SDK > Packages > flyte.errors > InitializationError** | This error is raised when the Union system is tried to access without being initialized. |
| **Flyte SDK > Packages > flyte.errors > InlineIOMaxBytesBreached** | This error is raised when the inline IO max bytes limit is breached. |
| **Flyte SDK > Packages > flyte.errors > InvalidImageNameError** | This error is raised when the image name is invalid. |
| **Flyte SDK > Packages > flyte.errors > InvalidPackageError** | Raised when an invalid system package is detected during image build. |
| **Flyte SDK > Packages > flyte.errors > LogsNotYetAvailableError** | This error is raised when the logs are not yet available for a task. |
| **Flyte SDK > Packages > flyte.errors > ModuleLoadError** | This error is raised when the module cannot be loaded, either because it does not exist or because of a. |
| **Flyte SDK > Packages > flyte.errors > NonRecoverableError** | Raised when an error is encountered that is not recoverable. |
| **Flyte SDK > Packages > flyte.errors > NotInTaskContextError** | This error is raised when the user tries to access the task context outside of a task. |
| **Flyte SDK > Packages > flyte.errors > OOMError** | This error is raised when the underlying task execution fails because of an out-of-memory error. |
| **Flyte SDK > Packages > flyte.errors > OnlyAsyncIOSupportedError** | This error is raised when the user tries to use sync IO in an async task. |
| **Flyte SDK > Packages > flyte.errors > ParameterMaterializationError** | This error is raised when the user tries to use a Parameter in an App, that has delayed Materialization,. |
| **Flyte SDK > Packages > flyte.errors > PrimaryContainerNotFoundError** | This error is raised when the primary container is not found. |
| **Flyte SDK > Packages > flyte.errors > RemoteTaskNotFoundError** | This error is raised when the user tries to access a task that does not exist. |
| **Flyte SDK > Packages > flyte.errors > RemoteTaskUsageError** | This error is raised when the user tries to access a task that does not exist. |
| **Flyte SDK > Packages > flyte.errors > RestrictedTypeError** | This error is raised when the user uses a restricted type, for example current a Tuple is not supported for one. |
| **Flyte SDK > Packages > flyte.errors > RetriesExhaustedError** | This error is raised when the underlying task execution fails after all retries have been exhausted. |
| **Flyte SDK > Packages > flyte.errors > RuntimeDataValidationError** | This error is raised when the user tries to access a resource that does not exist or is invalid. |
| **Flyte SDK > Packages > flyte.errors > RuntimeSystemError** | This error is raised when the underlying task execution fails because of a system error. |
| **Flyte SDK > Packages > flyte.errors > RuntimeUnknownError** | This error is raised when the underlying task execution fails because of an unknown error. |
| **Flyte SDK > Packages > flyte.errors > RuntimeUserError** | This error is raised when the underlying task execution fails because of an error in the user's code. |
| **Flyte SDK > Packages > flyte.errors > SlowDownError** | This error is raised when the user tries to access a resource that does not exist or is invalid. |
| **Flyte SDK > Packages > flyte.errors > TaskInterruptedError** | This error is raised when the underlying task execution is interrupted. |
| **Flyte SDK > Packages > flyte.errors > TaskTimeoutError** | This error is raised when the underlying task execution runs for longer than the specified timeout. |
| **Flyte SDK > Packages > flyte.errors > TraceDoesNotAllowNestedTasksError** | This error is raised when the user tries to use a task from within a trace. |
| **Flyte SDK > Packages > flyte.errors > UnionRpcError** | This error is raised when communication with the Union server fails. |

### Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.errors > Methods > silence_polling_error()** | Suppress specific polling errors in the event loop. |

## Methods

#### silence_polling_error()

```python
def silence_polling_error(
    loop,
    context,
)
```
Suppress specific polling errors in the event loop.

| Parameter | Type | Description |
|-|-|-|
| `loop` |  | |
| `context` |  | |

## Subpages
- **Flyte SDK > Packages > flyte.errors > ActionAbortedError**
- **Flyte SDK > Packages > flyte.errors > ActionNotFoundError**
- **Flyte SDK > Packages > flyte.errors > BaseRuntimeError**
- **Flyte SDK > Packages > flyte.errors > CodeBundleError**
- **Flyte SDK > Packages > flyte.errors > CustomError**
- **Flyte SDK > Packages > flyte.errors > DeploymentError**
- **Flyte SDK > Packages > flyte.errors > ImageBuildError**
- **Flyte SDK > Packages > flyte.errors > ImagePullBackOffError**
- **Flyte SDK > Packages > flyte.errors > InitializationError**
- **Flyte SDK > Packages > flyte.errors > InlineIOMaxBytesBreached**
- **Flyte SDK > Packages > flyte.errors > InvalidImageNameError**
- **Flyte SDK > Packages > flyte.errors > InvalidPackageError**
- **Flyte SDK > Packages > flyte.errors > LogsNotYetAvailableError**
- **Flyte SDK > Packages > flyte.errors > ModuleLoadError**
- **Flyte SDK > Packages > flyte.errors > NonRecoverableError**
- **Flyte SDK > Packages > flyte.errors > NotInTaskContextError**
- **Flyte SDK > Packages > flyte.errors > OnlyAsyncIOSupportedError**
- **Flyte SDK > Packages > flyte.errors > OOMError**
- **Flyte SDK > Packages > flyte.errors > ParameterMaterializationError**
- **Flyte SDK > Packages > flyte.errors > PrimaryContainerNotFoundError**
- **Flyte SDK > Packages > flyte.errors > RemoteTaskNotFoundError**
- **Flyte SDK > Packages > flyte.errors > RemoteTaskUsageError**
- **Flyte SDK > Packages > flyte.errors > RestrictedTypeError**
- **Flyte SDK > Packages > flyte.errors > RetriesExhaustedError**
- **Flyte SDK > Packages > flyte.errors > RuntimeDataValidationError**
- **Flyte SDK > Packages > flyte.errors > RuntimeSystemError**
- **Flyte SDK > Packages > flyte.errors > RuntimeUnknownError**
- **Flyte SDK > Packages > flyte.errors > RuntimeUserError**
- **Flyte SDK > Packages > flyte.errors > SlowDownError**
- **Flyte SDK > Packages > flyte.errors > TaskInterruptedError**
- **Flyte SDK > Packages > flyte.errors > TaskTimeoutError**
- **Flyte SDK > Packages > flyte.errors > TraceDoesNotAllowNestedTasksError**
- **Flyte SDK > Packages > flyte.errors > UnionRpcError**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/actionabortederror ===

# ActionAbortedError

**Package:** `flyte.errors`

This error is raised when an action was aborted, externally. The parent action will raise this error.

## Parameters

```python
class ActionAbortedError(
    message: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `message` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/actionnotfounderror ===

# ActionNotFoundError

**Package:** `flyte.errors`

This error is raised when the user tries to access an action that does not exist.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/baseruntimeerror ===

# BaseRuntimeError

**Package:** `flyte.errors`

Base class for all Union runtime errors. These errors are raised when the underlying task execution fails, either
because of a user error, system error or an unknown error.

## Parameters

```python
class BaseRuntimeError(
    code: str,
    kind: typing.Literal['system', 'unknown', 'user'],
    root_cause_message: str,
    worker: str | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `code` | `str` | |
| `kind` | `typing.Literal['system', 'unknown', 'user']` | |
| `root_cause_message` | `str` | |
| `worker` | `str \| None` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/codebundleerror ===

# CodeBundleError

**Package:** `flyte.errors`

This error is raised when the code bundle cannot be created, for example when no files are found to bundle.

## Parameters

```python
class CodeBundleError(
    message: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `message` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/customerror ===

# CustomError

**Package:** `flyte.errors`

This error is raised when the user raises a custom error.

## Parameters

```python
class CustomError(
    code: str,
    message: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `code` | `str` | |
| `message` | `str` | |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.errors > CustomError > Methods > from_exception()** | Create a CustomError from an exception. |

### from_exception()

```python
def from_exception(
    e: Exception,
)
```
Create a CustomError from an exception. The exception's class name is used as the error code and the exception
message is used as the error message.

| Parameter | Type | Description |
|-|-|-|
| `e` | `Exception` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/deploymenterror ===

# DeploymentError

**Package:** `flyte.errors`

This error is raised when the deployment of a task fails, or some preconditions for deployment are not met.

## Parameters

```python
class DeploymentError(
    message: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `message` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/imagebuilderror ===

# ImageBuildError

**Package:** `flyte.errors`

This error is raised when the image build fails.

## Parameters

```python
class ImageBuildError(
    message: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `message` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/imagepullbackofferror ===

# ImagePullBackOffError

**Package:** `flyte.errors`

This error is raised when the image cannot be pulled.

## Parameters

```python
class ImagePullBackOffError(
    code: str,
    message: str,
    worker: str | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `code` | `str` | |
| `message` | `str` | |
| `worker` | `str \| None` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/initializationerror ===

# InitializationError

**Package:** `flyte.errors`

This error is raised when the Union system is tried to access without being initialized.

## Parameters

```python
class InitializationError(
    code: str,
    kind: typing.Literal['system', 'unknown', 'user'],
    root_cause_message: str,
    worker: str | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `code` | `str` | |
| `kind` | `typing.Literal['system', 'unknown', 'user']` | |
| `root_cause_message` | `str` | |
| `worker` | `str \| None` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/inlineiomaxbytesbreached ===

# InlineIOMaxBytesBreached

**Package:** `flyte.errors`

This error is raised when the inline IO max bytes limit is breached.
This can be adjusted per task by setting max_inline_io_bytes in the task definition.

## Parameters

```python
class InlineIOMaxBytesBreached(
    message: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `message` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/invalidimagenameerror ===

# InvalidImageNameError

**Package:** `flyte.errors`

This error is raised when the image name is invalid.

## Parameters

```python
class InvalidImageNameError(
    code: str,
    message: str,
    worker: str | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `code` | `str` | |
| `message` | `str` | |
| `worker` | `str \| None` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/invalidpackageerror ===

# InvalidPackageError

**Package:** `flyte.errors`

Raised when an invalid system package is detected during image build.

## Parameters

```python
class InvalidPackageError(
    package_name: str,
    original_error: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `package_name` | `str` | |
| `original_error` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/logsnotyetavailableerror ===

# LogsNotYetAvailableError

**Package:** `flyte.errors`

This error is raised when the logs are not yet available for a task.

## Parameters

```python
class LogsNotYetAvailableError(
    message: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `message` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/moduleloaderror ===

# ModuleLoadError

**Package:** `flyte.errors`

This error is raised when the module cannot be loaded, either because it does not exist or because of a
 syntax error.

## Parameters

```python
class ModuleLoadError(
    message: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `message` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/nonrecoverableerror ===

# NonRecoverableError

**Package:** `flyte.errors`

Raised when an error is encountered that is not recoverable. Retries are irrelevant.

## Parameters

```python
class NonRecoverableError(
    message: str,
    code: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `message` | `str` | |
| `code` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/notintaskcontexterror ===

# NotInTaskContextError

**Package:** `flyte.errors`

This error is raised when the user tries to access the task context outside of a task.

## Parameters

```python
class NotInTaskContextError(
    code: str,
    message: str,
    worker: str | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `code` | `str` | |
| `message` | `str` | |
| `worker` | `str \| None` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/onlyasynciosupportederror ===

# OnlyAsyncIOSupportedError

**Package:** `flyte.errors`

This error is raised when the user tries to use sync IO in an async task.

## Parameters

```python
class OnlyAsyncIOSupportedError(
    message: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `message` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/oomerror ===

# OOMError

**Package:** `flyte.errors`

This error is raised when the underlying task execution fails because of an out-of-memory error.

## Parameters

```python
class OOMError(
    code: str,
    message: str,
    worker: str | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `code` | `str` | |
| `message` | `str` | |
| `worker` | `str \| None` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/parametermaterializationerror ===

# ParameterMaterializationError

**Package:** `flyte.errors`

This error is raised when the user tries to use a Parameter in an App, that has delayed Materialization,
but the materialization fails.

## Parameters

```python
class ParameterMaterializationError(
    message: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `message` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/primarycontainernotfounderror ===

# PrimaryContainerNotFoundError

**Package:** `flyte.errors`

This error is raised when the primary container is not found.

## Parameters

```python
class PrimaryContainerNotFoundError(
    code: str,
    message: str,
    worker: str | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `code` | `str` | |
| `message` | `str` | |
| `worker` | `str \| None` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/remotetasknotfounderror ===

# RemoteTaskNotFoundError

**Package:** `flyte.errors`

This error is raised when the user tries to access a task that does not exist.

## Parameters

```python
class RemoteTaskNotFoundError(
    message: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `message` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/remotetaskusageerror ===

# RemoteTaskUsageError

**Package:** `flyte.errors`

This error is raised when the user tries to access a task that does not exist.

## Parameters

```python
class RemoteTaskUsageError(
    message: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `message` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/restrictedtypeerror ===

# RestrictedTypeError

**Package:** `flyte.errors`

This error is raised when the user uses a restricted type, for example current a Tuple is not supported for one
 value.

## Parameters

```python
class RestrictedTypeError(
    message: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `message` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/retriesexhaustederror ===

# RetriesExhaustedError

**Package:** `flyte.errors`

This error is raised when the underlying task execution fails after all retries have been exhausted.

## Parameters

```python
class RetriesExhaustedError(
    code: str,
    message: str,
    worker: str | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `code` | `str` | |
| `message` | `str` | |
| `worker` | `str \| None` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/runtimedatavalidationerror ===

# RuntimeDataValidationError

**Package:** `flyte.errors`

This error is raised when the user tries to access a resource that does not exist or is invalid.

## Parameters

```python
class RuntimeDataValidationError(
    var: str,
    e: Exception | str,
    task_name: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `var` | `str` | |
| `e` | `Exception \| str` | |
| `task_name` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/runtimesystemerror ===

# RuntimeSystemError

**Package:** `flyte.errors`

This error is raised when the underlying task execution fails because of a system error. This could be a bug in the
Union system or a bug in the user's code.

## Parameters

```python
class RuntimeSystemError(
    code: str,
    message: str,
    worker: str | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `code` | `str` | |
| `message` | `str` | |
| `worker` | `str \| None` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/runtimeunknownerror ===

# RuntimeUnknownError

**Package:** `flyte.errors`

This error is raised when the underlying task execution fails because of an unknown error.

## Parameters

```python
class RuntimeUnknownError(
    code: str,
    message: str,
    worker: str | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `code` | `str` | |
| `message` | `str` | |
| `worker` | `str \| None` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/runtimeusererror ===

# RuntimeUserError

**Package:** `flyte.errors`

This error is raised when the underlying task execution fails because of an error in the user's code.

## Parameters

```python
class RuntimeUserError(
    code: str,
    message: str,
    worker: str | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `code` | `str` | |
| `message` | `str` | |
| `worker` | `str \| None` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/slowdownerror ===

# SlowDownError

**Package:** `flyte.errors`

This error is raised when the user tries to access a resource that does not exist or is invalid.

## Parameters

```python
class SlowDownError(
    message: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `message` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/taskinterruptederror ===

# TaskInterruptedError

**Package:** `flyte.errors`

This error is raised when the underlying task execution is interrupted.

## Parameters

```python
class TaskInterruptedError(
    code: str,
    message: str,
    worker: str | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `code` | `str` | |
| `message` | `str` | |
| `worker` | `str \| None` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/tasktimeouterror ===

# TaskTimeoutError

**Package:** `flyte.errors`

This error is raised when the underlying task execution runs for longer than the specified timeout.

## Parameters

```python
class TaskTimeoutError(
    message: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `message` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/tracedoesnotallownestedtaskserror ===

# TraceDoesNotAllowNestedTasksError

**Package:** `flyte.errors`

This error is raised when the user tries to use a task from within a trace. Tasks can be nested under tasks
not traces.

## Parameters

```python
class TraceDoesNotAllowNestedTasksError(
    message: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `message` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.errors/unionrpcerror ===

# UnionRpcError

**Package:** `flyte.errors`

This error is raised when communication with the Union server fails.

## Parameters

```python
class UnionRpcError(
    code: str,
    message: str,
    worker: str | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `code` | `str` | |
| `message` | `str` | |
| `worker` | `str \| None` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.extend ===

# flyte.extend

## Directory

### Classes

| Class | Description |
|-|-|
| **Flyte SDK > Packages > flyte.extend > AsyncFunctionTaskTemplate** | A task template that wraps an asynchronous functions. |
| **Flyte SDK > Packages > flyte.extend > ImageBuildEngine** | ImageBuildEngine contains a list of builders that can be used to build an ImageSpec. |
| **Flyte SDK > Packages > flyte.extend > TaskTemplate** | Task template is a template for a task that can be executed. |

### Protocols

| Protocol | Description |
|-|-|
| **Flyte SDK > Packages > flyte.extend > ImageBuilder** |  |
| **Flyte SDK > Packages > flyte.extend > ImageChecker** |  |

### Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.extend > Methods > download_code_bundle()** | Downloads the code bundle if it is not already downloaded. |
| **Flyte SDK > Packages > flyte.extend > Methods > get_proto_resources()** | Get main resources IDL representation from the resources object. |
| **Flyte SDK > Packages > flyte.extend > Methods > is_initialized()** | Check if the system has been initialized. |
| **Flyte SDK > Packages > flyte.extend > Methods > lazy_module()** | This function is used to lazily import modules. |
| **Flyte SDK > Packages > flyte.extend > Methods > pod_spec_from_resources()** |  |

### Variables

| Property | Type | Description |
|-|-|-|
| `PRIMARY_CONTAINER_DEFAULT_NAME` | `str` |  |
| `TaskPluginRegistry` | `_Registry` |  |

## Methods

#### download_code_bundle()

```python
def download_code_bundle(
    code_bundle: flyte.models.CodeBundle,
) -> flyte.models.CodeBundle
```
Downloads the code bundle if it is not already downloaded.

| Parameter | Type | Description |
|-|-|-|
| `code_bundle` | `flyte.models.CodeBundle` | The code bundle to download. |

**Returns:** The code bundle with the downloaded path.

#### get_proto_resources()

```python
def get_proto_resources(
    resources: flyte._resources.Resources | None,
) -> typing.Optional[flyteidl2.core.tasks_pb2.Resources]
```
Get main resources IDL representation from the resources object

| Parameter | Type | Description |
|-|-|-|
| `resources` | `flyte._resources.Resources \| None` | User facing Resources object containing potentially both requests and limits |

**Returns:** The given resources as requests and limits

#### is_initialized()

```python
def is_initialized()
```
Check if the system has been initialized.

**Returns:** True if initialized, False otherwise

#### lazy_module()

```python
def lazy_module(
    fullname,
)
```
This function is used to lazily import modules.  It is used in the following way:
.. code-block:: python
    from flytekit.lazy_import import lazy_module
    sklearn = lazy_module("sklearn")
    sklearn.svm.SVC()

| Parameter | Type | Description |
|-|-|-|
| `fullname` |  | |

#### pod_spec_from_resources()

```python
def pod_spec_from_resources(
    primary_container_name: str,
    requests: typing.Optional[flyte._resources.Resources],
    limits: typing.Optional[flyte._resources.Resources],
    k8s_gpu_resource_key: str,
) -> V1PodSpec
```
| Parameter | Type | Description |
|-|-|-|
| `primary_container_name` | `str` | |
| `requests` | `typing.Optional[flyte._resources.Resources]` | |
| `limits` | `typing.Optional[flyte._resources.Resources]` | |
| `k8s_gpu_resource_key` | `str` | |

## Subpages
- **Flyte SDK > Packages > flyte.extend > AsyncFunctionTaskTemplate**
- **Flyte SDK > Packages > flyte.extend > ImageBuildEngine**
- **Flyte SDK > Packages > flyte.extend > ImageBuilder**
- **Flyte SDK > Packages > flyte.extend > ImageChecker**
- **Flyte SDK > Packages > flyte.extend > TaskTemplate**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.extend/asyncfunctiontasktemplate ===

# AsyncFunctionTaskTemplate

**Package:** `flyte.extend`

A task template that wraps an asynchronous functions. This is automatically created when an asynchronous function
is decorated with the task decorator.

## Parameters

```python
class AsyncFunctionTaskTemplate(
    name: str,
    interface: NativeInterface,
    short_name: str,
    task_type: str,
    task_type_version: int,
    image: Union[str, Image, Literal['auto']] | None,
    resources: Optional[Resources],
    cache: CacheRequest,
    interruptible: bool,
    retries: Union[int, RetryStrategy],
    reusable: Union[ReusePolicy, None],
    docs: Optional[Documentation],
    env_vars: Optional[Dict[str, str]],
    secrets: Optional[SecretRequest],
    timeout: Optional[TimeoutType],
    pod_template: Optional[Union[str, PodTemplate]],
    report: bool,
    queue: Optional[str],
    debuggable: bool,
    parent_env: Optional[weakref.ReferenceType[TaskEnvironment]],
    parent_env_name: Optional[str],
    max_inline_io_bytes: int,
    triggers: Tuple[Trigger, ...],
    links: Tuple[Link, ...],
    _call_as_synchronous: bool,
    func: F,
    plugin_config: Optional[Any],
    task_resolver: Optional[Any],
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |
| `interface` | `NativeInterface` | |
| `short_name` | `str` | |
| `task_type` | `str` | |
| `task_type_version` | `int` | |
| `image` | `Union[str, Image, Literal['auto']] \| None` | |
| `resources` | `Optional[Resources]` | |
| `cache` | `CacheRequest` | |
| `interruptible` | `bool` | |
| `retries` | `Union[int, RetryStrategy]` | |
| `reusable` | `Union[ReusePolicy, None]` | |
| `docs` | `Optional[Documentation]` | |
| `env_vars` | `Optional[Dict[str, str]]` | |
| `secrets` | `Optional[SecretRequest]` | |
| `timeout` | `Optional[TimeoutType]` | |
| `pod_template` | `Optional[Union[str, PodTemplate]]` | |
| `report` | `bool` | |
| `queue` | `Optional[str]` | |
| `debuggable` | `bool` | |
| `parent_env` | `Optional[weakref.ReferenceType[TaskEnvironment]]` | |
| `parent_env_name` | `Optional[str]` | |
| `max_inline_io_bytes` | `int` | |
| `triggers` | `Tuple[Trigger, ...]` | |
| `links` | `Tuple[Link, ...]` | |
| `_call_as_synchronous` | `bool` | |
| `func` | `F` | |
| `plugin_config` | `Optional[Any]` | |
| `task_resolver` | `Optional[Any]` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `json_schema` | `None` | JSON schema for the task inputs, following the Flyte standard.  Delegates to NativeInterface.json_schema, which uses the type engine to produce a LiteralType per input and converts to JSON schema. |
| `native_interface` | `None` |  |
| `source_file` | `None` | Returns the source file of the function, if available. This is useful for debugging and tracing. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.extend > AsyncFunctionTaskTemplate > Methods > aio()** | The aio function allows executing "sync" tasks, in an async context. |
| **Flyte SDK > Packages > flyte.extend > AsyncFunctionTaskTemplate > Methods > config()** | Returns additional configuration for the task. |
| **Flyte SDK > Packages > flyte.extend > AsyncFunctionTaskTemplate > Methods > container_args()** | Returns the container args for the task. |
| **Flyte SDK > Packages > flyte.extend > AsyncFunctionTaskTemplate > Methods > custom_config()** | Returns additional configuration for the task. |
| **Flyte SDK > Packages > flyte.extend > AsyncFunctionTaskTemplate > Methods > data_loading_config()** | This configuration allows executing raw containers in Flyte using the Flyte CoPilot system. |
| **Flyte SDK > Packages > flyte.extend > AsyncFunctionTaskTemplate > Methods > execute()** | This is the execute method that will be called when the task is invoked. |
| **Flyte SDK > Packages > flyte.extend > AsyncFunctionTaskTemplate > forward()** | Think of this as a local execute method for your task. |
| **Flyte SDK > Packages > flyte.extend > AsyncFunctionTaskTemplate > override()** | Override various parameters of the task template. |
| **Flyte SDK > Packages > flyte.extend > AsyncFunctionTaskTemplate > post()** | This is the postexecute function that will be. |
| **Flyte SDK > Packages > flyte.extend > AsyncFunctionTaskTemplate > pre()** | This is the preexecute function that will be. |
| **Flyte SDK > Packages > flyte.extend > AsyncFunctionTaskTemplate > sql()** | Returns the SQL for the task. |

### aio()

```python
def aio(
    args: *args,
    kwargs: **kwargs,
) -> Coroutine[Any, Any, R] | R
```
The aio function allows executing "sync" tasks, in an async context. This helps with migrating v1 defined sync
tasks to be used within an asyncio parent task.
This function will also re-raise exceptions from the underlying task.

```python
@env.task
def my_legacy_task(x: int) -> int:
    return x

@env.task
async def my_new_parent_task(n: int) -> List[int]:
    collect = []
    for x in range(n):
        collect.append(my_legacy_task.aio(x))
    return asyncio.gather(*collect)
```

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### config()

```python
def config(
    sctx: SerializationContext,
) -> Dict[str, str]
```
Returns additional configuration for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### container_args()

```python
def container_args(
    serialize_context: SerializationContext,
) -> List[str]
```
Returns the container args for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `serialize_context` | `SerializationContext` | |

### custom_config()

```python
def custom_config(
    sctx: SerializationContext,
) -> Dict[str, str]
```
Returns additional configuration for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### data_loading_config()

```python
def data_loading_config(
    sctx: SerializationContext,
) -> DataLoadingConfig
```
This configuration allows executing raw containers in Flyte using the Flyte CoPilot system
Flyte CoPilot, eliminates the needs of sdk inside the container. Any inputs required by the users container
are side-loaded in the input_path
Any outputs generated by the user container - within output_path are automatically uploaded

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### execute()

```python
def execute(
    args: *args,
    kwargs: **kwargs,
) -> R
```
This is the execute method that will be called when the task is invoked. It will call the actual function.
# TODO We may need to keep this as the bare func execute, and need a pre and post execute some other func.

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### forward()

```python
def forward(
    args: *args,
    kwargs: **kwargs,
) -> Coroutine[Any, Any, R] | R
```
Think of this as a local execute method for your task. This function will be invoked by the __call__ method
when not in a Flyte task execution context.  See the implementation below for an example.

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### override()

```python
def override(
    short_name: Optional[str],
    resources: Optional[Resources],
    cache: Optional[CacheRequest],
    retries: Union[int, RetryStrategy],
    timeout: Optional[TimeoutType],
    reusable: Union[ReusePolicy, Literal['off'], None],
    env_vars: Optional[Dict[str, str]],
    secrets: Optional[SecretRequest],
    max_inline_io_bytes: int | None,
    pod_template: Optional[Union[str, PodTemplate]],
    queue: Optional[str],
    interruptible: Optional[bool],
    links: Tuple[Link, ...],
    kwargs: **kwargs,
) -> TaskTemplate
```
Override various parameters of the task template. This allows for dynamic configuration of the task
when it is called, such as changing the image, resources, cache policy, etc.

| Parameter | Type | Description |
|-|-|-|
| `short_name` | `Optional[str]` | Optional override for the short name of the task. |
| `resources` | `Optional[Resources]` | Optional override for the resources to use for the task. |
| `cache` | `Optional[CacheRequest]` | Optional override for the cache policy for the task. |
| `retries` | `Union[int, RetryStrategy]` | Optional override for the number of retries for the task. |
| `timeout` | `Optional[TimeoutType]` | Optional override for the timeout for the task. |
| `reusable` | `Union[ReusePolicy, Literal['off'], None]` | Optional override for the reusability policy for the task. |
| `env_vars` | `Optional[Dict[str, str]]` | Optional override for the environment variables to set for the task. |
| `secrets` | `Optional[SecretRequest]` | Optional override for the secrets that will be injected into the task at runtime. |
| `max_inline_io_bytes` | `int \| None` | Optional override for the maximum allowed size (in bytes) for all inputs and outputs passed directly to the task. |
| `pod_template` | `Optional[Union[str, PodTemplate]]` | Optional override for the pod template to use for the task. |
| `queue` | `Optional[str]` | Optional override for the queue to use for the task. |
| `interruptible` | `Optional[bool]` | Optional override for the interruptible policy for the task. |
| `links` | `Tuple[Link, ...]` | Optional override for the Links associated with the task. |
| `kwargs` | `**kwargs` | Additional keyword arguments for further overrides. Some fields like name, image, docs, and interface cannot be overridden. |

**Returns:** A new TaskTemplate instance with the overridden parameters.

### post()

```python
def post(
    return_vals: Any,
) -> Any
```
This is the postexecute function that will be
called after the task is executed

| Parameter | Type | Description |
|-|-|-|
| `return_vals` | `Any` | |

### pre()

```python
def pre(
    args,
    kwargs,
) -> Dict[str, Any]
```
This is the preexecute function that will be
called before the task is executed

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### sql()

```python
def sql(
    sctx: SerializationContext,
) -> Optional[str]
```
Returns the SQL for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.extend/imagebuildengine ===

# ImageBuildEngine

**Package:** `flyte.extend`

ImageBuildEngine contains a list of builders that can be used to build an ImageSpec.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.extend/imagebuilder ===

# ImageBuilder

**Package:** `flyte.extend`

```python
protocol ImageBuilder()
```
## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.extend > ImageBuilder > Methods > build_image()** |  |
| **Flyte SDK > Packages > flyte.extend > ImageBuilder > Methods > get_checkers()** | Returns ImageCheckers that can be used to check if the image exists in the registry. |

### build_image()

```python
def build_image(
    image: Image,
    dry_run: bool,
    wait: bool,
    force: bool,
) -> 'ImageBuild'
```
| Parameter | Type | Description |
|-|-|-|
| `image` | `Image` | |
| `dry_run` | `bool` | |
| `wait` | `bool` | |
| `force` | `bool` | |

### get_checkers()

```python
def get_checkers()
```
Returns ImageCheckers that can be used to check if the image exists in the registry.
If None, then use the default checkers.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.extend/imagechecker ===

# ImageChecker

**Package:** `flyte.extend`

```python
protocol ImageChecker()
```
## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.extend > ImageChecker > Methods > image_exists()** |  |

### image_exists()

```python
def image_exists(
    repository: str,
    tag: str,
    arch: Tuple[Architecture, ...],
) -> Optional[str]
```
| Parameter | Type | Description |
|-|-|-|
| `repository` | `str` | |
| `tag` | `str` | |
| `arch` | `Tuple[Architecture, ...]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.extend/tasktemplate ===

# TaskTemplate

**Package:** `flyte.extend`

Task template is a template for a task that can be executed. It defines various parameters for the task, which
can be defined statically at the time of task definition or dynamically at the time of task invocation using
the override method.

Example usage:
```python
@task(name="my_task", image="my_image", resources=Resources(cpu="1", memory="1Gi"))
def my_task():
    pass
```

## Parameters

```python
class TaskTemplate(
    name: str,
    interface: NativeInterface,
    short_name: str,
    task_type: str,
    task_type_version: int,
    image: Union[str, Image, Literal['auto']] | None,
    resources: Optional[Resources],
    cache: CacheRequest,
    interruptible: bool,
    retries: Union[int, RetryStrategy],
    reusable: Union[ReusePolicy, None],
    docs: Optional[Documentation],
    env_vars: Optional[Dict[str, str]],
    secrets: Optional[SecretRequest],
    timeout: Optional[TimeoutType],
    pod_template: Optional[Union[str, PodTemplate]],
    report: bool,
    queue: Optional[str],
    debuggable: bool,
    parent_env: Optional[weakref.ReferenceType[TaskEnvironment]],
    parent_env_name: Optional[str],
    max_inline_io_bytes: int,
    triggers: Tuple[Trigger, ...],
    links: Tuple[Link, ...],
    _call_as_synchronous: bool,
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | Optional The name of the task (defaults to the function name) |
| `interface` | `NativeInterface` | |
| `short_name` | `str` | |
| `task_type` | `str` | Router type for the task, this is used to determine how the task will be executed. This is usually set to match with th execution plugin. |
| `task_type_version` | `int` | |
| `image` | `Union[str, Image, Literal['auto']] \| None` | Optional The image to use for the task, if set to "auto" will use the default image for the python version with flyte installed |
| `resources` | `Optional[Resources]` | Optional The resources to use for the task |
| `cache` | `CacheRequest` | Optional The cache policy for the task, defaults to auto, which will cache the results of the task. |
| `interruptible` | `bool` | Optional The interruptible policy for the task, defaults to False, which means the task will not be scheduled on interruptible nodes. If set to True, the task will be scheduled on interruptible nodes, and the code should handle interruptions and resumptions. |
| `retries` | `Union[int, RetryStrategy]` | Optional The number of retries for the task, defaults to 0, which means no retries. |
| `reusable` | `Union[ReusePolicy, None]` | Optional The reusability policy for the task, defaults to None, which means the task environment will not be reused across task invocations. |
| `docs` | `Optional[Documentation]` | Optional The documentation for the task, if not provided the function docstring will be used. |
| `env_vars` | `Optional[Dict[str, str]]` | Optional The environment variables to set for the task. |
| `secrets` | `Optional[SecretRequest]` | Optional The secrets that will be injected into the task at runtime. |
| `timeout` | `Optional[TimeoutType]` | Optional The timeout for the task. |
| `pod_template` | `Optional[Union[str, PodTemplate]]` | Optional The pod template to use for the task. |
| `report` | `bool` | Optional Whether to report the task execution to the Flyte console, defaults to False. |
| `queue` | `Optional[str]` | Optional The queue to use for the task. If not provided, the default queue will be used. |
| `debuggable` | `bool` | Optional Whether the task supports debugging capabilities, defaults to False. |
| `parent_env` | `Optional[weakref.ReferenceType[TaskEnvironment]]` | |
| `parent_env_name` | `Optional[str]` | |
| `max_inline_io_bytes` | `int` | Maximum allowed size (in bytes) for all inputs and outputs passed directly to the task (e.g., primitives, strings, dicts). Does not apply to files, directories, or dataframes. |
| `triggers` | `Tuple[Trigger, ...]` | |
| `links` | `Tuple[Link, ...]` | |
| `_call_as_synchronous` | `bool` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `native_interface` | `None` |  |
| `source_file` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.extend > TaskTemplate > Methods > aio()** | The aio function allows executing "sync" tasks, in an async context. |
| **Flyte SDK > Packages > flyte.extend > TaskTemplate > Methods > config()** | Returns additional configuration for the task. |
| **Flyte SDK > Packages > flyte.extend > TaskTemplate > Methods > container_args()** | Returns the container args for the task. |
| **Flyte SDK > Packages > flyte.extend > TaskTemplate > Methods > custom_config()** | Returns additional configuration for the task. |
| **Flyte SDK > Packages > flyte.extend > TaskTemplate > Methods > data_loading_config()** | This configuration allows executing raw containers in Flyte using the Flyte CoPilot system. |
| **Flyte SDK > Packages > flyte.extend > TaskTemplate > Methods > execute()** | This is the pure python function that will be executed when the task is called. |
| **Flyte SDK > Packages > flyte.extend > TaskTemplate > Methods > forward()** | Think of this as a local execute method for your task. |
| **Flyte SDK > Packages > flyte.extend > TaskTemplate > Methods > override()** | Override various parameters of the task template. |
| **Flyte SDK > Packages > flyte.extend > TaskTemplate > Methods > post()** | This is the postexecute function that will be. |
| **Flyte SDK > Packages > flyte.extend > TaskTemplate > Methods > pre()** | This is the preexecute function that will be. |
| **Flyte SDK > Packages > flyte.extend > TaskTemplate > Methods > sql()** | Returns the SQL for the task. |

### aio()

```python
def aio(
    args: *args,
    kwargs: **kwargs,
) -> Coroutine[Any, Any, R] | R
```
The aio function allows executing "sync" tasks, in an async context. This helps with migrating v1 defined sync
tasks to be used within an asyncio parent task.
This function will also re-raise exceptions from the underlying task.

```python
@env.task
def my_legacy_task(x: int) -> int:
    return x

@env.task
async def my_new_parent_task(n: int) -> List[int]:
    collect = []
    for x in range(n):
        collect.append(my_legacy_task.aio(x))
    return asyncio.gather(*collect)
```

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### config()

```python
def config(
    sctx: SerializationContext,
) -> Dict[str, str]
```
Returns additional configuration for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### container_args()

```python
def container_args(
    sctx: SerializationContext,
) -> List[str]
```
Returns the container args for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### custom_config()

```python
def custom_config(
    sctx: SerializationContext,
) -> Dict[str, str]
```
Returns additional configuration for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### data_loading_config()

```python
def data_loading_config(
    sctx: SerializationContext,
) -> DataLoadingConfig
```
This configuration allows executing raw containers in Flyte using the Flyte CoPilot system
Flyte CoPilot, eliminates the needs of sdk inside the container. Any inputs required by the users container
are side-loaded in the input_path
Any outputs generated by the user container - within output_path are automatically uploaded

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### execute()

```python
def execute(
    args,
    kwargs,
) -> Any
```
This is the pure python function that will be executed when the task is called.

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### forward()

```python
def forward(
    args: *args,
    kwargs: **kwargs,
) -> Coroutine[Any, Any, R] | R
```
Think of this as a local execute method for your task. This function will be invoked by the __call__ method
when not in a Flyte task execution context.  See the implementation below for an example.

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### override()

```python
def override(
    short_name: Optional[str],
    resources: Optional[Resources],
    cache: Optional[CacheRequest],
    retries: Union[int, RetryStrategy],
    timeout: Optional[TimeoutType],
    reusable: Union[ReusePolicy, Literal['off'], None],
    env_vars: Optional[Dict[str, str]],
    secrets: Optional[SecretRequest],
    max_inline_io_bytes: int | None,
    pod_template: Optional[Union[str, PodTemplate]],
    queue: Optional[str],
    interruptible: Optional[bool],
    links: Tuple[Link, ...],
    kwargs: **kwargs,
) -> TaskTemplate
```
Override various parameters of the task template. This allows for dynamic configuration of the task
when it is called, such as changing the image, resources, cache policy, etc.

| Parameter | Type | Description |
|-|-|-|
| `short_name` | `Optional[str]` | Optional override for the short name of the task. |
| `resources` | `Optional[Resources]` | Optional override for the resources to use for the task. |
| `cache` | `Optional[CacheRequest]` | Optional override for the cache policy for the task. |
| `retries` | `Union[int, RetryStrategy]` | Optional override for the number of retries for the task. |
| `timeout` | `Optional[TimeoutType]` | Optional override for the timeout for the task. |
| `reusable` | `Union[ReusePolicy, Literal['off'], None]` | Optional override for the reusability policy for the task. |
| `env_vars` | `Optional[Dict[str, str]]` | Optional override for the environment variables to set for the task. |
| `secrets` | `Optional[SecretRequest]` | Optional override for the secrets that will be injected into the task at runtime. |
| `max_inline_io_bytes` | `int \| None` | Optional override for the maximum allowed size (in bytes) for all inputs and outputs passed directly to the task. |
| `pod_template` | `Optional[Union[str, PodTemplate]]` | Optional override for the pod template to use for the task. |
| `queue` | `Optional[str]` | Optional override for the queue to use for the task. |
| `interruptible` | `Optional[bool]` | Optional override for the interruptible policy for the task. |
| `links` | `Tuple[Link, ...]` | Optional override for the Links associated with the task. |
| `kwargs` | `**kwargs` | Additional keyword arguments for further overrides. Some fields like name, image, docs, and interface cannot be overridden. |

**Returns:** A new TaskTemplate instance with the overridden parameters.

### post()

```python
def post(
    return_vals: Any,
) -> Any
```
This is the postexecute function that will be
called after the task is executed

| Parameter | Type | Description |
|-|-|-|
| `return_vals` | `Any` | |

### pre()

```python
def pre(
    args,
    kwargs,
) -> Dict[str, Any]
```
This is the preexecute function that will be
called before the task is executed

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### sql()

```python
def sql(
    sctx: SerializationContext,
) -> Optional[str]
```
Returns the SQL for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.extras ===

# flyte.extras

Flyte extras package.
This package provides various utilities that make it possible to build highly customized workflows.

1. ContainerTask: Execute arbitrary pre-containerized applications, without needing the `flyte-sdk`
                  to be installed. This extra uses `flyte copilot` system to inject inputs and slurp
                  outputs from the container run.

2. DynamicBatcher / TokenBatcher: Maximize resource utilization by batching work from many concurrent
                   producers through a single async processing function.  DynamicBatcher is the
                   general-purpose base; TokenBatcher is a convenience subclass for token-budgeted
                   LLM inference with reusable containers.
## Directory

### Classes

| Class | Description |
|-|-|
| **Flyte SDK > Packages > flyte.extras > BatchStats** | Monitoring statistics exposed by `DynamicBatcher. |
| [`ContainerTask`](containertask/page.md) | This is an intermediate class that represents Flyte Tasks that run a container at execution time. |
| [`DynamicBatcher`](dynamicbatcher/page.md) | Batches records from many concurrent producers and runs them through. |
| [`Prompt`](prompt/page.md) | Simple prompt record with built-in token estimation. |
| [`TokenBatcher`](tokenbatcher/page.md) | Token-aware batcher for LLM inference workloads. |

### Protocols

| Protocol | Description |
|-|-|
| [`CostEstimator`](costestimator/page.md) | Protocol for records that can estimate their own processing cost. |
| [`TokenEstimator`](tokenestimator/page.md) | Protocol for records that can estimate their own token count. |

## Subpages
- **Flyte SDK > Packages > flyte.extras > BatchStats**
- **Flyte SDK > Packages > flyte.extras > ContainerTask**
- **Flyte SDK > Packages > flyte.extras > CostEstimator**
- **Flyte SDK > Packages > flyte.extras > DynamicBatcher**
- **Flyte SDK > Packages > flyte.extras > Prompt**
- **Flyte SDK > Packages > flyte.extras > TokenBatcher**
- **Flyte SDK > Packages > flyte.extras > TokenEstimator**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.extras/batchstats ===

# BatchStats

**Package:** `flyte.extras`

Monitoring statistics exposed by `DynamicBatcher.stats`.

## Parameters

```python
class BatchStats(
    total_submitted: int,
    total_completed: int,
    total_batches: int,
    total_batch_cost: int,
    avg_batch_size: float,
    avg_batch_cost: float,
    busy_time_s: float,
    idle_time_s: float,
)
```
| Parameter | Type | Description |
|-|-|-|
| `total_submitted` | `int` | Total records submitted via `submit`. |
| `total_completed` | `int` | Total records whose futures have been resolved. |
| `total_batches` | `int` | Number of batches dispatched. |
| `total_batch_cost` | `int` | Sum of estimated cost across all batches. |
| `avg_batch_size` | `float` | Running average records per batch. |
| `avg_batch_cost` | `float` | Running average cost per batch. |
| `busy_time_s` | `float` | Cumulative seconds spent inside `process_fn`. |
| `idle_time_s` | `float` | Cumulative seconds the processing loop waited for a batch to be assembled. |

## Properties

| Property | Type | Description |
|-|-|-|
| `utilization` | `None` | Fraction of wall-clock time spent processing (0.0-1.0). |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.extras/containertask ===

# ContainerTask

**Package:** `flyte.extras`

This is an intermediate class that represents Flyte Tasks that run a container at execution time. This is the vast
majority of tasks - the typical `@task` decorated tasks; for instance, all run a container. An example of
something that doesn't run a container would be something like the Athena SQL task.

## Parameters

```python
class ContainerTask(
    name: str,
    image: typing.Union[str, flyte._image.Image],
    command: typing.List[str],
    inputs: typing.Optional[typing.Dict[str, typing.Type]],
    arguments: typing.Optional[typing.List[str]],
    outputs: typing.Optional[typing.Dict[str, typing.Type]],
    input_data_dir: str | pathlib.Path,
    output_data_dir: str | pathlib.Path,
    metadata_format: typing.Literal['JSON', 'YAML', 'PROTO'],
    local_logs: bool,
    kwargs,
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | Name of the task |
| `image` | `typing.Union[str, flyte._image.Image]` | The container image to use for the task. This can be a string or an Image object. |
| `command` | `typing.List[str]` | The command to run in the container. This can be a list of strings or a single string. |
| `inputs` | `typing.Optional[typing.Dict[str, typing.Type]]` | The inputs to the task. This is a dictionary of input names to types. |
| `arguments` | `typing.Optional[typing.List[str]]` | The arguments to pass to the command. This is a list of strings. |
| `outputs` | `typing.Optional[typing.Dict[str, typing.Type]]` | The outputs of the task. This is a dictionary of output names to types. |
| `input_data_dir` | `str \| pathlib.Path` | The directory where the input data is stored. This is a string or a Path object. |
| `output_data_dir` | `str \| pathlib.Path` | The directory where the output data is stored. This is a string or a Path object. |
| `metadata_format` | `typing.Literal['JSON', 'YAML', 'PROTO']` | The format of the output file. This can be "JSON", "YAML", or "PROTO". |
| `local_logs` | `bool` | If True, logs will be printed to the console in the local execution. |
| `kwargs` | `**kwargs` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `native_interface` | `None` |  |
| `source_file` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.extras > ContainerTask > Methods > aio()** | The aio function allows executing "sync" tasks, in an async context. |
| **Flyte SDK > Packages > flyte.extras > ContainerTask > Methods > config()** | Returns additional configuration for the task. |
| **Flyte SDK > Packages > flyte.extras > ContainerTask > Methods > container_args()** | Returns the container args for the task. |
| **Flyte SDK > Packages > flyte.extras > ContainerTask > Methods > custom_config()** | Returns additional configuration for the task. |
| **Flyte SDK > Packages > flyte.extras > ContainerTask > Methods > data_loading_config()** | This configuration allows executing raw containers in Flyte using the Flyte CoPilot system. |
| **Flyte SDK > Packages > flyte.extras > ContainerTask > Methods > execute()** | This is the pure python function that will be executed when the task is called. |
| **Flyte SDK > Packages > flyte.extras > ContainerTask > Methods > forward()** | Think of this as a local execute method for your task. |
| **Flyte SDK > Packages > flyte.extras > ContainerTask > Methods > override()** | Override various parameters of the task template. |
| **Flyte SDK > Packages > flyte.extras > ContainerTask > Methods > post()** | This is the postexecute function that will be. |
| **Flyte SDK > Packages > flyte.extras > ContainerTask > Methods > pre()** | This is the preexecute function that will be. |
| **Flyte SDK > Packages > flyte.extras > ContainerTask > Methods > sql()** | Returns the SQL for the task. |

### aio()

```python
def aio(
    args: *args,
    kwargs: **kwargs,
) -> Coroutine[Any, Any, R] | R
```
The aio function allows executing "sync" tasks, in an async context. This helps with migrating v1 defined sync
tasks to be used within an asyncio parent task.
This function will also re-raise exceptions from the underlying task.

```python
@env.task
def my_legacy_task(x: int) -> int:
    return x

@env.task
async def my_new_parent_task(n: int) -> List[int]:
    collect = []
    for x in range(n):
        collect.append(my_legacy_task.aio(x))
    return asyncio.gather(*collect)
```

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### config()

```python
def config(
    sctx: SerializationContext,
) -> Dict[str, str]
```
Returns additional configuration for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### container_args()

```python
def container_args(
    sctx: flyte.models.SerializationContext,
) -> typing.List[str]
```
Returns the container args for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `flyte.models.SerializationContext` | |

### custom_config()

```python
def custom_config(
    sctx: SerializationContext,
) -> Dict[str, str]
```
Returns additional configuration for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### data_loading_config()

```python
def data_loading_config(
    sctx: flyte.models.SerializationContext,
) -> flyteidl2.core.tasks_pb2.DataLoadingConfig
```
This configuration allows executing raw containers in Flyte using the Flyte CoPilot system
Flyte CoPilot, eliminates the needs of sdk inside the container. Any inputs required by the users container
are side-loaded in the input_path
Any outputs generated by the user container - within output_path are automatically uploaded

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `flyte.models.SerializationContext` | |

### execute()

```python
def execute(
    kwargs,
) -> typing.Any
```
This is the pure python function that will be executed when the task is called.

| Parameter | Type | Description |
|-|-|-|
| `kwargs` | `**kwargs` | |

### forward()

```python
def forward(
    args: *args,
    kwargs: **kwargs,
) -> Coroutine[Any, Any, R] | R
```
Think of this as a local execute method for your task. This function will be invoked by the __call__ method
when not in a Flyte task execution context.  See the implementation below for an example.

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### override()

```python
def override(
    short_name: Optional[str],
    resources: Optional[Resources],
    cache: Optional[CacheRequest],
    retries: Union[int, RetryStrategy],
    timeout: Optional[TimeoutType],
    reusable: Union[ReusePolicy, Literal['off'], None],
    env_vars: Optional[Dict[str, str]],
    secrets: Optional[SecretRequest],
    max_inline_io_bytes: int | None,
    pod_template: Optional[Union[str, PodTemplate]],
    queue: Optional[str],
    interruptible: Optional[bool],
    links: Tuple[Link, ...],
    kwargs: **kwargs,
) -> TaskTemplate
```
Override various parameters of the task template. This allows for dynamic configuration of the task
when it is called, such as changing the image, resources, cache policy, etc.

| Parameter | Type | Description |
|-|-|-|
| `short_name` | `Optional[str]` | Optional override for the short name of the task. |
| `resources` | `Optional[Resources]` | Optional override for the resources to use for the task. |
| `cache` | `Optional[CacheRequest]` | Optional override for the cache policy for the task. |
| `retries` | `Union[int, RetryStrategy]` | Optional override for the number of retries for the task. |
| `timeout` | `Optional[TimeoutType]` | Optional override for the timeout for the task. |
| `reusable` | `Union[ReusePolicy, Literal['off'], None]` | Optional override for the reusability policy for the task. |
| `env_vars` | `Optional[Dict[str, str]]` | Optional override for the environment variables to set for the task. |
| `secrets` | `Optional[SecretRequest]` | Optional override for the secrets that will be injected into the task at runtime. |
| `max_inline_io_bytes` | `int \| None` | Optional override for the maximum allowed size (in bytes) for all inputs and outputs passed directly to the task. |
| `pod_template` | `Optional[Union[str, PodTemplate]]` | Optional override for the pod template to use for the task. |
| `queue` | `Optional[str]` | Optional override for the queue to use for the task. |
| `interruptible` | `Optional[bool]` | Optional override for the interruptible policy for the task. |
| `links` | `Tuple[Link, ...]` | Optional override for the Links associated with the task. |
| `kwargs` | `**kwargs` | Additional keyword arguments for further overrides. Some fields like name, image, docs, and interface cannot be overridden. |

**Returns:** A new TaskTemplate instance with the overridden parameters.

### post()

```python
def post(
    return_vals: Any,
) -> Any
```
This is the postexecute function that will be
called after the task is executed

| Parameter | Type | Description |
|-|-|-|
| `return_vals` | `Any` | |

### pre()

```python
def pre(
    args,
    kwargs,
) -> Dict[str, Any]
```
This is the preexecute function that will be
called before the task is executed

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### sql()

```python
def sql(
    sctx: SerializationContext,
) -> Optional[str]
```
Returns the SQL for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.extras/costestimator ===

# CostEstimator

**Package:** `flyte.extras`

Protocol for records that can estimate their own processing cost.

Implement this on your record type and the batcher will call it
automatically when no explicit `estimated_cost` is passed to
`DynamicBatcher.submit`.

```python
protocol CostEstimator()
```
## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.extras > CostEstimator > Methods > estimate_cost()** |  |

### estimate_cost()

```python
def estimate_cost()
```


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.extras/dynamicbatcher ===

# DynamicBatcher

**Package:** `flyte.extras`

Batches records from many concurrent producers and runs them through
a single async processing function, maximizing resource utilization.

The batcher runs two internal loops:

1. **Aggregation loop** — drains the submission queue and assembles
   cost-budgeted batches, respecting `target_batch_cost`,
   `max_batch_size`, and `batch_timeout_s`.
2. **Processing loop** — pulls assembled batches and calls
   `process_fn`, resolving each record's `asyncio.Future`.

Type Parameters:
    RecordT: The input record type produced by your tasks.
    ResultT: The per-record output type returned by `process_fn`.

## Parameters

```python
class DynamicBatcher(
    process_fn: ProcessFn[RecordT, ResultT],
    cost_estimator: CostEstimatorFn[RecordT] | None,
    target_batch_cost: int,
    max_batch_size: int,
    min_batch_size: int,
    batch_timeout_s: float,
    max_queue_size: int,
    prefetch_batches: int,
    default_cost: int,
)
```
| Parameter | Type | Description |
|-|-|-|
| `process_fn` | `ProcessFn[RecordT, ResultT]` | `async def f(batch: list[RecordT]) -&gt; list[ResultT]` Must return results in the **same order** as the input batch. |
| `cost_estimator` | `CostEstimatorFn[RecordT] \| None` | Optional `(RecordT) -&gt; int` function.  When provided, it is called to estimate the cost of each submitted record. Falls back to `record.estimate_cost()` if the record implements `CostEstimator`, then to `default_cost`. |
| `target_batch_cost` | `int` | Cost budget per batch.  The aggregator fills batches up to this limit before dispatching. |
| `max_batch_size` | `int` | Hard cap on records per batch regardless of cost budget. |
| `min_batch_size` | `int` | Minimum records before dispatching.  Ignored when the timeout fires or shutdown is in progress. |
| `batch_timeout_s` | `float` | Maximum seconds to wait for a full batch.  Lower values reduce idle time but may produce smaller batches. |
| `max_queue_size` | `int` | Bounded queue size.  When full, `submit` awaits (backpressure). |
| `prefetch_batches` | `int` | Number of pre-assembled batches to buffer between the aggregation and processing loops. |
| `default_cost` | `int` | Fallback cost when no estimator is available. |

## Properties

| Property | Type | Description |
|-|-|-|
| `is_running` | `None` | Whether the aggregation and processing loops are active. |
| `stats` | `None` | Current `BatchStats` snapshot. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.extras > DynamicBatcher > Methods > start()** | Start the aggregation and processing loops. |
| **Flyte SDK > Packages > flyte.extras > DynamicBatcher > Methods > stop()** | Graceful shutdown: process all enqueued work, then stop. |
| **Flyte SDK > Packages > flyte.extras > DynamicBatcher > Methods > submit()** | Submit a single record for batched processing. |
| **Flyte SDK > Packages > flyte.extras > DynamicBatcher > Methods > submit_batch()** | Convenience: submit multiple records and return their futures. |

### start()

```python
def start()
```
Start the aggregation and processing loops.

**Raises**

| Exception | Description |
|-|-|
| `RuntimeError` | If the batcher is already running. |

### stop()

```python
def stop()
```
Graceful shutdown: process all enqueued work, then stop.

Blocks until every pending future is resolved.

### submit()

```python
def submit(
    record: RecordT,
    estimated_cost: int | None,
) -> asyncio.Future[ResultT]
```
Submit a single record for batched processing.

Returns an `asyncio.Future` that resolves once the batch
containing this record has been processed.

| Parameter | Type | Description |
|-|-|-|
| `record` | `RecordT` | The input record. |
| `estimated_cost` | `int \| None` | Optional explicit cost.  When omitted the batcher tries `cost_estimator`, then `record.estimate_cost()`, then `default_cost`. |

**Returns**

A future whose result is the corresponding entry from the list
returned by `process_fn`.

**Raises**

| Exception | Description |
|-|-|
| `RuntimeError` | If the batcher is not running. |

> [!NOTE]
> If the internal queue is full this coroutine awaits until space
> is available, providing natural backpressure to fast producers.

### submit_batch()

```python
def submit_batch(
    records: Sequence[RecordT],
    estimated_cost: Sequence[int] | None,
) -> list[asyncio.Future[ResultT]]
```
Convenience: submit multiple records and return their futures.

| Parameter | Type | Description |
|-|-|-|
| `records` | `Sequence[RecordT]` | Iterable of input records. |
| `estimated_cost` | `Sequence[int] \| None` | Optional per-record cost estimates.  Length must match *records* when provided. |

**Returns:** List of futures, one per record.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.extras/prompt ===

# Prompt

**Package:** `flyte.extras`

Simple prompt record with built-in token estimation.

This is a convenience type for common LLM use cases.  For richer
prompt types (e.g. with system messages, metadata), define your own
dataclass implementing `TokenEstimator`.

## Parameters

```python
class Prompt(
    text: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `text` | `str` | The prompt text. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.extras > Prompt > Methods > estimate_tokens()** | Rough token estimate (~4 chars per token). |

### estimate_tokens()

```python
def estimate_tokens()
```
Rough token estimate (~4 chars per token).


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.extras/tokenbatcher ===

# TokenBatcher

**Package:** `flyte.extras`

Token-aware batcher for LLM inference workloads.

A thin convenience wrapper around `DynamicBatcher` that accepts
token-specific parameter names (`inference_fn`, `token_estimator`,
`target_batch_tokens`, etc.) and maps them to the base class.

Also checks the `TokenEstimator` protocol (`estimate_tokens()`)
in addition to `CostEstimator` (`estimate_cost()`).

## Parameters

```python
class TokenBatcher(
    inference_fn: ProcessFn[RecordT, ResultT] | None,
    process_fn: ProcessFn[RecordT, ResultT] | None,
    token_estimator: CostEstimatorFn[RecordT] | None,
    cost_estimator: CostEstimatorFn[RecordT] | None,
    target_batch_tokens: int | None,
    target_batch_cost: int,
    default_token_estimate: int | None,
    default_cost: int,
    max_batch_size: int,
    min_batch_size: int,
    batch_timeout_s: float,
    max_queue_size: int,
    prefetch_batches: int,
)
```
| Parameter | Type | Description |
|-|-|-|
| `inference_fn` | `ProcessFn[RecordT, ResultT] \| None` | |
| `process_fn` | `ProcessFn[RecordT, ResultT] \| None` | |
| `token_estimator` | `CostEstimatorFn[RecordT] \| None` | |
| `cost_estimator` | `CostEstimatorFn[RecordT] \| None` | |
| `target_batch_tokens` | `int \| None` | |
| `target_batch_cost` | `int` | |
| `default_token_estimate` | `int \| None` | |
| `default_cost` | `int` | |
| `max_batch_size` | `int` | |
| `min_batch_size` | `int` | |
| `batch_timeout_s` | `float` | |
| `max_queue_size` | `int` | |
| `prefetch_batches` | `int` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `is_running` | `None` | Whether the aggregation and processing loops are active. |
| `stats` | `None` | Current `BatchStats` snapshot. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.extras > TokenBatcher > Methods > start()** | Start the aggregation and processing loops. |
| **Flyte SDK > Packages > flyte.extras > TokenBatcher > Methods > stop()** | Graceful shutdown: process all enqueued work, then stop. |
| **Flyte SDK > Packages > flyte.extras > TokenBatcher > Methods > submit()** | Submit a single record for batched inference. |
| **Flyte SDK > Packages > flyte.extras > TokenBatcher > Methods > submit_batch()** | Convenience: submit multiple records and return their futures. |

### start()

```python
def start()
```
Start the aggregation and processing loops.

**Raises**

| Exception | Description |
|-|-|
| `RuntimeError` | If the batcher is already running. |

### stop()

```python
def stop()
```
Graceful shutdown: process all enqueued work, then stop.

Blocks until every pending future is resolved.

### submit()

```python
def submit(
    record: RecordT,
    estimated_tokens: int | None,
    estimated_cost: int | None,
) -> asyncio.Future[ResultT]
```
Submit a single record for batched inference.

Accepts either `estimated_tokens` or `estimated_cost`.

| Parameter | Type | Description |
|-|-|-|
| `record` | `RecordT` | The input record. |
| `estimated_tokens` | `int \| None` | Optional explicit token count. |
| `estimated_cost` | `int \| None` | Optional explicit cost (base class parameter). |

**Returns**

A future whose result is the corresponding entry from the list
returned by the inference function.

### submit_batch()

```python
def submit_batch(
    records: Sequence[RecordT],
    estimated_cost: Sequence[int] | None,
) -> list[asyncio.Future[ResultT]]
```
Convenience: submit multiple records and return their futures.

| Parameter | Type | Description |
|-|-|-|
| `records` | `Sequence[RecordT]` | Iterable of input records. |
| `estimated_cost` | `Sequence[int] \| None` | Optional per-record cost estimates.  Length must match *records* when provided. |

**Returns:** List of futures, one per record.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.extras/tokenestimator ===

# TokenEstimator

**Package:** `flyte.extras`

Protocol for records that can estimate their own token count.

Implement this on your record type and the `TokenBatcher` will
call it automatically when no explicit `estimated_tokens` is passed
to `TokenBatcher.submit`.

```python
protocol TokenEstimator()
```
## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.extras > TokenEstimator > Methods > estimate_tokens()** |  |

### estimate_tokens()

```python
def estimate_tokens()
```


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.git ===

# flyte.git

## Directory

### Classes

| Class | Description |
|-|-|
| **Flyte SDK > Packages > flyte.git > GitStatus** | A class representing the status of a git repository. |

### Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.git > Methods > config_from_root()** | Get the config file from the git root directory. |

## Methods

#### config_from_root()

```python
def config_from_root(
    path: pathlib.Path | str,
) -> flyte.config._config.Config | None
```
Get the config file from the git root directory.

By default, the config file is expected to be in `.flyte/config.yaml` in the git root directory.

| Parameter | Type | Description |
|-|-|-|
| `path` | `pathlib.Path \| str` | Path to the config file relative to git root directory (default |

**Returns:** Config object if found, None otherwise

## Subpages
- **Flyte SDK > Packages > flyte.git > GitStatus**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.git/gitstatus ===

# GitStatus

**Package:** `flyte.git`

A class representing the status of a git repository.

## Parameters

```python
class GitStatus(
    is_valid: bool,
    is_tree_clean: bool,
    remote_url: str,
    repo_dir: pathlib.Path,
    commit_sha: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `is_valid` | `bool` | Whether git repository is valid |
| `is_tree_clean` | `bool` | Whether working tree is clean |
| `remote_url` | `str` | Remote URL in HTTPS format |
| `repo_dir` | `pathlib.Path` | Repository root directory |
| `commit_sha` | `str` | Current commit SHA |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.git > GitStatus > Methods > build_url()** | Build a git URL for the given path. |
| **Flyte SDK > Packages > flyte.git > GitStatus > Methods > from_current_repo()** | Discover git information from the current repository. |

### build_url()

```python
def build_url(
    path: pathlib.Path | str,
    line_number: int,
) -> str
```
Build a git URL for the given path.

| Parameter | Type | Description |
|-|-|-|
| `path` | `pathlib.Path \| str` | Path to a file |
| `line_number` | `int` | Line number of the code file |

**Returns:** Path relative to repo_dir

### from_current_repo()

```python
def from_current_repo()
```
Discover git information from the current repository.

If Git is not installed or .git does not exist, returns GitStatus with is_valid=False.

**Returns:** GitStatus instance with discovered git information


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.io ===

# flyte.io

## IO data types

This package contains additional data types beyond the primitive data types in python to abstract data flow
of large datasets in Union.
## Directory

### Classes

| Class | Description |
|-|-|
| **Flyte SDK > Packages > flyte.io > DataFrame** | A Flyte meta DataFrame object, that wraps all other dataframe types (usually available as plugins, pandas. |
| **Flyte SDK > Packages > flyte.io > Dir** | A generic directory class representing a directory with files of a specified format. |
| **Flyte SDK > Packages > flyte.io > File** | A generic file class representing a file with a specified format. |
| **Flyte SDK > Packages > flyte.io > HashFunction** | A hash method that wraps a user-provided function to compute hashes. |

### Variables

| Property | Type | Description |
|-|-|-|
| `PARQUET` | `str` |  |

## Subpages
- **Flyte SDK > Packages > flyte.io > DataFrame**
- **Flyte SDK > Packages > flyte.io > Dir**
- **Flyte SDK > Packages > flyte.io > File**
- **Flyte SDK > Packages > flyte.io > HashFunction**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.io/dataframe ===

# DataFrame

**Package:** `flyte.io`

A Flyte meta DataFrame object, that wraps all other dataframe types (usually available as plugins, pandas.DataFrame
and pyarrow.Table are supported natively, just install these libraries).

Known eco-system plugins that supply other dataframe encoding plugins are,
1. `flyteplugins-polars` - pl.DataFrame
2. `flyteplugins-spark` - pyspark.DataFrame

You can add other implementations by extending following `flyte.io.extend`.

The Flyte DataFrame object serves 2 main purposes:
1. Interoperability between various dataframe objects. A task can generate a pandas.DataFrame and another task
 can accept a flyte.io.DataFrame, which can be converted to any dataframe.
2. Allows for non materialized access to DataFrame objects. So, for example you can accept any dataframe as a
flyte.io.DataFrame and this is just a reference and will not materialize till you force `.all()` or `.iter()` etc

## Parameters

```python
class DataFrame(
    uri: typing.Optional[str],
    format: typing.Optional[str],
    hash: typing.Optional[str],
)
```
Create a new model by parsing and validating input data from keyword arguments.

Raises [`ValidationError`](https://docs.pydantic.dev/latest/api/pydantic_core/#pydantic_core.ValidationError) if the input data cannot be
validated to form a valid model.

`self` is explicitly positional-only to allow `self` as a field name.

| Parameter | Type | Description |
|-|-|-|
| `uri` | `typing.Optional[str]` | |
| `format` | `typing.Optional[str]` | |
| `hash` | `typing.Optional[str]` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `lazy_uploader` | `None` |  |
| `literal` | `None` |  |
| `metadata` | `None` |  |
| `val` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.io > DataFrame > Methods > all()** |  |
| **Flyte SDK > Packages > flyte.io > DataFrame > Methods > all_sync()** |  |
| **Flyte SDK > Packages > flyte.io > DataFrame > Methods > column_names()** |  |
| **Flyte SDK > Packages > flyte.io > DataFrame > Methods > columns()** |  |
| **Flyte SDK > Packages > flyte.io > DataFrame > Methods > deserialize_dataframe()** |  |
| **Flyte SDK > Packages > flyte.io > DataFrame > Methods > from_df()** | Deprecated: Please use wrap_df, as that is the right name. |
| **Flyte SDK > Packages > flyte.io > DataFrame > Methods > from_existing_remote()** | Create a DataFrame reference from an existing remote dataframe. |
| **Flyte SDK > Packages > flyte.io > DataFrame > Methods > from_local()** | This method is useful to upload the dataframe eagerly and get the actual DataFrame. |
| **Flyte SDK > Packages > flyte.io > DataFrame > Methods > from_local_sync()** | This method is useful to upload the dataframe eagerly and get the actual DataFrame. |
| **Flyte SDK > Packages > flyte.io > DataFrame > Methods > iter()** |  |
| **Flyte SDK > Packages > flyte.io > DataFrame > Methods > model_post_init()** | This function is meant to behave like a BaseModel method to initialise private attributes. |
| **Flyte SDK > Packages > flyte.io > DataFrame > Methods > open()** | Load the handler if needed. |
| **Flyte SDK > Packages > flyte.io > DataFrame > Methods > schema_match()** |  |
| **Flyte SDK > Packages > flyte.io > DataFrame > Methods > serialize_dataframe()** |  |
| **Flyte SDK > Packages > flyte.io > DataFrame > Methods > set_literal()** | A public wrapper method to set the DataFrame Literal. |
| **Flyte SDK > Packages > flyte.io > DataFrame > Methods > wrap_df()** | Wrapper to create a DataFrame from a dataframe. |

### all()

```python
def all()
```
### all_sync()

```python
def all_sync()
```
### column_names()

```python
def column_names()
```
### columns()

```python
def columns()
```
### deserialize_dataframe()

```python
def deserialize_dataframe(
    info,
) -> DataFrame
```
| Parameter | Type | Description |
|-|-|-|
| `info` |  | |

### from_df()

```python
def from_df(
    val: typing.Optional[typing.Any],
    uri: typing.Optional[str],
) -> DataFrame
```
Deprecated: Please use wrap_df, as that is the right name.

Creates a new Flyte DataFrame from any registered DataFrame type (For example, pandas.DataFrame).
Other dataframe types are usually supported through plugins like `flyteplugins-polars`, `flyteplugins-spark`
etc.

| Parameter | Type | Description |
|-|-|-|
| `val` | `typing.Optional[typing.Any]` | |
| `uri` | `typing.Optional[str]` | |

### from_existing_remote()

```python
def from_existing_remote(
    remote_path: str,
    format: typing.Optional[str],
    kwargs,
) -> 'DataFrame'
```
Create a DataFrame reference from an existing remote dataframe.

| Parameter | Type | Description |
|-|-|-|
| `remote_path` | `str` | The remote path to the existing dataframe |
| `format` | `typing.Optional[str]` | Format of the stored dataframe |
| `kwargs` | `**kwargs` | |

### from_local()

```python
def from_local(
    df: typing.Any,
    columns: typing.OrderedDict[str, type[typing.Any]] | None,
    remote_destination: str | None,
    hash_method: HashMethod | str | None,
) -> DataFrame
```
This method is useful to upload the dataframe eagerly and get the actual DataFrame.

This is useful to upload small local datasets onto Flyte and also upload dataframes from notebooks. This
uses signed urls and is thus not the most efficient way of uploading.

In tasks (at runtime) it uses the task context and the underlying fast storage sub-system to upload the data.

At runtime it is recommended to use `DataFrame.wrap_df` as it is simpler.

Example (With hash_method for cache key computation):

```python
import pandas as pd
from flyte.io import DataFrame, HashFunction

def hash_pandas_dataframe(df: pd.DataFrame) -> str:
    return str(pd.util.hash_pandas_object(df).sum())

@env.task
async def foo() -> DataFrame:
    df = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
    hash_method = HashFunction.from_fn(hash_pandas_dataframe)
    return await DataFrame.from_local(df, hash_method=hash_method)
```

| Parameter | Type | Description |
|-|-|-|
| `df` | `typing.Any` | The dataframe object to be uploaded and converted. |
| `columns` | `typing.OrderedDict[str, type[typing.Any]] \| None` | Optionally, any column information to be stored as part of the metadata |
| `remote_destination` | `str \| None` | Optional destination URI to upload to, if not specified, this is automatically determined based on the current context. For example, locally it will use flyte:// automatic data management system to upload data (this is slow and useful for smaller datasets). On remote it will use the storage configuration and the raw data directory setting in the task context. |
| `hash_method` | `HashMethod \| str \| None` | Optional HashMethod or string to use for cache key computation. If a string is provided, it will be used as a precomputed cache key. If a HashMethod is provided, it will compute the hash from the dataframe. If not specified, the cache key will be based on dataframe attributes.  Returns: DataFrame object. |

### from_local_sync()

```python
def from_local_sync(
    df: typing.Any,
    columns: typing.OrderedDict[str, type[typing.Any]] | None,
    remote_destination: str | None,
    hash_method: HashMethod | str | None,
) -> DataFrame
```
This method is useful to upload the dataframe eagerly and get the actual DataFrame.

This is useful to upload small local datasets onto Flyte and also upload dataframes from notebooks. This
uses signed urls and is thus not the most efficient way of uploading.

In tasks (at runtime) it uses the task context and the underlying fast storage sub-system to upload the data.

At runtime it is recommended to use `DataFrame.wrap_df` as it is simpler.

Example (With hash_method for cache key computation):

```python
import pandas as pd
from flyte.io import DataFrame, HashFunction

def hash_pandas_dataframe(df: pd.DataFrame) -> str:
    return str(pd.util.hash_pandas_object(df).sum())

@env.task
def foo() -> DataFrame:
    df = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
    hash_method = HashFunction.from_fn(hash_pandas_dataframe)
    return DataFrame.from_local_sync(df, hash_method=hash_method)
```

| Parameter | Type | Description |
|-|-|-|
| `df` | `typing.Any` | The dataframe object to be uploaded and converted. |
| `columns` | `typing.OrderedDict[str, type[typing.Any]] \| None` | Optionally, any column information to be stored as part of the metadata |
| `remote_destination` | `str \| None` | Optional destination URI to upload to, if not specified, this is automatically determined based on the current context. For example, locally it will use flyte:// automatic data management system to upload data (this is slow and useful for smaller datasets). On remote it will use the storage configuration and the raw data directory setting in the task context. |
| `hash_method` | `HashMethod \| str \| None` | Optional HashMethod or string to use for cache key computation. If a string is provided, it will be used as a precomputed cache key. If a HashMethod is provided, it will compute the hash from the dataframe. If not specified, the cache key will be based on dataframe attributes.  Returns: DataFrame object. |

### iter()

```python
def iter()
```
### model_post_init()

```python
def model_post_init(
    context: Any,
)
```
This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that's what pydantic-core passes when calling it.

| Parameter | Type | Description |
|-|-|-|
| `context` | `Any` | The context. |

### open()

```python
def open(
    dataframe_type: Type[DF],
)
```
Load the handler if needed. For the use case like:
@task
def t1(df: DataFrame):
  import pandas as pd
  df.open(pd.DataFrame).all()

pandas is imported inside the task, so panda handler won't be loaded during deserialization in type engine.

| Parameter | Type | Description |
|-|-|-|
| `dataframe_type` | `Type[DF]` | |

### schema_match()

```python
def schema_match(
    incoming: dict,
) -> bool
```
| Parameter | Type | Description |
|-|-|-|
| `incoming` | `dict` | |

### serialize_dataframe()

```python
def serialize_dataframe()
```
### set_literal()

```python
def set_literal(
    expected: types_pb2.LiteralType,
)
```
A public wrapper method to set the DataFrame Literal.

This method provides external access to the internal _set_literal method.

| Parameter | Type | Description |
|-|-|-|
| `expected` | `types_pb2.LiteralType` | |

### wrap_df()

```python
def wrap_df(
    val: typing.Optional[typing.Any],
    uri: typing.Optional[str],
) -> DataFrame
```
Wrapper to create a DataFrame from a dataframe.
Other dataframe types are usually supported through plugins like `flyteplugins-polars`, `flyteplugins-spark`
etc.

| Parameter | Type | Description |
|-|-|-|
| `val` | `typing.Optional[typing.Any]` | |
| `uri` | `typing.Optional[str]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.io/dir ===

# Dir

**Package:** `flyte.io`

A generic directory class representing a directory with files of a specified format.
Provides both async and sync interfaces for directory operations. All methods without _sync suffix are async.

The class should be instantiated using one of the class methods. The constructor should only be used to
instantiate references to existing remote directories.

The generic type T represents the format of the files in the directory.

Important methods:
- `from_existing_remote`: Create a Dir object referencing an existing remote directory.
- `from_local` / `from_local_sync`: Upload a local directory to remote storage.

**Asynchronous methods**:
- `walk`: Asynchronously iterate through files in the directory.
- `list_files`: Asynchronously get a list of all files (non-recursive).
- `download`: Asynchronously download the entire directory to a local path.
- `exists`: Asynchronously check if the directory exists.
- `get_file`: Asynchronously get a specific file from the directory by name.

**Synchronous methods** (suffixed with `_sync`):
- `walk_sync`: Synchronously iterate through files in the directory.
- `list_files_sync`: Synchronously get a list of all files (non-recursive).
- `download_sync`: Synchronously download the entire directory to a local path.
- `exists_sync`: Synchronously check if the directory exists.
- `get_file_sync`: Synchronously get a specific file from the directory by name.

Example: Walk through directory files recursively (Async).

```python
@env.task
async def process_all_files(d: Dir) -> int:
    file_count = 0
    async for file in d.walk(recursive=True):
        async with file.open("rb") as f:
            content = await f.read()
            # Process content
            file_count += 1
    return file_count
```

Example: Walk through directory files recursively (Sync).

```python
@env.task
def process_all_files_sync(d: Dir) -> int:
    file_count = 0
    for file in d.walk_sync(recursive=True):
        with file.open_sync("rb") as f:
            content = f.read()
            # Process content
            file_count += 1
    return file_count
```

Example: List files in directory (Async).

```python
@env.task
async def count_files(d: Dir) -> int:
    files = await d.list_files()
    return len(files)
```

Example: List files in directory (Sync).

```python
@env.task
def count_files_sync(d: Dir) -> int:
    files = d.list_files_sync()
    return len(files)
```

Example: Get a specific file from directory (Async).

```python
@env.task
async def read_config_file(d: Dir) -> str:
    config_file = await d.get_file("config.json")
    if config_file:
        async with config_file.open("rb") as f:
            return (await f.read()).decode("utf-8")
    return "Config not found"
```

Example: Get a specific file from directory (Sync).

```python
@env.task
def read_config_file_sync(d: Dir) -> str:
    config_file = d.get_file_sync("config.json")
    if config_file:
        with config_file.open_sync("rb") as f:
            return f.read().decode("utf-8")
    return "Config not found"
```

Example: Upload a local directory to remote storage (Async).

```python
@env.task
async def upload_directory() -> Dir:
    # Create local directory with files
    os.makedirs("/tmp/my_data", exist_ok=True)
    with open("/tmp/my_data/file1.txt", "w") as f:
        f.write("data1")
    # Upload to remote storage
    return await Dir.from_local("/tmp/my_data/")
```

Example: Upload a local directory to remote storage (Sync).

```python
@env.task
def upload_directory_sync() -> Dir:
    # Create local directory with files
    os.makedirs("/tmp/my_data", exist_ok=True)
    with open("/tmp/my_data/file1.txt", "w") as f:
        f.write("data1")
    # Upload to remote storage
    return Dir.from_local_sync("/tmp/my_data/")
```

Example: Download a directory to local storage (Async).

```python
@env.task
async def download_directory(d: Dir) -> str:
    local_path = await d.download()
    # Process files in local directory
    return local_path
```

Example: Download a directory to local storage (Sync).

```python
@env.task
def download_directory_sync(d: Dir) -> str:
    local_path = d.download_sync()
    # Process files in local directory
    return local_path
```

Example: Reference an existing remote directory.

```python
@env.task
async def process_existing_dir() -> int:
    d = Dir.from_existing_remote("s3://my-bucket/data/")
    files = await d.list_files()
    return len(files)
```

Example: Check if directory exists (Async).

```python
@env.task
async def check_directory(d: Dir) -> bool:
    return await d.exists()
```

Example: Check if directory exists (Sync).

```python
@env.task
def check_directory_sync(d: Dir) -> bool:
    return d.exists_sync()
```

## Parameters

```python
class Dir(
    path: str,
    name: typing.Optional[str],
    format: str,
    hash: typing.Optional[str],
)
```
Create a new model by parsing and validating input data from keyword arguments.

Raises [`ValidationError`](https://docs.pydantic.dev/latest/api/pydantic_core/#pydantic_core.ValidationError) if the input data cannot be
validated to form a valid model.

`self` is explicitly positional-only to allow `self` as a field name.

| Parameter | Type | Description |
|-|-|-|
| `path` | `str` | The path to the directory (can be local or remote) |
| `name` | `typing.Optional[str]` | Optional name for the directory (defaults to basename of path) |
| `format` | `str` | |
| `hash` | `typing.Optional[str]` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `lazy_uploader` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.io > Dir > Methods > download()** | Asynchronously download the entire directory to a local path. |
| **Flyte SDK > Packages > flyte.io > Dir > Methods > download_sync()** | Synchronously download the entire directory to a local path. |
| **Flyte SDK > Packages > flyte.io > Dir > Methods > exists()** | Asynchronously check if the directory exists. |
| **Flyte SDK > Packages > flyte.io > Dir > Methods > exists_sync()** | Synchronously check if the directory exists. |
| **Flyte SDK > Packages > flyte.io > Dir > Methods > from_existing_remote()** | Create a Dir reference from an existing remote directory. |
| **Flyte SDK > Packages > flyte.io > Dir > Methods > from_local()** | Asynchronously create a new Dir by uploading a local directory to remote storage. |
| **Flyte SDK > Packages > flyte.io > Dir > Methods > from_local_sync()** | Synchronously create a new Dir by uploading a local directory to remote storage. |
| **Flyte SDK > Packages > flyte.io > Dir > Methods > get_file()** | Asynchronously get a specific file from the directory by name. |
| **Flyte SDK > Packages > flyte.io > Dir > Methods > get_file_sync()** | Synchronously get a specific file from the directory by name. |
| **Flyte SDK > Packages > flyte.io > Dir > Methods > list_files()** | Asynchronously get a list of all files in the directory (non-recursive). |
| **Flyte SDK > Packages > flyte.io > Dir > Methods > list_files_sync()** | Synchronously get a list of all files in the directory (non-recursive). |
| **Flyte SDK > Packages > flyte.io > Dir > Methods > model_post_init()** | This function is meant to behave like a BaseModel method to initialise private attributes. |
| **Flyte SDK > Packages > flyte.io > Dir > Methods > new_remote()** | Create a new Dir reference for a remote directory that will be written to. |
| **Flyte SDK > Packages > flyte.io > Dir > Methods > pre_init()** | Internal: Pydantic validator to set default name from path. |
| **Flyte SDK > Packages > flyte.io > Dir > Methods > schema_match()** | Internal: Check if incoming schema matches Dir schema. |
| **Flyte SDK > Packages > flyte.io > Dir > Methods > walk()** | Asynchronously walk through the directory and yield File objects. |
| **Flyte SDK > Packages > flyte.io > Dir > Methods > walk_sync()** | Synchronously walk through the directory and yield File objects. |

### download()

```python
def download(
    local_path: Optional[Union[str, Path]],
) -> str
```
Asynchronously download the entire directory to a local path.

Use this when you need to download all files in a directory to your local filesystem for processing.

Example (Async):

```python
@env.task
async def download_directory(d: Dir) -> str:
    local_dir = await d.download()
    # Process files in the local directory
    return local_dir
```

Example (Async - Download to specific path):

```python
@env.task
async def download_to_path(d: Dir) -> str:
    local_dir = await d.download("/tmp/my_data/")
    return local_dir
```

| Parameter | Type | Description |
|-|-|-|
| `local_path` | `Optional[Union[str, Path]]` | The local path to download the directory to. If None, a temporary directory will be used and a path will be generated. |

**Returns:** The absolute path to the downloaded directory

### download_sync()

```python
def download_sync(
    local_path: Optional[Union[str, Path]],
) -> str
```
Synchronously download the entire directory to a local path.

Use this in non-async tasks when you need to download all files in a directory to your local filesystem.

Example (Sync):

```python
@env.task
def download_directory_sync(d: Dir) -> str:
    local_dir = d.download_sync()
    # Process files in the local directory
    return local_dir
```

Example (Sync - Download to specific path):

```python
@env.task
def download_to_path_sync(d: Dir) -> str:
    local_dir = d.download_sync("/tmp/my_data/")
    return local_dir
```

| Parameter | Type | Description |
|-|-|-|
| `local_path` | `Optional[Union[str, Path]]` | The local path to download the directory to. If None, a temporary directory will be used and a path will be generated. |

**Returns:** The absolute path to the downloaded directory

### exists()

```python
def exists()
```
Asynchronously check if the directory exists.

Example (Async):

```python
@env.task
async def check_directory(d: Dir) -> bool:
    if await d.exists():
        print("Directory exists!")
        return True
    return False
```

**Returns**

True if the directory exists, False otherwise

### exists_sync()

```python
def exists_sync()
```
Synchronously check if the directory exists.

Use this in non-async tasks or when you need synchronous directory existence checking.

Example (Sync):

```python
@env.task
def check_directory_sync(d: Dir) -> bool:
    if d.exists_sync():
        print("Directory exists!")
        return True
    return False
```

**Returns**

True if the directory exists, False otherwise

### from_existing_remote()

```python
def from_existing_remote(
    remote_path: str,
    dir_cache_key: Optional[str],
) -> Dir[T]
```
Create a Dir reference from an existing remote directory.

Use this when you want to reference a directory that already exists in remote storage without uploading it.

```python
@env.task
async def process_existing_directory() -> int:
    d = Dir.from_existing_remote("s3://my-bucket/data/")
    files = await d.list_files()
    return len(files)
```

Example (With cache key):

```python
@env.task
async def process_with_cache_key() -> int:
    d = Dir.from_existing_remote("s3://my-bucket/data/", dir_cache_key="abc123")
    files = await d.list_files()
    return len(files)
```

| Parameter | Type | Description |
|-|-|-|
| `remote_path` | `str` | The remote path to the existing directory |
| `dir_cache_key` | `Optional[str]` | Optional hash value to use for cache key computation. If not specified, the cache key will be computed based on the directory's attributes. |

**Returns:** A new Dir instance pointing to the existing remote directory

### from_local()

```python
def from_local(
    local_path: Union[str, Path],
    remote_destination: Optional[str],
    dir_cache_key: Optional[str],
    batch_size: Optional[int],
) -> Dir[T]
```
Asynchronously create a new Dir by uploading a local directory to remote storage.

Use this in async tasks when you have a local directory that needs to be uploaded to remote storage.

Example (Async):

```python
@env.task
async def upload_local_directory() -> Dir:
    # Create a local directory with files
    os.makedirs("/tmp/data_dir", exist_ok=True)
    with open("/tmp/data_dir/file1.txt", "w") as f:
        f.write("data1")

    # Upload to remote storage
    remote_dir = await Dir.from_local("/tmp/data_dir/")
    return remote_dir
```

Example (Async - With specific destination):

```python
@env.task
async def upload_to_specific_path() -> Dir:
    remote_dir = await Dir.from_local("/tmp/data_dir/", "s3://my-bucket/data/")
    return remote_dir
```

Example (Async - With cache key):

```python
@env.task
async def upload_with_cache_key() -> Dir:
    remote_dir = await Dir.from_local("/tmp/data_dir/", dir_cache_key="my_cache_key_123")
    return remote_dir
```

| Parameter | Type | Description |
|-|-|-|
| `local_path` | `Union[str, Path]` | Path to the local directory |
| `remote_destination` | `Optional[str]` | Optional remote path to store the directory. If None, a path will be automatically generated. |
| `dir_cache_key` | `Optional[str]` | Optional precomputed hash value to use for cache key computation when this Dir is used as an input to discoverable tasks. If not specified, the cache key will be based on directory attributes. |
| `batch_size` | `Optional[int]` | Optional concurrency limit for uploading files. If not specified, the default value is determined by the FLYTE_IO_BATCH_SIZE environment variable (default: 32). |

**Returns:** A new Dir instance pointing to the uploaded directory

### from_local_sync()

```python
def from_local_sync(
    local_path: Union[str, Path],
    remote_destination: Optional[str],
    dir_cache_key: Optional[str],
) -> Dir[T]
```
Synchronously create a new Dir by uploading a local directory to remote storage.

Use this in non-async tasks when you have a local directory that needs to be uploaded to remote storage.

Example (Sync):

```python
@env.task
def upload_local_directory_sync() -> Dir:
    # Create a local directory with files
    os.makedirs("/tmp/data_dir", exist_ok=True)
    with open("/tmp/data_dir/file1.txt", "w") as f:
        f.write("data1")

    # Upload to remote storage
    remote_dir = Dir.from_local_sync("/tmp/data_dir/")
    return remote_dir
```

Example (Sync - With specific destination):

```python
@env.task
def upload_to_specific_path_sync() -> Dir:
    remote_dir = Dir.from_local_sync("/tmp/data_dir/", "s3://my-bucket/data/")
    return remote_dir
```

Example (Sync - With cache key):

```python
@env.task
def upload_with_cache_key_sync() -> Dir:
    remote_dir = Dir.from_local_sync("/tmp/data_dir/", dir_cache_key="my_cache_key_123")
    return remote_dir
```

| Parameter | Type | Description |
|-|-|-|
| `local_path` | `Union[str, Path]` | Path to the local directory |
| `remote_destination` | `Optional[str]` | Optional remote path to store the directory. If None, a path will be automatically generated. |
| `dir_cache_key` | `Optional[str]` | Optional precomputed hash value to use for cache key computation when this Dir is used as an input to discoverable tasks. If not specified, the cache key will be based on directory attributes. |

**Returns:** A new Dir instance pointing to the uploaded directory

### get_file()

```python
def get_file(
    file_name: str,
) -> Optional[File[T]]
```
Asynchronously get a specific file from the directory by name.

Use this when you know the name of a specific file in the directory you want to access.

Example (Async):

```python
@env.task
async def read_specific_file(d: Dir) -> str:
    file = await d.get_file("data.csv")
    if file:
        async with file.open("rb") as f:
            content = await f.read()
            return content.decode("utf-8")
    return "File not found"
```

| Parameter | Type | Description |
|-|-|-|
| `file_name` | `str` | The name of the file to get |

**Returns:** A File instance if the file exists, None otherwise

### get_file_sync()

```python
def get_file_sync(
    file_name: str,
) -> Optional[File[T]]
```
Synchronously get a specific file from the directory by name.

Use this in non-async tasks when you know the name of a specific file in the directory you want to access.

Example (Sync):

```python
@env.task
def read_specific_file_sync(d: Dir) -> str:
    file = d.get_file_sync("data.csv")
    if file:
        with file.open_sync("rb") as f:
            content = f.read()
            return content.decode("utf-8")
    return "File not found"
```

| Parameter | Type | Description |
|-|-|-|
| `file_name` | `str` | The name of the file to get |

**Returns:** A File instance if the file exists, None otherwise

### list_files()

```python
def list_files()
```
Asynchronously get a list of all files in the directory (non-recursive).

Use this when you need a list of all files in the top-level directory at once.

Example (Async):

```python
@env.task
async def count_files(d: Dir) -> int:
    files = await d.list_files()
    return len(files)
```

Example (Async - Process files):

```python
@env.task
async def process_all_files(d: Dir) -> list[str]:
    files = await d.list_files()
    contents = []
    for file in files:
        async with file.open("rb") as f:
            content = await f.read()
            contents.append(content.decode("utf-8"))
    return contents
```

**Returns**

A list of File objects for files in the top-level directory

### list_files_sync()

```python
def list_files_sync()
```
Synchronously get a list of all files in the directory (non-recursive).

Use this in non-async tasks when you need a list of all files in the top-level directory at once.

Example (Sync):

```python
@env.task
def count_files_sync(d: Dir) -> int:
    files = d.list_files_sync()
    return len(files)
```

Example (Sync - Process files):

```python
@env.task
def process_all_files_sync(d: Dir) -> list[str]:
    files = d.list_files_sync()
    contents = []
    for file in files:
        with file.open_sync("rb") as f:
            content = f.read()
            contents.append(content.decode("utf-8"))
    return contents
```

**Returns**

A list of File objects for files in the top-level directory

### model_post_init()

```python
def model_post_init(
    context: Any,
)
```
This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that's what pydantic-core passes when calling it.

| Parameter | Type | Description |
|-|-|-|
| `context` | `Any` | The context. |

### new_remote()

```python
def new_remote(
    dir_name: Optional[str],
    hash: Optional[str],
) -> Dir[T]
```
Create a new Dir reference for a remote directory that will be written to.

Use this when you want to create a new directory and write files into it
directly without creating a local directory first.

| Parameter | Type | Description |
|-|-|-|
| `dir_name` | `Optional[str]` | Optional name for the remote directory. If not set, a generated name will be used. |
| `hash` | `Optional[str]` | Optional precomputed hash value to use for cache key computation when this Dir is used as an input to discoverable tasks. |

**Returns:** A new Dir instance with a generated remote path.

### pre_init()

```python
def pre_init(
    data,
)
```
Internal: Pydantic validator to set default name from path. Not intended for direct use.

| Parameter | Type | Description |
|-|-|-|
| `data` |  | |

### schema_match()

```python
def schema_match(
    incoming: dict,
)
```
Internal: Check if incoming schema matches Dir schema. Not intended for direct use.

| Parameter | Type | Description |
|-|-|-|
| `incoming` | `dict` | |

### walk()

```python
def walk(
    recursive: bool,
    max_depth: Optional[int],
) -> AsyncIterator[File[T]]
```
Asynchronously walk through the directory and yield File objects.

Use this to iterate through all files in a directory. Each yielded File can be read directly without
downloading.

Example (Async - Recursive):

```python
@env.task
async def list_all_files(d: Dir) -> list[str]:
    file_names = []
    async for file in d.walk(recursive=True):
        file_names.append(file.name)
    return file_names
```

Example (Async - Non-recursive):

```python
@env.task
async def list_top_level_files(d: Dir) -> list[str]:
    file_names = []
    async for file in d.walk(recursive=False):
        file_names.append(file.name)
    return file_names
```

Example (Async - With max depth):

```python
@env.task
async def list_files_max_depth(d: Dir) -> list[str]:
    file_names = []
    async for file in d.walk(recursive=True, max_depth=2):
        file_names.append(file.name)
    return file_names
```

Yields:
    File objects for each file found in the directory

| Parameter | Type | Description |
|-|-|-|
| `recursive` | `bool` | If True, recursively walk subdirectories. If False, only list files in the top-level directory. |
| `max_depth` | `Optional[int]` | Maximum depth for recursive walking. If None, walk through all subdirectories. |

### walk_sync()

```python
def walk_sync(
    recursive: bool,
    file_pattern: str,
    max_depth: Optional[int],
) -> Iterator[File[T]]
```
Synchronously walk through the directory and yield File objects.

Use this in non-async tasks to iterate through all files in a directory.

Example (Sync - Recursive):

```python
@env.task
def list_all_files_sync(d: Dir) -> list[str]:
    file_names = []
    for file in d.walk_sync(recursive=True):
        file_names.append(file.name)
    return file_names
```

Example (Sync - With file pattern):

```python
@env.task
def list_text_files(d: Dir) -> list[str]:
    file_names = []
    for file in d.walk_sync(recursive=True, file_pattern="*.txt"):
        file_names.append(file.name)
    return file_names
```

Example (Sync - Non-recursive with max depth):

```python
@env.task
def list_files_limited(d: Dir) -> list[str]:
    file_names = []
    for file in d.walk_sync(recursive=True, max_depth=2):
        file_names.append(file.name)
    return file_names
```

Yields:
    File objects for each file found in the directory

| Parameter | Type | Description |
|-|-|-|
| `recursive` | `bool` | If True, recursively walk subdirectories. If False, only list files in the top-level directory. |
| `file_pattern` | `str` | Glob pattern to filter files (e.g., "*.txt", "*.csv"). Default is "*" (all files). |
| `max_depth` | `Optional[int]` | Maximum depth for recursive walking. If None, walk through all subdirectories. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.io/file ===

# File

**Package:** `flyte.io`

A generic file class representing a file with a specified format.
Provides both async and sync interfaces for file operations. All methods without _sync suffix are async.

The class should be instantiated using one of the class methods. The constructor should be used only to
instantiate references to existing remote objects.

The generic type T represents the format of the file.

Important methods:
- `from_existing_remote`: Create a File object from an existing remote file.
- `new_remote`: Create a new File reference for a remote file that will be written to.

**Asynchronous methods**:
- `open`: Asynchronously open the file and return a file-like object.
- `download`: Asynchronously download the file to a local path.
- `from_local`: Asynchronously create a File object from a local file, uploading it to remote storage.
- `exists`: Asynchronously check if the file exists.

**Synchronous methods** (suffixed with `_sync`):
- `open_sync`: Synchronously open the file and return a file-like object.
- `download_sync`: Synchronously download the file to a local path.
- `from_local_sync`: Synchronously create a File object from a local file, uploading it to remote storage.
- `exists_sync`: Synchronously check if the file exists.

Example: Read a file input in a Task (Async).

```python
@env.task
async def read_file(file: File) -> str:
    async with file.open("rb") as f:
        content = bytes(await f.read())
        return content.decode("utf-8")
```

Example: Read a file input in a Task (Sync).

```python
@env.task
def read_file_sync(file: File) -> str:
    with file.open_sync("rb") as f:
        content = f.read()
        return content.decode("utf-8")
```

Example: Write a file by streaming it directly to blob storage (Async).

```python
@env.task
async def write_file() -> File:
    file = File.new_remote()
    async with file.open("wb") as f:
        await f.write(b"Hello, World!")
    return file
```

Example: Upload a local file to remote storage (Async).

```python
@env.task
async def upload_file() -> File:
    # Write to local file first
    with open("/tmp/data.csv", "w") as f:
        f.write("col1,col2\n1,2\n3,4\n")
    # Upload to remote storage
    return await File.from_local("/tmp/data.csv")
```

Example: Upload a local file to remote storage (Sync).

```python
@env.task
def upload_file_sync() -> File:
    # Write to local file first
    with open("/tmp/data.csv", "w") as f:
        f.write("col1,col2\n1,2\n3,4\n")
    # Upload to remote storage
    return File.from_local_sync("/tmp/data.csv")
```

Example: Download a file to local storage (Async).

```python
@env.task
async def download_file(file: File) -> str:
    local_path = await file.download()
    # Process the local file
    with open(local_path, "r") as f:
        return f.read()
```

Example: Download a file to local storage (Sync).

```python
@env.task
def download_file_sync(file: File) -> str:
    local_path = file.download_sync()
    # Process the local file
    with open(local_path, "r") as f:
        return f.read()
```

Example: Reference an existing remote file.

```python
@env.task
async def process_existing_file() -> str:
    file = File.from_existing_remote("s3://my-bucket/data.csv")
    async with file.open("rb") as f:
        content = await f.read()
        return content.decode("utf-8")
```

Example: Check if a file exists (Async).

```python
@env.task
async def check_file(file: File) -> bool:
    return await file.exists()
```

Example: Check if a file exists (Sync).

```python
@env.task
def check_file_sync(file: File) -> bool:
    return file.exists_sync()
```

Example: Pass through a file without copying.

```python
@env.task
async def pass_through(file: File) -> File:
    # No copy occurs - just passes the reference
    return file
```

## Parameters

```python
class File(
    path: str,
    name: typing.Optional[str],
    format: str,
    hash: typing.Optional[str],
    hash_method: typing.Optional[flyte.io._hashing_io.HashMethod],
)
```
Create a new model by parsing and validating input data from keyword arguments.

Raises [`ValidationError`](https://docs.pydantic.dev/latest/api/pydantic_core/#pydantic_core.ValidationError) if the input data cannot be
validated to form a valid model.

`self` is explicitly positional-only to allow `self` as a field name.

| Parameter | Type | Description |
|-|-|-|
| `path` | `str` | The path to the file (can be local or remote) |
| `name` | `typing.Optional[str]` | Optional name for the file (defaults to basename of path) |
| `format` | `str` | |
| `hash` | `typing.Optional[str]` | |
| `hash_method` | `typing.Optional[flyte.io._hashing_io.HashMethod]` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `lazy_uploader` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.io > File > Methods > download()** | Asynchronously download the file to a local path. |
| **Flyte SDK > Packages > flyte.io > File > Methods > download_sync()** | Synchronously download the file to a local path. |
| **Flyte SDK > Packages > flyte.io > File > Methods > exists()** | Asynchronously check if the file exists. |
| **Flyte SDK > Packages > flyte.io > File > Methods > exists_sync()** | Synchronously check if the file exists. |
| **Flyte SDK > Packages > flyte.io > File > Methods > from_existing_remote()** | Create a File reference from an existing remote file. |
| **Flyte SDK > Packages > flyte.io > File > Methods > from_local()** | Asynchronously create a new File object from a local file by uploading it to remote storage. |
| **Flyte SDK > Packages > flyte.io > File > Methods > from_local_sync()** | Synchronously create a new File object from a local file by uploading it to remote storage. |
| **Flyte SDK > Packages > flyte.io > File > Methods > model_post_init()** | This function is meant to behave like a BaseModel method to initialise private attributes. |
| **Flyte SDK > Packages > flyte.io > File > Methods > named_remote()** | Create a File reference whose remote path is derived deterministically from *name*. |
| **Flyte SDK > Packages > flyte.io > File > Methods > new_remote()** | Create a new File reference for a remote file that will be written to. |
| **Flyte SDK > Packages > flyte.io > File > Methods > open()** | Asynchronously open the file and return a file-like object. |
| **Flyte SDK > Packages > flyte.io > File > Methods > open_sync()** | Synchronously open the file and return a file-like object. |
| **Flyte SDK > Packages > flyte.io > File > Methods > pre_init()** | Internal: Pydantic validator to set default name from path. |
| **Flyte SDK > Packages > flyte.io > File > Methods > schema_match()** | Internal: Check if incoming schema matches File schema. |

### download()

```python
def download(
    local_path: Optional[Union[str, Path]],
) -> str
```
Asynchronously download the file to a local path.

Use this when you need to download a remote file to your local filesystem for processing.

Example (Async):

```python
@env.task
async def download_and_process(f: File) -> str:
    local_path = await f.download()
    # Now process the local file
    with open(local_path, "r") as fh:
        return fh.read()
```

Example (Download to specific path):

```python
@env.task
async def download_to_path(f: File) -> str:
    local_path = await f.download("/tmp/myfile.csv")
    return local_path
```

| Parameter | Type | Description |
|-|-|-|
| `local_path` | `Optional[Union[str, Path]]` | The local path to download the file to. If None, a temporary directory will be used and a path will be generated. |

**Returns:** The absolute path to the downloaded file

### download_sync()

```python
def download_sync(
    local_path: Optional[Union[str, Path]],
) -> str
```
Synchronously download the file to a local path.

Use this in non-async tasks when you need to download a remote file to your local filesystem.

Example (Sync):

```python
@env.task
def download_and_process_sync(f: File) -> str:
    local_path = f.download_sync()
    # Now process the local file
    with open(local_path, "r") as fh:
        return fh.read()
```

Example (Download to specific path):

```python
@env.task
def download_to_path_sync(f: File) -> str:
    local_path = f.download_sync("/tmp/myfile.csv")
    return local_path
```

| Parameter | Type | Description |
|-|-|-|
| `local_path` | `Optional[Union[str, Path]]` | The local path to download the file to. If None, a temporary directory will be used and a path will be generated. |

**Returns:** The absolute path to the downloaded file

### exists()

```python
def exists()
```
Asynchronously check if the file exists.

Example (Async):

```python
@env.task
async def check_file(f: File) -> bool:
    if await f.exists():
        print("File exists!")
        return True
    return False
```

**Returns:** True if the file exists, False otherwise

### exists_sync()

```python
def exists_sync()
```
Synchronously check if the file exists.

Use this in non-async tasks or when you need synchronous file existence checking.

Example (Sync):

```python
@env.task
def check_file_sync(f: File) -> bool:
    if f.exists_sync():
        print("File exists!")
        return True
    return False
```

**Returns:** True if the file exists, False otherwise

### from_existing_remote()

```python
def from_existing_remote(
    remote_path: str,
    file_cache_key: Optional[str],
) -> File[T]
```
Create a File reference from an existing remote file.

Use this when you want to reference a file that already exists in remote storage without uploading it.

```python
@env.task
async def process_existing_file() -> str:
    file = File.from_existing_remote("s3://my-bucket/data.csv")
    async with file.open("rb") as f:
        content = await f.read()
    return content.decode("utf-8")
```

| Parameter | Type | Description |
|-|-|-|
| `remote_path` | `str` | The remote path to the existing file |
| `file_cache_key` | `Optional[str]` | Optional hash value to use for cache key computation. If not specified, the cache key will be computed based on the file's attributes (path, name, format). |

**Returns:** A new File instance pointing to the existing remote file

### from_local()

```python
def from_local(
    local_path: Union[str, Path],
    remote_destination: Optional[str],
    hash_method: Optional[HashMethod | str],
) -> File[T]
```
Asynchronously create a new File object from a local file by uploading it to remote storage.

        Use this in async tasks when you have a local file that needs to be uploaded to remote storage.

        Example (Async):

        ```python
        @env.task
        async def upload_local_file() -> File:
            # Create a local file
            async with aiofiles.open("/tmp/data.csv", "w") as f:
                await f.write("col1,col2
1,2
3,4
")

            # Upload to remote storage
            remote_file = await File.from_local("/tmp/data.csv")
            return remote_file
        ```

        Example (With specific destination):

        ```python
        @env.task
        async def upload_to_specific_path() -> File:
            remote_file = await File.from_local("/tmp/data.csv", "s3://my-bucket/data.csv")
            return remote_file
        ```

        Args:
            local_path: Path to the local file
            remote_destination: Optional remote path to store the file. If None, a path will be automatically generated.
            hash_method: Optional HashMethod or string to use for cache key computation. If a string is provided,
                        it will be used as a precomputed cache key. If a HashMethod is provided, it will compute
                        the hash during upload. If not specified, the cache key will be based on file attributes.

        Returns:
            A new File instance pointing to the uploaded remote file
        
| Parameter | Type | Description |
|-|-|-|
| `local_path` | `Union[str, Path]` | |
| `remote_destination` | `Optional[str]` | |
| `hash_method` | `Optional[HashMethod \| str]` | |

### from_local_sync()

```python
def from_local_sync(
    local_path: Union[str, Path],
    remote_destination: Optional[str],
    hash_method: Optional[HashMethod | str],
) -> File[T]
```
Synchronously create a new File object from a local file by uploading it to remote storage.

        Use this in non-async tasks when you have a local file that needs to be uploaded to remote storage.

        Example (Sync):

        ```python
        @env.task
        def upload_local_file_sync() -> File:
            # Create a local file
            with open("/tmp/data.csv", "w") as f:
                f.write("col1,col2
1,2
3,4
")

            # Upload to remote storage
            remote_file = File.from_local_sync("/tmp/data.csv")
            return remote_file
        ```

        Example (With specific destination):

        ```python
        @env.task
        def upload_to_specific_path() -> File:
            remote_file = File.from_local_sync("/tmp/data.csv", "s3://my-bucket/data.csv")
            return remote_file
        ```

        Args:
            local_path: Path to the local file
            remote_destination: Optional remote path to store the file. If None, a path will be automatically generated.
            hash_method: Optional HashMethod or string to use for cache key computation. If a string is provided,
                        it will be used as a precomputed cache key. If a HashMethod is provided, it will compute
                        the hash during upload. If not specified, the cache key will be based on file attributes.

        Returns:
            A new File instance pointing to the uploaded remote file
        
| Parameter | Type | Description |
|-|-|-|
| `local_path` | `Union[str, Path]` | |
| `remote_destination` | `Optional[str]` | |
| `hash_method` | `Optional[HashMethod \| str]` | |

### model_post_init()

```python
def model_post_init(
    context: Any,
)
```
This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that's what pydantic-core passes when calling it.

| Parameter | Type | Description |
|-|-|-|
| `context` | `Any` | The context. |

### named_remote()

```python
def named_remote(
    name: str,
) -> File[T]
```
Create a File reference whose remote path is derived deterministically from *name*.

Unlike `new_remote`, which generates a random path on every call, this method
produces the same path for the same *name* within a given task execution. This makes
it safe across retries: the first attempt uploads to the path and subsequent retries
resolve to the identical location without re-uploading.

The path is optionally namespaced by the node ID extracted from the backend
raw-data path, which follows the convention:

    {run_name}-{node_id}-{attempt_index}

If extraction fails, the function falls back to the run base directory alone.

| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | Plain filename (e.g., "data.csv"). Must not contain path separators. |

**Returns:** A `File` instance whose path is stable across retries.

### new_remote()

```python
def new_remote(
    file_name: Optional[str],
    hash_method: Optional[HashMethod | str],
) -> File[T]
```
Create a new File reference for a remote file that will be written to.

Use this when you want to create a new file and write to it directly without creating a local file first.

Example (Async):

```python
@env.task
async def create_csv() -> File:
    df = pd.DataFrame({"col1": [1, 2], "col2": [3, 4]})
    file = File.new_remote()
    async with file.open("wb") as f:
        df.to_csv(f)
    return file
```

| Parameter | Type | Description |
|-|-|-|
| `file_name` | `Optional[str]` | Optional string specifying a remote file name. If not set, a generated file name will be returned. |
| `hash_method` | `Optional[HashMethod \| str]` | Optional HashMethod or string to use for cache key computation. If a string is provided, it will be used as a precomputed cache key. If a HashMethod is provided, it will be used to compute the hash as data is written. |

**Returns:** A new File instance with a generated remote path

### open()

```python
def open(
    mode: str,
    block_size: Optional[int],
    cache_type: str,
    cache_options: Optional[dict],
    compression: Optional[str],
    kwargs,
) -> AsyncGenerator[Union[AsyncWritableFile, AsyncReadableFile, 'HashingWriter'], None]
```
Asynchronously open the file and return a file-like object.

Use this method in async tasks to read from or write to files directly.

Example (Async Read):

```python
@env.task
async def read_file(f: File) -> str:
    async with f.open("rb") as fh:
        content = bytes(await fh.read())
        return content.decode("utf-8")
```

Example (Async Write):

```python
@env.task
async def write_file() -> File:
    f = File.new_remote()
    async with f.open("wb") as fh:
        await fh.write(b"Hello, World!")
    return f
```

Example (Streaming Read):

```python
@env.task
async def stream_read(f: File) -> str:
    content_parts = []
    async with f.open("rb", block_size=1024) as fh:
        while True:
            chunk = await fh.read()
            if not chunk:
                break
            content_parts.append(chunk)
    return b"".join(content_parts).decode("utf-8")
```

| Parameter | Type | Description |
|-|-|-|
| `mode` | `str` | The mode to open the file in (default: 'rb'). Common modes: 'rb' (read binary), 'wb' (write binary), 'rt' (read text), 'wt' (write text) |
| `block_size` | `Optional[int]` | Size of blocks for reading in bytes. Useful for streaming large files. |
| `cache_type` | `str` | Caching mechanism to use ('readahead', 'mmap', 'bytes', 'none') |
| `cache_options` | `Optional[dict]` | Dictionary of options for the cache |
| `compression` | `Optional[str]` | Compression format or None for auto-detection |
| `kwargs` | `**kwargs` | |

**Returns:** An async file-like object that can be used with async read/write operations

### open_sync()

```python
def open_sync(
    mode: str,
    block_size: Optional[int],
    cache_type: str,
    cache_options: Optional[dict],
    compression: Optional[str],
    kwargs,
) -> Generator[IO[Any], None, None]
```
Synchronously open the file and return a file-like object.

Use this method in non-async tasks to read from or write to files directly.

Example (Sync Read):

```python
@env.task
def read_file_sync(f: File) -> str:
    with f.open_sync("rb") as fh:
        content = fh.read()
        return content.decode("utf-8")
```

Example (Sync Write):

```python
@env.task
def write_file_sync() -> File:
    f = File.new_remote()
    with f.open_sync("wb") as fh:
        fh.write(b"Hello, World!")
    return f
```

| Parameter | Type | Description |
|-|-|-|
| `mode` | `str` | The mode to open the file in (default: 'rb'). Common modes: 'rb' (read binary), 'wb' (write binary), 'rt' (read text), 'wt' (write text) |
| `block_size` | `Optional[int]` | Size of blocks for reading in bytes. Useful for streaming large files. |
| `cache_type` | `str` | Caching mechanism to use ('readahead', 'mmap', 'bytes', 'none') |
| `cache_options` | `Optional[dict]` | Dictionary of options for the cache |
| `compression` | `Optional[str]` | Compression format or None for auto-detection |
| `kwargs` | `**kwargs` | |

**Returns:** A file-like object that can be used with standard read/write operations

### pre_init()

```python
def pre_init(
    data,
)
```
Internal: Pydantic validator to set default name from path. Not intended for direct use.

| Parameter | Type | Description |
|-|-|-|
| `data` |  | |

### schema_match()

```python
def schema_match(
    incoming: dict,
)
```
Internal: Check if incoming schema matches File schema. Not intended for direct use.

| Parameter | Type | Description |
|-|-|-|
| `incoming` | `dict` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.io/hashfunction ===

# HashFunction

**Package:** `flyte.io`

A hash method that wraps a user-provided function to compute hashes.

This class allows you to define custom hashing logic by providing a callable
that takes data and returns a hash string. It implements the HashMethod protocol,
making it compatible with Flyte's hashing infrastructure.

## Parameters

```python
class HashFunction(
    fn: Callable[[Any], str],
)
```
Initialize a HashFunction with a custom hash callable.

| Parameter | Type | Description |
|-|-|-|
| `fn` | `Callable[[Any], str]` | |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.io > HashFunction > Methods > from_fn()** | Create a HashFunction from a callable. |
| **Flyte SDK > Packages > flyte.io > HashFunction > Methods > reset()** |  |
| **Flyte SDK > Packages > flyte.io > HashFunction > Methods > result()** | Return the most recently computed hash value. |
| **Flyte SDK > Packages > flyte.io > HashFunction > Methods > update()** | Update the hash value by applying the hash function to the given data. |

### from_fn()

```python
def from_fn(
    fn: Callable[[Any], str],
) -> HashFunction
```
Create a HashFunction from a callable.

This is a convenience factory method for creating HashFunction instances.

| Parameter | Type | Description |
|-|-|-|
| `fn` | `Callable[[Any], str]` | A callable that takes data of any type and returns a hash string. |

**Returns**

A new HashFunction instance wrapping the provided callable.

### reset()

```python
def reset()
```
### result()

```python
def result()
```
Return the most recently computed hash value.

**Returns:** The hash string from the last call to update().

### update()

```python
def update(
    data: Any,
)
```
Update the hash value by applying the hash function to the given data.

| Parameter | Type | Description |
|-|-|-|
| `data` | `Any` | The data to hash. The type depends on the hash function provided. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.io.extend ===

# flyte.io.extend

## Directory

### Classes

| Class | Description |
|-|-|
| **Flyte SDK > Packages > flyte.io.extend > DataFrameDecoder** |  |
| **Flyte SDK > Packages > flyte.io.extend > DataFrameEncoder** |  |
| **Flyte SDK > Packages > flyte.io.extend > DataFrameTransformerEngine** | Think of this transformer as a higher-level meta transformer that is used for all the dataframe types. |

## Subpages
- **Flyte SDK > Packages > flyte.io.extend > DataFrameDecoder**
- **Flyte SDK > Packages > flyte.io.extend > DataFrameEncoder**
- **Flyte SDK > Packages > flyte.io.extend > DataFrameTransformerEngine**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.io.extend/dataframedecoder ===

# DataFrameDecoder

**Package:** `flyte.io.extend`

## Parameters

```python
class DataFrameDecoder(
    python_type: Type[DF],
    protocol: Optional[str],
    supported_format: Optional[str],
    additional_protocols: Optional[List[str]],
)
```
Extend this abstract class, implement the decode function, and register your concrete class with the
DataFrameTransformerEngine class in order for the core flytekit type engine to handle
dataframe libraries. This is the decoder interface, meaning it is used when there is a Flyte Literal value,
and we have to get a Python value out of it. For the other way, see the DataFrameEncoder

| Parameter | Type | Description |
|-|-|-|
| `python_type` | `Type[DF]` | The dataframe class in question that you want to register this decoder with |
| `protocol` | `Optional[str]` | A prefix representing the storage driver (e.g. 's3, 'gs', 'bq', etc.). You can use either "s3" or "s3://". They are the same since the "://" will just be stripped by the constructor. If None, this decoder will be registered with all protocols that flytekit's data persistence layer is capable of handling. |
| `supported_format` | `Optional[str]` | Arbitrary string representing the format. If not supplied then an empty string will be used. An empty string implies that the decoder works with any format. If the format being asked for does not exist, the transformer enginer will look for the "" decoder instead and write a warning. |
| `additional_protocols` | `Optional[List[str]]` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `protocol` | `None` |  |
| `python_type` | `None` |  |
| `supported_format` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.io.extend > DataFrameDecoder > Methods > decode()** | This is code that will be called by the dataset transformer engine to ultimately translate from a Flyte Literal. |

### decode()

```python
def decode(
    flyte_value: literals_pb2.StructuredDataset,
    current_task_metadata: literals_pb2.StructuredDatasetMetadata,
) -> Union[DF, typing.AsyncIterator[DF]]
```
This is code that will be called by the dataset transformer engine to ultimately translate from a Flyte Literal
value into a Python instance.

    of those dataframes.

| Parameter | Type | Description |
|-|-|-|
| `flyte_value` | `literals_pb2.StructuredDataset` | This will be a Flyte IDL DataFrame Literal - do not confuse this with the DataFrame class defined also in this module. |
| `current_task_metadata` | `literals_pb2.StructuredDatasetMetadata` | Metadata object containing the type (and columns if any) for the currently executing task. This type may have more or less information than the type information bundled inside the incoming flyte_value. |

**Returns:** This function can either return an instance of the dataframe that this decoder handles, or an iterator


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.io.extend/dataframeencoder ===

# DataFrameEncoder

**Package:** `flyte.io.extend`

## Parameters

```python
class DataFrameEncoder(
    python_type: Type[T],
    protocol: Optional[str],
    supported_format: Optional[str],
)
```
Extend this abstract class, implement the encode function, and register your concrete class with the
DataFrameTransformerEngine class in order for the core flytekit type engine to handle
dataframe libraries. This is the encoding interface, meaning it is used when there is a Python value that the
flytekit type engine is trying to convert into a Flyte Literal. For the other way, see
the DataFrameEncoder

| Parameter | Type | Description |
|-|-|-|
| `python_type` | `Type[T]` | The dataframe class in question that you want to register this encoder with |
| `protocol` | `Optional[str]` | A prefix representing the storage driver (e.g. 's3, 'gs', 'bq', etc.). You can use either "s3" or "s3://". They are the same since the "://" will just be stripped by the constructor. If None, this encoder will be registered with all protocols that flytekit's data persistence layer is capable of handling. |
| `supported_format` | `Optional[str]` | Arbitrary string representing the format. If not supplied then an empty string will be used. An empty string implies that the encoder works with any format. If the format being asked for does not exist, the transformer engine will look for the "" encoder instead and write a warning. |

## Properties

| Property | Type | Description |
|-|-|-|
| `protocol` | `None` |  |
| `python_type` | `None` |  |
| `supported_format` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.io.extend > DataFrameEncoder > Methods > encode()** | Even if the user code returns a plain dataframe instance, the dataset transformer engine will wrap the. |

### encode()

```python
def encode(
    dataframe: DataFrame,
    structured_dataset_type: types_pb2.StructuredDatasetType,
) -> literals_pb2.StructuredDataset
```
Even if the user code returns a plain dataframe instance, the dataset transformer engine will wrap the
incoming dataframe with defaults set for that dataframe
type. This simplifies this function's interface as a lot of data that could be specified by the user using
the
# TODO: Do we need to add a flag to indicate if it was wrapped by the transformer or by the user?

  DataFrame wrapper class used as input to this function - that is the user facing Python class.
  This function needs to return the IDL DataFrame.

| Parameter | Type | Description |
|-|-|-|
| `dataframe` | `DataFrame` | This is a DataFrame wrapper object. See more info above. |
| `structured_dataset_type` | `types_pb2.StructuredDatasetType` | This the DataFrameType, as found in the LiteralType of the interface of the task that invoked this encoding call. It is passed along to encoders so that authors of encoders can include it in the returned literals.DataFrame. See the IDL for more information on why this literal in particular carries the type information along with it. If the encoder doesn't supply it, it will also be filled in after the encoder runs by the transformer engine. |

**Returns:** This function should return a DataFrame literal object. Do not confuse this with the


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.io.extend/dataframetransformerengine ===

# DataFrameTransformerEngine

**Package:** `flyte.io.extend`

Think of this transformer as a higher-level meta transformer that is used for all the dataframe types.
If you are bringing a custom data frame type, or any data frame type, to flytekit, instead of
registering with the main type engine, you should register with this transformer instead.

## Parameters

```python
def DataFrameTransformerEngine()
```
## Properties

| Property | Type | Description |
|-|-|-|
| `name` | `None` |  |
| `python_type` | `None` | This returns the python type |
| `type_assertions_enabled` | `None` | Indicates if the transformer wants type assertions to be enabled at the core type engine layer |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.io.extend > DataFrameTransformerEngine > Methods > assert_type()** |  |
| **Flyte SDK > Packages > flyte.io.extend > DataFrameTransformerEngine > Methods > encode()** |  |
| **Flyte SDK > Packages > flyte.io.extend > DataFrameTransformerEngine > Methods > from_binary_idl()** | This function primarily handles deserialization for untyped dicts, dataclasses, Pydantic BaseModels, and. |
| **Flyte SDK > Packages > flyte.io.extend > DataFrameTransformerEngine > Methods > get_decoder()** |  |
| **Flyte SDK > Packages > flyte.io.extend > DataFrameTransformerEngine > Methods > get_encoder()** |  |
| **Flyte SDK > Packages > flyte.io.extend > DataFrameTransformerEngine > Methods > get_literal_type()** | Provide a concrete implementation so that writers of custom dataframe handlers since there's nothing that. |
| **Flyte SDK > Packages > flyte.io.extend > DataFrameTransformerEngine > Methods > get_structured_dataset_type()** |  |
| **Flyte SDK > Packages > flyte.io.extend > DataFrameTransformerEngine > Methods > guess_python_type()** | Converts the Flyte LiteralType to a python object type. |
| **Flyte SDK > Packages > flyte.io.extend > DataFrameTransformerEngine > Methods > isinstance_generic()** |  |
| **Flyte SDK > Packages > flyte.io.extend > DataFrameTransformerEngine > Methods > iter_as()** |  |
| **Flyte SDK > Packages > flyte.io.extend > DataFrameTransformerEngine > Methods > open_as()** |  |
| **Flyte SDK > Packages > flyte.io.extend > DataFrameTransformerEngine > Methods > register()** | Call this with any Encoder or Decoder to register it with the flytekit type system. |
| **Flyte SDK > Packages > flyte.io.extend > DataFrameTransformerEngine > Methods > register_for_protocol()** | See the main register function instead. |
| **Flyte SDK > Packages > flyte.io.extend > DataFrameTransformerEngine > Methods > register_renderer()** |  |
| **Flyte SDK > Packages > flyte.io.extend > DataFrameTransformerEngine > Methods > schema_match()** | Check if a JSON schema fragment matches this transformer's python_type. |
| **Flyte SDK > Packages > flyte.io.extend > DataFrameTransformerEngine > Methods > to_html()** | Converts any python val (dataframe, int, float) to a html string, and it will be wrapped in the HTML div. |
| **Flyte SDK > Packages > flyte.io.extend > DataFrameTransformerEngine > Methods > to_literal()** | Converts a given python_val to a Flyte Literal, assuming the given python_val matches the declared python_type. |
| **Flyte SDK > Packages > flyte.io.extend > DataFrameTransformerEngine > Methods > to_python_value()** | The only tricky thing with converting a Literal (say the output of an earlier task), to a Python value at. |

### assert_type()

```python
def assert_type(
    t: Type[DataFrame],
    v: typing.Any,
)
```
| Parameter | Type | Description |
|-|-|-|
| `t` | `Type[DataFrame]` | |
| `v` | `typing.Any` | |

### encode()

```python
def encode(
    df: DataFrame,
    df_type: Type,
    protocol: str,
    format: str,
    structured_literal_type: types_pb2.StructuredDatasetType,
) -> literals_pb2.Literal
```
| Parameter | Type | Description |
|-|-|-|
| `df` | `DataFrame` | |
| `df_type` | `Type` | |
| `protocol` | `str` | |
| `format` | `str` | |
| `structured_literal_type` | `types_pb2.StructuredDatasetType` | |

### from_binary_idl()

```python
def from_binary_idl(
    binary_idl_object: Binary,
    expected_python_type: Type[T],
) -> Optional[T]
```
This function primarily handles deserialization for untyped dicts, dataclasses, Pydantic BaseModels, and
 attribute access.

For untyped dict, dataclass, and pydantic basemodel:
Life Cycle (Untyped Dict as example):
    python val -&gt; msgpack bytes -&gt; binary literal scalar -&gt; msgpack bytes -&gt; python val
                  (to_literal)                             (from_binary_idl)

For attribute access:
Life Cycle:
    python val -&gt; msgpack bytes -&gt; binary literal scalar -&gt; resolved golang value -&gt; binary literal scalar
     -&gt; msgpack bytes -&gt; python val
                  (to_literal)      (propeller attribute access)     (from_binary_idl)

| Parameter | Type | Description |
|-|-|-|
| `binary_idl_object` | `Binary` | |
| `expected_python_type` | `Type[T]` | |

### get_decoder()

```python
def get_decoder(
    df_type: Type,
    protocol: str,
    format: str,
) -> DataFrameDecoder
```
| Parameter | Type | Description |
|-|-|-|
| `df_type` | `Type` | |
| `protocol` | `str` | |
| `format` | `str` | |

### get_encoder()

```python
def get_encoder(
    df_type: Type,
    protocol: str,
    format: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `df_type` | `Type` | |
| `protocol` | `str` | |
| `format` | `str` | |

### get_literal_type()

```python
def get_literal_type(
    t: typing.Union[Type[DataFrame], typing.Any],
) -> types_pb2.LiteralType
```
Provide a concrete implementation so that writers of custom dataframe handlers since there's nothing that
special about the literal type. Any dataframe type will always be associated with the structured dataset type.
The other aspects of it - columns, external schema type, etc. can be read from associated metadata.

| Parameter | Type | Description |
|-|-|-|
| `t` | `typing.Union[Type[DataFrame], typing.Any]` | The python dataframe type, which is mostly ignored. |

### get_structured_dataset_type()

```python
def get_structured_dataset_type(
    storage_format: str | None,
    pa_schema: Optional['pa.lib.Schema'],
    column_map: typing.OrderedDict[str, type[typing.Any]] | None,
) -> types_pb2.StructuredDatasetType
```
| Parameter | Type | Description |
|-|-|-|
| `storage_format` | `str \| None` | |
| `pa_schema` | `Optional['pa.lib.Schema']` | |
| `column_map` | `typing.OrderedDict[str, type[typing.Any]] \| None` | |

### guess_python_type()

```python
def guess_python_type(
    literal_type: types_pb2.LiteralType,
) -> Type[DataFrame]
```
Converts the Flyte LiteralType to a python object type.

| Parameter | Type | Description |
|-|-|-|
| `literal_type` | `types_pb2.LiteralType` | |

### isinstance_generic()

```python
def isinstance_generic(
    obj,
    generic_alias,
)
```
| Parameter | Type | Description |
|-|-|-|
| `obj` |  | |
| `generic_alias` |  | |

### iter_as()

```python
def iter_as(
    sd: literals_pb2.StructuredDataset,
    df_type: Type[DF],
    updated_metadata: literals_pb2.StructuredDatasetMetadata,
) -> typing.AsyncIterator[DF]
```
| Parameter | Type | Description |
|-|-|-|
| `sd` | `literals_pb2.StructuredDataset` | |
| `df_type` | `Type[DF]` | |
| `updated_metadata` | `literals_pb2.StructuredDatasetMetadata` | |

### open_as()

```python
def open_as(
    sd: literals_pb2.StructuredDataset,
    df_type: Type[DF],
    updated_metadata: literals_pb2.StructuredDatasetMetadata,
) -> DF
```
| Parameter | Type | Description |
|-|-|-|
| `sd` | `literals_pb2.StructuredDataset` | |
| `df_type` | `Type[DF]` | |
| `updated_metadata` | `literals_pb2.StructuredDatasetMetadata` | New metadata type, since it might be different from the metadata in the literal. |

**Returns:** dataframe. It could be pandas dataframe or arrow table, etc.

### register()

```python
def register(
    h: Handlers,
    default_for_type: bool,
    override: bool,
    default_format_for_type: bool,
    default_storage_for_type: bool,
)
```
Call this with any Encoder or Decoder to register it with the flytekit type system. If your handler does not
specify a protocol (e.g. s3, gs, etc.) field, then

| Parameter | Type | Description |
|-|-|-|
| `h` | `Handlers` | The DataFrameEncoder or DataFrameDecoder you wish to register with this transformer. |
| `default_for_type` | `bool` | If set, when a user returns from a task an instance of the dataframe the handler handles, e.g. `return pd.DataFrame(...)`, not wrapped around the `StructuredDataset` object, we will use this handler's protocol and format as the default, effectively saying that this handler will be called. Note that this shouldn't be set if your handler's protocol is None, because that implies that your handler is capable of handling all the different storage protocols that flytekit's data persistence layer is aware of. In these cases, the protocol is determined by the raw output data prefix set in the active context. |
| `override` | `bool` | Override any previous registrations. If default_for_type is also set, this will also override the default. |
| `default_format_for_type` | `bool` | Unlike the default_for_type arg that will set this handler's format and storage as the default, this will only set the format. Error if already set, unless override is specified. |
| `default_storage_for_type` | `bool` | Same as above but only for the storage format. Error if already set, unless override is specified. |

### register_for_protocol()

```python
def register_for_protocol(
    h: Handlers,
    protocol: str,
    default_for_type: bool,
    override: bool,
    default_format_for_type: bool,
    default_storage_for_type: bool,
)
```
See the main register function instead.

| Parameter | Type | Description |
|-|-|-|
| `h` | `Handlers` | |
| `protocol` | `str` | |
| `default_for_type` | `bool` | |
| `override` | `bool` | |
| `default_format_for_type` | `bool` | |
| `default_storage_for_type` | `bool` | |

### register_renderer()

```python
def register_renderer(
    python_type: Type,
    renderer: Renderable,
)
```
| Parameter | Type | Description |
|-|-|-|
| `python_type` | `Type` | |
| `renderer` | `Renderable` | |

### schema_match()

```python
def schema_match(
    schema: dict,
) -> bool
```
Check if a JSON schema fragment matches this transformer's python_type.

For BaseModel subclasses, automatically compares the schema's title, type, and
required fields against the type's own JSON schema. For other types, returns
False by default — override if needed.

| Parameter | Type | Description |
|-|-|-|
| `schema` | `dict` | |

### to_html()

```python
def to_html(
    python_val: typing.Any,
    expected_python_type: Type[T],
) -> str
```
Converts any python val (dataframe, int, float) to a html string, and it will be wrapped in the HTML div

| Parameter | Type | Description |
|-|-|-|
| `python_val` | `typing.Any` | |
| `expected_python_type` | `Type[T]` | |

### to_literal()

```python
def to_literal(
    python_val: Union[DataFrame, typing.Any],
    python_type: Union[Type[DataFrame], Type],
    expected: types_pb2.LiteralType,
) -> literals_pb2.Literal
```
Converts a given python_val to a Flyte Literal, assuming the given python_val matches the declared python_type.
Implementers should refrain from using type(python_val) instead rely on the passed in python_type. If these
do not match (or are not allowed) the Transformer implementer should raise an AssertionError, clearly stating
what was the mismatch

| Parameter | Type | Description |
|-|-|-|
| `python_val` | `Union[DataFrame, typing.Any]` | The actual value to be transformed |
| `python_type` | `Union[Type[DataFrame], Type]` | The assumed type of the value (this matches the declared type on the function) |
| `expected` | `types_pb2.LiteralType` | Expected Literal Type |

### to_python_value()

```python
def to_python_value(
    lv: literals_pb2.Literal,
    expected_python_type: Type[T] | DataFrame,
) -> T | DataFrame
```
The only tricky thing with converting a Literal (say the output of an earlier task), to a Python value at
the start of a task execution, is the column subsetting behavior. For example, if you have,

def t1() -&gt; Annotated[StructuredDataset, kwtypes(col_a=int, col_b=float)]: ...
def t2(in_a: Annotated[StructuredDataset, kwtypes(col_b=float)]): ...

where t2(in_a=t1()), when t2 does in_a.open(pd.DataFrame).all(), it should get a DataFrame
with only one column.

+-----------------------------+-----------------------------------------+--------------------------------------+
|                             |          StructuredDatasetType of the incoming Literal                         |
+-----------------------------+-----------------------------------------+--------------------------------------+
| StructuredDatasetType       | Has columns defined                     |  [] columns or None                  |
| of currently running task   |                                         |                                      |
+=============================+=========================================+======================================+
|    Has columns              | The StructuredDatasetType passed to the decoder will have the columns          |
|    defined                  | as defined by the type annotation of the currently running task.               |
|                             |                                                                                |
|                             | Decoders **should** then subset the incoming data to the columns requested.    |
|                             |                                                                                |
+-----------------------------+-----------------------------------------+--------------------------------------+
|   [] columns or None        | StructuredDatasetType passed to decoder | StructuredDatasetType passed to the  |
|                             | will have the columns from the incoming | decoder will have an empty list of   |
|                             | Literal. This is the scenario where     | columns.                             |
|                             | the Literal returned by the running     |                                      |
|                             | task will have more information than    |                                      |
|                             | the running task's signature.           |                                      |
+-----------------------------+-----------------------------------------+--------------------------------------+

| Parameter | Type | Description |
|-|-|-|
| `lv` | `literals_pb2.Literal` | |
| `expected_python_type` | `Type[T] \| DataFrame` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.models ===

# flyte.models

## Directory

### Classes

| Class | Description |
|-|-|
| **Flyte SDK > Packages > flyte.models > ActionID** | A class representing the ID of an Action, nested within a Run. |
| **Flyte SDK > Packages > flyte.models > ActionPhase** | Represents the execution phase of a Flyte action (run). |
| **Flyte SDK > Packages > flyte.models > Checkpoints** | A class representing the checkpoints for a task. |
| **Flyte SDK > Packages > flyte.models > CodeBundle** | A class representing a code bundle for a task. |
| **Flyte SDK > Packages > flyte.models > GroupData** |  |
| **Flyte SDK > Packages > flyte.models > NativeInterface** | A class representing the native interface for a task. |
| **Flyte SDK > Packages > flyte.models > PathRewrite** | Configuration for rewriting paths during input loading. |
| **Flyte SDK > Packages > flyte.models > RawDataPath** | A class representing the raw data path for a task. |
| **Flyte SDK > Packages > flyte.models > SerializationContext** | This object holds serialization time contextual information, that can be used when serializing the task and. |
| **Flyte SDK > Packages > flyte.models > TaskContext** | A context class to hold the current task executions context. |

### Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.models > Methods > generate_random_name()** | Generate a random name for the task. |

### Variables

| Property | Type | Description |
|-|-|-|
| `MAX_INLINE_IO_BYTES` | `int` |  |
| `TYPE_CHECKING` | `bool` |  |

## Methods

#### generate_random_name()

```python
def generate_random_name()
```
Generate a random name for the task. This is used to create unique names for tasks.
TODO we can use unique-namer in the future, for now its just guids

## Subpages
- **Flyte SDK > Packages > flyte.models > ActionID**
- **Flyte SDK > Packages > flyte.models > ActionPhase**
- **Flyte SDK > Packages > flyte.models > Checkpoints**
- **Flyte SDK > Packages > flyte.models > CodeBundle**
- **Flyte SDK > Packages > flyte.models > GroupData**
- **Flyte SDK > Packages > flyte.models > NativeInterface**
- **Flyte SDK > Packages > flyte.models > PathRewrite**
- **Flyte SDK > Packages > flyte.models > RawDataPath**
- **Flyte SDK > Packages > flyte.models > SerializationContext**
- **Flyte SDK > Packages > flyte.models > TaskContext**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.models/actionid ===

# ActionID

**Package:** `flyte.models`

A class representing the ID of an Action, nested within a Run. This is used to identify a specific action on a task.

## Parameters

```python
class ActionID(
    name: str,
    run_name: str | None,
    project: str | None,
    domain: str | None,
    org: str | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |
| `run_name` | `str \| None` | |
| `project` | `str \| None` | |
| `domain` | `str \| None` | |
| `org` | `str \| None` | |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.models > ActionID > Methods > create_random()** |  |
| **Flyte SDK > Packages > flyte.models > ActionID > Methods > new_sub_action()** | Create a new sub-run with the given name. |
| **Flyte SDK > Packages > flyte.models > ActionID > Methods > new_sub_action_from()** | Make a deterministic name. |
| **Flyte SDK > Packages > flyte.models > ActionID > Methods > unique_id_str()** | Generate a unique ID string for this action in the format:. |

### create_random()

```python
def create_random()
```
### new_sub_action()

```python
def new_sub_action(
    name: str | None,
) -> ActionID
```
Create a new sub-run with the given name. If  name is None, a random name will be generated.

| Parameter | Type | Description |
|-|-|-|
| `name` | `str \| None` | |

### new_sub_action_from()

```python
def new_sub_action_from(
    task_call_seq: int,
    task_hash: str,
    input_hash: str,
    group: str | None,
) -> ActionID
```
Make a deterministic name

| Parameter | Type | Description |
|-|-|-|
| `task_call_seq` | `int` | |
| `task_hash` | `str` | |
| `input_hash` | `str` | |
| `group` | `str \| None` | |

### unique_id_str()

```python
def unique_id_str(
    salt: str | None,
) -> str
```
Generate a unique ID string for this action in the format:
{project}-{domain}-{run_name}-{action_name}

This is optimized for performance assuming all fields are available.

| Parameter | Type | Description |
|-|-|-|
| `salt` | `str \| None` | |

**Returns:** A unique ID string


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.models/actionphase ===

# ActionPhase

**Package:** `flyte.models`

Represents the execution phase of a Flyte action (run).

Actions progress through different phases during their lifecycle:
- Queued: Action is waiting to be scheduled
- Waiting for resources: Action is waiting for compute resources
- Initializing: Action is being initialized
- Running: Action is currently executing
- Succeeded: Action completed successfully
- Failed: Action failed during execution
- Aborted: Action was manually aborted
- Timed out: Action exceeded its timeout limit

This enum can be used for filtering runs and checking execution status.

## Parameters

```python
class ActionPhase(
    args,
    kwds,
)
```
| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwds` |  | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.models/checkpoints ===

# Checkpoints

**Package:** `flyte.models`

A class representing the checkpoints for a task. This is used to store the checkpoints for the task execution.

## Parameters

```python
class Checkpoints(
    prev_checkpoint_path: str | None,
    checkpoint_path: str | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `prev_checkpoint_path` | `str \| None` | |
| `checkpoint_path` | `str \| None` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.models/codebundle ===

# CodeBundle

**Package:** `flyte.models`

A class representing a code bundle for a task. This is used to package the code and the inflation path.
The code bundle computes the version of the code using the hash of the code.

## Parameters

```python
class CodeBundle(
    computed_version: str,
    destination: str,
    tgz: str | None,
    pkl: str | None,
    downloaded_path: pathlib.Path | None,
    files: List[str] | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `computed_version` | `str` | The version of the code bundle. This is the hash of the code. |
| `destination` | `str` | The destination path for the code bundle to be inflated to. |
| `tgz` | `str \| None` | Optional path to the tgz file. |
| `pkl` | `str \| None` | Optional path to the pkl file. |
| `downloaded_path` | `pathlib.Path \| None` | The path to the downloaded code bundle. This is only available during runtime, when the code bundle has been downloaded and inflated. |
| `files` | `List[str] \| None` | |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.models > CodeBundle > Methods > with_downloaded_path()** | Create a new CodeBundle with the given downloaded path. |

### with_downloaded_path()

```python
def with_downloaded_path(
    path: pathlib.Path,
) -> CodeBundle
```
Create a new CodeBundle with the given downloaded path.

| Parameter | Type | Description |
|-|-|-|
| `path` | `pathlib.Path` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.models/groupdata ===

# GroupData

**Package:** `flyte.models`

## Parameters

```python
class GroupData(
    name: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.models/nativeinterface ===

# NativeInterface

**Package:** `flyte.models`

A class representing the native interface for a task. This is used to interact with the task and its execution
context.

## Parameters

```python
class NativeInterface(
    inputs: Dict[str, Tuple[Type, Any]],
    outputs: Dict[str, Type],
    docstring: Optional[Docstring],
    _remote_defaults: Optional[Dict[str, literals_pb2.Literal]],
)
```
| Parameter | Type | Description |
|-|-|-|
| `inputs` | `Dict[str, Tuple[Type, Any]]` | |
| `outputs` | `Dict[str, Type]` | |
| `docstring` | `Optional[Docstring]` | |
| `_remote_defaults` | `Optional[Dict[str, literals_pb2.Literal]]` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `json_schema` | `None` | Convert task inputs to a JSON schema dict.  Uses the Flyte type engine to produce a LiteralType for each input, then converts to JSON schema. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.models > NativeInterface > Methods > convert_to_kwargs()** | Convert the given arguments to keyword arguments based on the native interface. |
| **Flyte SDK > Packages > flyte.models > NativeInterface > Methods > from_callable()** | Extract the native interface from the given function. |
| **Flyte SDK > Packages > flyte.models > NativeInterface > Methods > from_types()** | Create a new NativeInterface from the given types. |
| **Flyte SDK > Packages > flyte.models > NativeInterface > Methods > get_input_types()** | Get the input types for the task. |
| **Flyte SDK > Packages > flyte.models > NativeInterface > Methods > has_outputs()** | Check if the task has outputs. |
| **Flyte SDK > Packages > flyte.models > NativeInterface > Methods > num_required_inputs()** | Get the number of required inputs for the task. |
| **Flyte SDK > Packages > flyte.models > NativeInterface > Methods > required_inputs()** | Get the names of the required inputs for the task. |

### convert_to_kwargs()

```python
def convert_to_kwargs(
    args,
    kwargs,
) -> Dict[str, Any]
```
Convert the given arguments to keyword arguments based on the native interface. This is used to convert the
arguments to the correct types for the task execution.

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### from_callable()

```python
def from_callable(
    func: Callable,
) -> NativeInterface
```
Extract the native interface from the given function. This is used to create a native interface for the task.

| Parameter | Type | Description |
|-|-|-|
| `func` | `Callable` | |

### from_types()

```python
def from_types(
    inputs: Dict[str, Tuple[Type, Type[_has_default] | Type[inspect._empty]]],
    outputs: Dict[str, Type],
    default_inputs: Optional[Dict[str, literals_pb2.Literal]],
) -> NativeInterface
```
Create a new NativeInterface from the given types. This is used to create a native interface for the task.

| Parameter | Type | Description |
|-|-|-|
| `inputs` | `Dict[str, Tuple[Type, Type[_has_default] \| Type[inspect._empty]]]` | A dictionary of input names and their types and a value indicating if they have a default value. |
| `outputs` | `Dict[str, Type]` | A dictionary of output names and their types. |
| `default_inputs` | `Optional[Dict[str, literals_pb2.Literal]]` | Optional dictionary of default inputs for remote tasks. |

**Returns:** A NativeInterface object with the given inputs and outputs.

### get_input_types()

```python
def get_input_types()
```
Get the input types for the task. This is used to get the types of the inputs for the task execution.

### has_outputs()

```python
def has_outputs()
```
Check if the task has outputs. This is used to determine if the task has outputs or not.

### num_required_inputs()

```python
def num_required_inputs()
```
Get the number of required inputs for the task. This is used to determine how many inputs are required for the
task execution.

### required_inputs()

```python
def required_inputs()
```
Get the names of the required inputs for the task. This is used to determine which inputs are required for the
task execution.

**Returns:** A list of required input names.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.models/pathrewrite ===

# PathRewrite

**Package:** `flyte.models`

Configuration for rewriting paths during input loading.

## Parameters

```python
class PathRewrite(
    old_prefix: str,
    new_prefix: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `old_prefix` | `str` | |
| `new_prefix` | `str` | |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.models > PathRewrite > Methods > from_str()** | Create a PathRewrite from a string pattern of the form `old_prefix->new_prefix`. |

### from_str()

```python
def from_str(
    pattern: str,
) -> PathRewrite
```
Create a PathRewrite from a string pattern of the form `old_prefix-&gt;new_prefix`.

| Parameter | Type | Description |
|-|-|-|
| `pattern` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.models/rawdatapath ===

# RawDataPath

**Package:** `flyte.models`

A class representing the raw data path for a task. This is used to store the raw data for the task execution and
also get mutations on the path.

## Parameters

```python
class RawDataPath(
    path: str,
    path_rewrite: Optional[PathRewrite],
)
```
| Parameter | Type | Description |
|-|-|-|
| `path` | `str` | |
| `path_rewrite` | `Optional[PathRewrite]` | |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.models > RawDataPath > Methods > from_local_folder()** | Create a new context attribute object, with local path given. |
| **Flyte SDK > Packages > flyte.models > RawDataPath > Methods > get_random_remote_path()** | Returns a random path for uploading a file/directory to. |

### from_local_folder()

```python
def from_local_folder(
    local_folder: str | pathlib.Path | None,
) -> RawDataPath
```
Create a new context attribute object, with local path given. Will be created if it doesn't exist.

| Parameter | Type | Description |
|-|-|-|
| `local_folder` | `str \| pathlib.Path \| None` | |

**Returns:** Path to the temporary directory

### get_random_remote_path()

```python
def get_random_remote_path(
    file_name: Optional[str],
) -> str
```
Returns a random path for uploading a file/directory to. This file/folder will not be created, it's just a path.

| Parameter | Type | Description |
|-|-|-|
| `file_name` | `Optional[str]` | If given, will be joined after a randomly generated portion. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.models/serializationcontext ===

# SerializationContext

**Package:** `flyte.models`

This object holds serialization time contextual information, that can be used when serializing the task and
various parameters of a tasktemplate. This is only available when the task is being serialized and can be
during a deployment or runtime.

## Parameters

```python
class SerializationContext(
    version: str,
    project: str | None,
    domain: str | None,
    org: str | None,
    code_bundle: Optional[CodeBundle],
    input_path: str,
    output_path: str,
    interpreter_path: str,
    image_cache: ImageCache | None,
    root_dir: Optional[pathlib.Path],
)
```
| Parameter | Type | Description |
|-|-|-|
| `version` | `str` | The version of the task |
| `project` | `str \| None` | |
| `domain` | `str \| None` | |
| `org` | `str \| None` | |
| `code_bundle` | `Optional[CodeBundle]` | The code bundle for the task. This is used to package the code and the inflation path. |
| `input_path` | `str` | The path to the inputs for the task. This is used to determine where the inputs will be located |
| `output_path` | `str` | The path to the outputs for the task. This is used to determine where the outputs will be located |
| `interpreter_path` | `str` | |
| `image_cache` | `ImageCache \| None` | |
| `root_dir` | `Optional[pathlib.Path]` | |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.models > SerializationContext > Methods > get_entrypoint_path()** | Get the entrypoint path for the task. |

### get_entrypoint_path()

```python
def get_entrypoint_path(
    interpreter_path: Optional[str],
) -> str
```
Get the entrypoint path for the task. This is used to determine the entrypoint for the task execution.

| Parameter | Type | Description |
|-|-|-|
| `interpreter_path` | `Optional[str]` | The path to the interpreter (python) |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.models/taskcontext ===

# TaskContext

**Package:** `flyte.models`

A context class to hold the current task executions context.
This can be used to access various contextual parameters in the task execution by the user.

## Parameters

```python
class TaskContext(
    action: ActionID,
    version: str,
    raw_data_path: RawDataPath,
    input_path: str | None,
    output_path: str,
    run_base_dir: str,
    report: Report,
    group_data: GroupData | None,
    checkpoints: Checkpoints | None,
    code_bundle: CodeBundle | None,
    compiled_image_cache: ImageCache | None,
    data: Dict[str, Any],
    mode: Literal['local', 'remote', 'hybrid'],
    interactive_mode: bool,
    custom_context: Dict[str, str],
    disable_run_cache: bool,
    in_driver_literal_conversion: bool,
)
```
| Parameter | Type | Description |
|-|-|-|
| `action` | `ActionID` | The action ID of the current execution. This is always set, within a run. |
| `version` | `str` | The version of the executed task. This is set when the task is executed by an action and will be set on all sub-actions. |
| `raw_data_path` | `RawDataPath` | |
| `input_path` | `str \| None` | |
| `output_path` | `str` | |
| `run_base_dir` | `str` | |
| `report` | `Report` | |
| `group_data` | `GroupData \| None` | |
| `checkpoints` | `Checkpoints \| None` | |
| `code_bundle` | `CodeBundle \| None` | |
| `compiled_image_cache` | `ImageCache \| None` | |
| `data` | `Dict[str, Any]` | |
| `mode` | `Literal['local', 'remote', 'hybrid']` | |
| `interactive_mode` | `bool` | |
| `custom_context` | `Dict[str, str]` | Context metadata for the action. If an action receives context, it'll automatically pass it to any actions it spawns. Context will not be used for cache key computation. |
| `disable_run_cache` | `bool` | |
| `in_driver_literal_conversion` | `bool` | Set by the runtime during nested-task literal marshalling; type transformers may use it to skip duplicate side effects (e.g. report tabs) outside true task-body I/O. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.models > TaskContext > Methods > is_in_cluster()** | Check if the task is running in a cluster. |
| **Flyte SDK > Packages > flyte.models > TaskContext > Methods > replace()** |  |

### is_in_cluster()

```python
def is_in_cluster()
```
Check if the task is running in a cluster.

**Returns:** bool

### replace()

```python
def replace(
    kwargs,
) -> TaskContext
```
| Parameter | Type | Description |
|-|-|-|
| `kwargs` | `**kwargs` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.notify ===

# flyte.notify

Task Notifications API for Flyte 2.0

Send notifications when tasks reach specific execution phases.
Supports Email, Slack, Teams, and custom Webhooks.

Quick Start:
    ```python
    import flyte
    import flyte.models
    import flyte.notify as notify

    @flyte.task(
        trigger=flyte.Trigger(
            name="daily_report",
            automation=flyte.Cron("0 0 * * *"),
            notifications=[
                notify.Email(
                    on_phase=flyte.models.ActionPhase.FAILED,
                    recipients=["oncall@example.com"]
                ),
                notify.Slack(
                    on_phase=flyte.models.ActionPhase.SUCCEEDED,
                    webhook_url="https://hooks.slack.com/...",
                    message="Daily report completed! {run.url}"
                )
            ]
        )
    )
    def daily_report():
        # Your task logic here
        pass
    ```

Available Notification Types:
    - Email: Send email notifications
    - Slack: Send Slack messages (with optional Block Kit)
    - Teams: Send Microsoft Teams messages (with optional Adaptive Cards)
    - Webhook: Send custom HTTP requests (most flexible)

Supported Phases:
    - SUCCEEDED: Task completed successfully
    - FAILED: Task failed
    - TIMED_OUT: Task timed out
    - ABORTED: Task was aborted

Template Variables:
    All notification messages support template variables:
    - {task.name}: Task name
    - {run.name}: Run ID/name
    - {run.phase}: Current run phase
    - {run.error}: Error message (if failed)
    - {run.duration}: Run duration
    - {run.timestamp}: ISO 8601 timestamp
    - {run.url}: URL to run details page
    - {project}: Flyte project name
    - {domain}: Flyte domain name
## Directory

### Classes

| Class | Description |
|-|-|
| **Flyte SDK > Packages > flyte.notify > Email** | Send email notifications. |
| **Flyte SDK > Packages > flyte.notify > NamedDelivery** | Use a pre-configured delivery channel by name. |
| **Flyte SDK > Packages > flyte.notify > NamedRule** | Reference a pre-defined notification rule by name. |
| **Flyte SDK > Packages > flyte.notify > Notification** | Base notification class. |
| **Flyte SDK > Packages > flyte.notify > Slack** | Send Slack notifications with optional Block Kit formatting. |
| **Flyte SDK > Packages > flyte.notify > Teams** | Send Microsoft Teams notifications with optional Adaptive Cards. |
| **Flyte SDK > Packages > flyte.notify > Webhook** | Send custom HTTP webhook notifications (most flexible option). |

## Subpages
- **Flyte SDK > Packages > flyte.notify > Email**
- **Flyte SDK > Packages > flyte.notify > NamedDelivery**
- **Flyte SDK > Packages > flyte.notify > NamedRule**
- **Flyte SDK > Packages > flyte.notify > Notification**
- **Flyte SDK > Packages > flyte.notify > Slack**
- **Flyte SDK > Packages > flyte.notify > Teams**
- **Flyte SDK > Packages > flyte.notify > Webhook**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.notify/email ===

# Email

**Package:** `flyte.notify`

Send email notifications.

    Example:
        ```python
        Email(
            on_phase=ActionPhase.FAILED,
            recipients=["oncall@example.com"],
            subject="Alert: Task {task.name} failed",
            body="Error: {run.error}
Details: {run.url}"
        )
        ```

    Args:
        on_phase: ActionPhase(s) to trigger notification
            (e.g., ActionPhase.FAILED or (ActionPhase.FAILED, ActionPhase.TIMED_OUT))
        recipients: Email addresses for the "to" field.
        cc: Optional email addresses for the "cc" field.
        bcc: Optional email addresses for the "bcc" field.
        subject: Email subject template (supports template variables).
        body: Plain text body template (supports template variables).
        html_body: Optional HTML body template (supports template variables).
            When provided, the email is sent as multipart with both plain text and HTML.
    
## Parameters

```python
class Email(
    on_phase: typing.Union[flyte.models.ActionPhase, typing.Tuple[flyte.models.ActionPhase, ...]],
    recipients: typing.Tuple[str, ...],
    cc: typing.Tuple[str, ...],
    bcc: typing.Tuple[str, ...],
    subject: str,
    body: str,
    html_body: typing.Optional[str],
)
```
| Parameter | Type | Description |
|-|-|-|
| `on_phase` | `typing.Union[flyte.models.ActionPhase, typing.Tuple[flyte.models.ActionPhase, ...]]` | |
| `recipients` | `typing.Tuple[str, ...]` | |
| `cc` | `typing.Tuple[str, ...]` | |
| `bcc` | `typing.Tuple[str, ...]` | |
| `subject` | `str` | |
| `body` | `str` | |
| `html_body` | `typing.Optional[str]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.notify/nameddelivery ===

# NamedDelivery

**Package:** `flyte.notify`

Use a pre-configured delivery channel by name.

Use this when your Flyte admin has configured a named delivery config
(e.g., a shared Slack webhook or email list) that you want to reference
without specifying the delivery details inline.

## Parameters

```python
class NamedDelivery(
    on_phase: typing.Union[flyte.models.ActionPhase, typing.Tuple[flyte.models.ActionPhase, ...]],
    name: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `on_phase` | `typing.Union[flyte.models.ActionPhase, typing.Tuple[flyte.models.ActionPhase, ...]]` | ActionPhase(s) to trigger notification. |
| `name` | `str` | The name of the pre-configured delivery config (scoped to project/domain). |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.notify/namedrule ===

# NamedRule

**Package:** `flyte.notify`

Reference a pre-defined notification rule by name.

Use this when your Flyte admin has configured a named notification rule
that you want to apply to your runs. Named rules define both the phases
to monitor and the delivery channels to use.

## Parameters

```python
class NamedRule(
    name: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | The name of the pre-defined rule (scoped to project/domain). |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.notify/notification ===

# Notification

**Package:** `flyte.notify`

Base notification class.

All notification types must specify phases when they should trigger.

## Parameters

```python
class Notification(
    on_phase: typing.Union[flyte.models.ActionPhase, typing.Tuple[flyte.models.ActionPhase, ...]],
)
```
| Parameter | Type | Description |
|-|-|-|
| `on_phase` | `typing.Union[flyte.models.ActionPhase, typing.Tuple[flyte.models.ActionPhase, ...]]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.notify/slack ===

# Slack

**Package:** `flyte.notify`

Send Slack notifications with optional Block Kit formatting.

    Example:
        ```python
        Slack(
            on_phase=ActionPhase.FAILED,
            webhook_url="https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
            message="🚨 Task {task.name} failed: {run.error}
{run.url}",
        )
        ```

    Args:
        on_phase:ActionPhase(s) to trigger notification
        webhook_url: Slack webhook URL
        message: Simple text message (supports template variables)
        blocks: Optional Slack Block Kit blocks for rich formatting
            (if provided, message is ignored). See: https://api.slack.com/block-kit
    
## Parameters

```python
class Slack(
    on_phase: typing.Union[flyte.models.ActionPhase, typing.Tuple[flyte.models.ActionPhase, ...]],
    webhook_url: str,
    message: typing.Optional[str],
    blocks: typing.Optional[typing.Tuple[typing.Dict[str, typing.Any], ...]],
)
```
| Parameter | Type | Description |
|-|-|-|
| `on_phase` | `typing.Union[flyte.models.ActionPhase, typing.Tuple[flyte.models.ActionPhase, ...]]` | |
| `webhook_url` | `str` | |
| `message` | `typing.Optional[str]` | |
| `blocks` | `typing.Optional[typing.Tuple[typing.Dict[str, typing.Any], ...]]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.notify/teams ===

# Teams

**Package:** `flyte.notify`

Send Microsoft Teams notifications with optional Adaptive Cards.

    Example:
        ```python
        Teams(
            on_phase=ActionPhase.SUCCEEDED,
            webhook_url="https://outlook.office.com/webhook/YOUR_WEBHOOK_URL",
            title="✅ Task Complete",
            message="Task {task.name} completed in {run.duration}
[View Details]({run.url})"
        )
        ```

    Args:
        on_phase:ActionPhase(s) to trigger notification
        webhook_url: Microsoft Teams webhook URL
        title: Message card title (supports template variables)
        message: Simple text message (supports template variables)
        card: Optional Adaptive Card for rich formatting
            (if provided, title and message are ignored).
            See: https://adaptivecards.io/designer/
    
## Parameters

```python
class Teams(
    on_phase: typing.Union[flyte.models.ActionPhase, typing.Tuple[flyte.models.ActionPhase, ...]],
    webhook_url: str,
    title: str,
    message: typing.Optional[str],
    card: typing.Optional[typing.Dict[str, typing.Any]],
)
```
| Parameter | Type | Description |
|-|-|-|
| `on_phase` | `typing.Union[flyte.models.ActionPhase, typing.Tuple[flyte.models.ActionPhase, ...]]` | |
| `webhook_url` | `str` | |
| `title` | `str` | |
| `message` | `typing.Optional[str]` | |
| `card` | `typing.Optional[typing.Dict[str, typing.Any]]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.notify/webhook ===

# Webhook

**Package:** `flyte.notify`

Send custom HTTP webhook notifications (most flexible option).

## Parameters

```python
class Webhook(
    on_phase: typing.Union[flyte.models.ActionPhase, typing.Tuple[flyte.models.ActionPhase, ...]],
    url: str,
    method: typing.Literal['POST', 'PUT', 'PATCH', 'GET', 'DELETE', 'HEAD', 'OPTIONS', 'TRACE', 'CONNECT'],
    headers: typing.Optional[typing.Dict[str, str]],
    body: typing.Optional[typing.Dict[str, typing.Any]],
)
```
| Parameter | Type | Description |
|-|-|-|
| `on_phase` | `typing.Union[flyte.models.ActionPhase, typing.Tuple[flyte.models.ActionPhase, ...]]` | ActionPhase(s) to trigger notification |
| `url` | `str` | Webhook URL (supports template variables) |
| `method` | `typing.Literal['POST', 'PUT', 'PATCH', 'GET', 'DELETE', 'HEAD', 'OPTIONS', 'TRACE', 'CONNECT']` | HTTP method (default: "POST") |
| `headers` | `typing.Optional[typing.Dict[str, str]]` | Optional HTTP headers (values support template variables) |
| `body` | `typing.Optional[typing.Dict[str, typing.Any]]` | Optional request body as dict (all string values support template variables recursively) |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.prefetch ===

# flyte.prefetch

Prefetch utilities for Flyte.

This module provides functionality to prefetch various artifacts from remote registries,
such as HuggingFace models.
## Directory

### Classes

| Class | Description |
|-|-|
| **Flyte SDK > Packages > flyte.prefetch > HuggingFaceModelInfo** | Information about a HuggingFace model to store. |
| **Flyte SDK > Packages > flyte.prefetch > ShardConfig** | Configuration for model sharding. |
| **Flyte SDK > Packages > flyte.prefetch > StoredModelInfo** | Information about a stored model. |
| **Flyte SDK > Packages > flyte.prefetch > VLLMShardArgs** | Arguments for sharding a model using vLLM. |

### Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.prefetch > Methods > hf_model()** | Store a HuggingFace model to remote storage. |

## Methods

#### hf_model()

```python
def hf_model(
    repo: str,
    raw_data_path: str | None,
    artifact_name: str | None,
    architecture: str | None,
    task: str,
    modality: tuple[str, ...],
    serial_format: str | None,
    model_type: str | None,
    short_description: str | None,
    shard_config: ShardConfig | None,
    hf_token_key: str,
    resources: Resources,
    force: int,
) -> Run
```
Store a HuggingFace model to remote storage.

This function downloads a model from the HuggingFace Hub and prefetches it to
remote storage. It supports optional sharding using vLLM for large models.

The prefetch behavior follows this priority:
1. If the model isn't being sharded, stream files directly to remote storage.
2. If streaming fails, fall back to downloading a snapshot and uploading.
3. If sharding is configured, download locally, shard with vLLM, then upload.

Example usage:

```python
import flyte

flyte.init(endpoint="my-flyte-endpoint")

# Store a model without sharding
run = flyte.prefetch.hf_model(
    repo="meta-llama/Llama-2-7b-hf",
    hf_token_key="HF_TOKEN",
)
run.wait()

# Prefetch and shard a model
from flyte.prefetch import ShardConfig, VLLMShardArgs

run = flyte.prefetch.hf_model(
    repo="meta-llama/Llama-2-70b-hf",
    shard_config=ShardConfig(
        engine="vllm",
        args=VLLMShardArgs(tensor_parallel_size=8),
    ),
    accelerator="A100:8",
    hf_token_key="HF_TOKEN",
)
run.wait()
```

| Parameter | Type | Description |
|-|-|-|
| `repo` | `str` | The HuggingFace repository ID (e.g., 'meta-llama/Llama-2-7b-hf'). |
| `raw_data_path` | `str \| None` | |
| `artifact_name` | `str \| None` | Optional name for the stored artifact. If not provided, the repo name will be used (with '.' replaced by '-'). |
| `architecture` | `str \| None` | Model architecture from HuggingFace config.json. |
| `task` | `str` | Model task (e.g., 'generate', 'classify', 'embed'). Default |
| `modality` | `tuple[str, ...]` | Modalities supported by the model. Default |
| `serial_format` | `str \| None` | Model serialization format (e.g., 'safetensors', 'onnx'). |
| `model_type` | `str \| None` | Model type (e.g., 'transformer', 'custom'). |
| `short_description` | `str \| None` | Short description of the model. |
| `shard_config` | `ShardConfig \| None` | Optional configuration for model sharding with vLLM. |
| `hf_token_key` | `str` | Name of the secret containing the HuggingFace token. Default |
| `resources` | `Resources` | |
| `force` | `int` | Force re-prefetch. Increment to force a new prefetch. Default |

**Returns:** A Run object representing the prefetch task execution.

## Subpages
- **Flyte SDK > Packages > flyte.prefetch > HuggingFaceModelInfo**
- **Flyte SDK > Packages > flyte.prefetch > ShardConfig**
- **Flyte SDK > Packages > flyte.prefetch > StoredModelInfo**
- **Flyte SDK > Packages > flyte.prefetch > VLLMShardArgs**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.prefetch/huggingfacemodelinfo ===

# HuggingFaceModelInfo

**Package:** `flyte.prefetch`

Information about a HuggingFace model to store.

## Parameters

```python
class HuggingFaceModelInfo(
    repo: str,
    artifact_name: str | None,
    architecture: str | None,
    task: str,
    modality: tuple[str, ...],
    serial_format: str | None,
    model_type: str | None,
    short_description: str | None,
    shard_config: flyte.prefetch._hf_model.ShardConfig | None,
)
```
Create a new model by parsing and validating input data from keyword arguments.

Raises [`ValidationError`](https://docs.pydantic.dev/latest/api/pydantic_core/#pydantic_core.ValidationError) if the input data cannot be
validated to form a valid model.

`self` is explicitly positional-only to allow `self` as a field name.

| Parameter | Type | Description |
|-|-|-|
| `repo` | `str` | The HuggingFace repository ID (e.g., 'meta-llama/Llama-2-7b-hf'). |
| `artifact_name` | `str \| None` | Optional name for the stored artifact. If not provided, the repo name will be used (with '.' replaced by '-'). |
| `architecture` | `str \| None` | Model architecture from HuggingFace config.json. |
| `task` | `str` | Model task (e.g., 'generate', 'classify', 'embed'). |
| `modality` | `tuple[str, ...]` | Modalities supported by the model (e.g., 'text', 'image'). |
| `serial_format` | `str \| None` | Model serialization format (e.g., 'safetensors', 'onnx'). |
| `model_type` | `str \| None` | Model type (e.g., 'transformer', 'custom'). |
| `short_description` | `str \| None` | Short description of the model. |
| `shard_config` | `flyte.prefetch._hf_model.ShardConfig \| None` | Optional configuration for model sharding. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.prefetch/shardconfig ===

# ShardConfig

**Package:** `flyte.prefetch`

Configuration for model sharding.

## Parameters

```python
class ShardConfig(
    engine: typing.Literal['vllm'],
    args: *args,
)
```
Create a new model by parsing and validating input data from keyword arguments.

Raises [`ValidationError`](https://docs.pydantic.dev/latest/api/pydantic_core/#pydantic_core.ValidationError) if the input data cannot be
validated to form a valid model.

`self` is explicitly positional-only to allow `self` as a field name.

| Parameter | Type | Description |
|-|-|-|
| `engine` | `typing.Literal['vllm']` | The sharding engine to use (currently only "vllm" is supported). |
| `args` | `*args` | Arguments for the sharding engine. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.prefetch/storedmodelinfo ===

# StoredModelInfo

**Package:** `flyte.prefetch`

Information about a stored model.

## Parameters

```python
class StoredModelInfo(
    artifact_name: str,
    path: str,
    metadata: dict[str, str],
)
```
Create a new model by parsing and validating input data from keyword arguments.

Raises [`ValidationError`](https://docs.pydantic.dev/latest/api/pydantic_core/#pydantic_core.ValidationError) if the input data cannot be
validated to form a valid model.

`self` is explicitly positional-only to allow `self` as a field name.

| Parameter | Type | Description |
|-|-|-|
| `artifact_name` | `str` | Name of the stored artifact. |
| `path` | `str` | Path to the stored model directory. |
| `metadata` | `dict[str, str]` | Metadata about the stored model. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.prefetch/vllmshardargs ===

# VLLMShardArgs

**Package:** `flyte.prefetch`

Arguments for sharding a model using vLLM.

## Parameters

```python
class VLLMShardArgs(
    tensor_parallel_size: int,
    dtype: str,
    trust_remote_code: bool,
    max_model_len: int | None,
    file_pattern: str | None,
    max_file_size: int,
)
```
Create a new model by parsing and validating input data from keyword arguments.

Raises [`ValidationError`](https://docs.pydantic.dev/latest/api/pydantic_core/#pydantic_core.ValidationError) if the input data cannot be
validated to form a valid model.

`self` is explicitly positional-only to allow `self` as a field name.

| Parameter | Type | Description |
|-|-|-|
| `tensor_parallel_size` | `int` | Number of tensor parallel workers. |
| `dtype` | `str` | Data type for model weights. |
| `trust_remote_code` | `bool` | Whether to trust remote code from HuggingFace. |
| `max_model_len` | `int \| None` | Maximum model context length. |
| `file_pattern` | `str \| None` | Pattern for sharded weight files. |
| `max_file_size` | `int` | Maximum size for each sharded file. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.prefetch > VLLMShardArgs > Methods > get_vllm_args()** | Get arguments dict for vLLM LLM constructor. |

### get_vllm_args()

```python
def get_vllm_args(
    model_path: str,
) -> dict[str, Any]
```
Get arguments dict for vLLM LLM constructor.

| Parameter | Type | Description |
|-|-|-|
| `model_path` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.remote ===

# flyte.remote

Remote Entities that are accessible from the Union Server once deployed or created.
## Directory

### Classes

| Class | Description |
|-|-|
| **Flyte SDK > Packages > flyte.remote > Action** | A class representing an action. |
| **Flyte SDK > Packages > flyte.remote > ActionDetails** | A class representing an action. |
| **Flyte SDK > Packages > flyte.remote > ActionInputs** | A class representing the inputs of an action. |
| **Flyte SDK > Packages > flyte.remote > ActionOutputs** | A class representing the outputs of an action. |
| **Flyte SDK > Packages > flyte.remote > App** |  |
| **Flyte SDK > Packages > flyte.remote > Project** | A class representing a project in the Union API. |
| **Flyte SDK > Packages > flyte.remote > Run** | A class representing a run of a task. |
| **Flyte SDK > Packages > flyte.remote > RunDetails** | A class representing a run of a task. |
| **Flyte SDK > Packages > flyte.remote > Secret** |  |
| **Flyte SDK > Packages > flyte.remote > Task** |  |
| **Flyte SDK > Packages > flyte.remote > TaskDetails** |  |
| **Flyte SDK > Packages > flyte.remote > TimeFilter** | Filter for time-based fields (e. |
| **Flyte SDK > Packages > flyte.remote > Trigger** | Represents a trigger in the Flyte platform. |
| **Flyte SDK > Packages > flyte.remote > User** | Represents a user in the Flyte platform. |

### Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.remote > Methods > auth_metadata()** | This context manager allows you to pass contextualized auth metadata downstream to the Flyte authentication system. |
| **Flyte SDK > Packages > flyte.remote > Methods > upload_dir()** | Uploads a directory to a remote location and returns the remote URI. |
| **Flyte SDK > Packages > flyte.remote > Methods > upload_file()** | Uploads a file to a remote location and returns the remote URI. |

## Methods

#### auth_metadata()

```python
def auth_metadata(
    kv: typing.Tuple[str, str],
)
```
This context manager allows you to pass contextualized auth metadata downstream to the Flyte authentication system.

This is only useful if flyte.init_passthrough() has been called.

```python

flyte.init_passthrough("my-endpoint")

...

with auth_metadata((key1, value1), (key2, value2)):
    ...
```

| Parameter | Type | Description |
|-|-|-|
| `kv` | `typing.Tuple[str, str]` | |

#### upload_dir()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await upload_dir.aio()`.
```python
def upload_dir(
    dir_path: pathlib.Path,
    verify: bool,
    prefix: str | None,
) -> str
```
Uploads a directory to a remote location and returns the remote URI.

| Parameter | Type | Description |
|-|-|-|
| `dir_path` | `pathlib.Path` | The directory path to upload. |
| `verify` | `bool` | Whether to verify the certificate for HTTPS requests. |
| `prefix` | `str \| None` | |

**Returns:** The remote URI of the uploaded directory.

#### upload_file()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await upload_file.aio()`.
```python
def upload_file(
    fp: pathlib.Path,
    verify: bool,
    fname: str | None,
) -> typing.Tuple[str, str]
```
Uploads a file to a remote location and returns the remote URI.

| Parameter | Type | Description |
|-|-|-|
| `fp` | `pathlib.Path` | The file path to upload. |
| `verify` | `bool` | Whether to verify the certificate for HTTPS requests. |
| `fname` | `str \| None` | Optional file name for the remote path. |

**Returns:** Tuple of (MD5 digest hex string, remote native URL).

## Subpages
- **Flyte SDK > Packages > flyte.remote > Action**
- **Flyte SDK > Packages > flyte.remote > ActionDetails**
- **Flyte SDK > Packages > flyte.remote > ActionInputs**
- **Flyte SDK > Packages > flyte.remote > ActionOutputs**
- **Flyte SDK > Packages > flyte.remote > App**
- **Flyte SDK > Packages > flyte.remote > Project**
- **Flyte SDK > Packages > flyte.remote > Run**
- **Flyte SDK > Packages > flyte.remote > RunDetails**
- **Flyte SDK > Packages > flyte.remote > Secret**
- **Flyte SDK > Packages > flyte.remote > Task**
- **Flyte SDK > Packages > flyte.remote > TaskDetails**
- **Flyte SDK > Packages > flyte.remote > TimeFilter**
- **Flyte SDK > Packages > flyte.remote > Trigger**
- **Flyte SDK > Packages > flyte.remote > User**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.remote/action ===

# Action

**Package:** `flyte.remote`

A class representing an action. It is used to manage the "execution" of a task and its state on the remote API.

From a datamodel perspective, a Run consists of actions. All actions are linearly nested under a parent action.
 Actions have unique auto-generated identifiers, that are unique within a parent action.

 &lt;pre&gt;
 run
  - a0
    - action1 under a0
    - action2 under a0
        - action1 under action2 under a0
        - action2 under action1 under action2 under a0
        - ...
    - ...
&lt;/pre&gt;

## Parameters

```python
class Action(
    pb2: run_definition_pb2.Action,
    _details: ActionDetails | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `pb2` | `run_definition_pb2.Action` | |
| `_details` | `ActionDetails \| None` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `action_id` | `None` | Get the action ID. |
| `name` | `None` | Get the name of the action. |
| `phase` | `None` | Get the phase of the action. |
| `raw_phase` | `None` | Get the raw phase of the action. |
| `run_name` | `None` | Get the name of the run. |
| `start_time` | `None` | Get the start time of the action. |
| `task_name` | `None` | Get the name of the task. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.remote > Action > Methods > abort()** | Aborts / Terminates the action. |
| **Flyte SDK > Packages > flyte.remote > Action > Methods > details()** | Get the details of the action. |
| **Flyte SDK > Packages > flyte.remote > Action > Methods > done()** | Check if the action is done. |
| **Flyte SDK > Packages > flyte.remote > Action > Methods > get()** | Get a run by its ID or name. |
| **Flyte SDK > Packages > flyte.remote > Action > Methods > get_logs()** | Get logs for the action as an iterator of strings. |
| **Flyte SDK > Packages > flyte.remote > Action > Methods > listall()** | Get all actions for a given run. |
| **Flyte SDK > Packages > flyte.remote > Action > Methods > show_logs()** | Display logs for the action. |
| **Flyte SDK > Packages > flyte.remote > Action > Methods > sync()** | Sync the action with the remote server. |
| **Flyte SDK > Packages > flyte.remote > Action > Methods > to_dict()** | Convert the object to a JSON-serializable dictionary. |
| **Flyte SDK > Packages > flyte.remote > Action > Methods > to_json()** | Convert the object to a JSON string. |
| **Flyte SDK > Packages > flyte.remote > Action > Methods > wait()** | Wait for the run to complete, displaying a rich progress panel with status transitions,. |
| **Flyte SDK > Packages > flyte.remote > Action > Methods > watch()** | Watch the action for updates, updating the internal Action state with latest details. |

### abort()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await <Action instance>.abort.aio()`.
```python
def abort(
    reason: str,
)
```
Aborts / Terminates the action.

| Parameter | Type | Description |
|-|-|-|
| `reason` | `str` | |

### details()

```python
def details()
```
Get the details of the action. This is a placeholder for getting the action details.

### done()

```python
def done()
```
Check if the action is done.

### get()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Action.get.aio()`.
```python
def get(
    cls,
    uri: str | None,
    run_name: str | None,
    name: str | None,
) -> Action
```
Get a run by its ID or name. If both are provided, the ID will take precedence.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `uri` | `str \| None` | The URI of the action. |
| `run_name` | `str \| None` | The name of the action. |
| `name` | `str \| None` | The name of the action. |

### get_logs()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await <Action instance>.get_logs.aio()`.
```python
def get_logs(
    attempt: int | None,
    filter_system: bool,
    show_ts: bool,
) -> AsyncGenerator[str, None]
```
Get logs for the action as an iterator of strings.

Can be called synchronously (returns `Iterator[str]`) or asynchronously
via `.aio()` (returns `AsyncIterator[str]`).

| Parameter | Type | Description |
|-|-|-|
| `attempt` | `int \| None` | The attempt number to retrieve logs for (defaults to latest attempt). |
| `filter_system` | `bool` | If True, filter out system-generated log lines. |
| `show_ts` | `bool` | If True, prefix each line with an ISO-8601 timestamp. |

### listall()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Action.listall.aio()`.
```python
def listall(
    cls,
    for_run_name: str,
    in_phase: Tuple[ActionPhase | str, ...] | None,
    sort_by: Tuple[str, Literal['asc', 'desc']] | None,
    created_at: TimeFilter | None,
    updated_at: TimeFilter | None,
) -> Union[Iterator[Action], AsyncIterator[Action]]
```
Get all actions for a given run.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `for_run_name` | `str` | The name of the run. |
| `in_phase` | `Tuple[ActionPhase \| str, ...] \| None` | Filter actions by one or more phases. |
| `sort_by` | `Tuple[str, Literal['asc', 'desc']] \| None` | The sorting criteria for the project list, in the format (field, order). |
| `created_at` | `TimeFilter \| None` | Filter actions by creation time range. |
| `updated_at` | `TimeFilter \| None` | Filter actions by last-update time range. |

**Returns:** An iterator of actions.

### show_logs()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await <Action instance>.show_logs.aio()`.
```python
def show_logs(
    attempt: int | None,
    max_lines: int,
    show_ts: bool,
    raw: bool,
    filter_system: bool,
)
```
Display logs for the action.

| Parameter | Type | Description |
|-|-|-|
| `attempt` | `int \| None` | The attempt number to show logs for (defaults to latest attempt). |
| `max_lines` | `int` | Maximum number of log lines to display in the viewer. |
| `show_ts` | `bool` | Whether to show timestamps with each log line. |
| `raw` | `bool` | If True, print logs directly without the interactive viewer. |
| `filter_system` | `bool` | If True, filter out system-generated log lines. |

### sync()

```python
def sync()
```
Sync the action with the remote server. This is a placeholder for syncing the action.

### to_dict()

```python
def to_dict()
```
Convert the object to a JSON-serializable dictionary.

**Returns:** dict: A dictionary representation of the object.

### to_json()

```python
def to_json()
```
Convert the object to a JSON string.

**Returns:** str: A JSON string representation of the object.

### wait()

```python
def wait(
    quiet: bool,
    wait_for: WaitFor,
)
```
Wait for the run to complete, displaying a rich progress panel with status transitions,
time elapsed, and error details in case of failure.

| Parameter | Type | Description |
|-|-|-|
| `quiet` | `bool` | |
| `wait_for` | `WaitFor` | |

### watch()

```python
def watch(
    cache_data_on_done: bool,
    wait_for: WaitFor,
) -> AsyncGenerator[ActionDetails, None]
```
Watch the action for updates, updating the internal Action state with latest details.

This method updates both the cached details and the protobuf representation,
ensuring that properties like `phase` reflect the current state.

| Parameter | Type | Description |
|-|-|-|
| `cache_data_on_done` | `bool` | |
| `wait_for` | `WaitFor` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.remote/actiondetails ===

# ActionDetails

**Package:** `flyte.remote`

A class representing an action. It is used to manage the run of a task and its state on the remote Union API.

## Parameters

```python
class ActionDetails(
    pb2: run_definition_pb2.ActionDetails,
    _inputs: ActionInputs | None,
    _outputs: ActionOutputs | None,
    _preserve_original_types: bool,
)
```
| Parameter | Type | Description |
|-|-|-|
| `pb2` | `run_definition_pb2.ActionDetails` | |
| `_inputs` | `ActionInputs \| None` | |
| `_outputs` | `ActionOutputs \| None` | |
| `_preserve_original_types` | `bool` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `abort_info` | `None` | Get the abort information if the action was aborted, otherwise returns None. |
| `action_id` | `None` | Get the action ID. |
| `attempts` | `None` | Get the number of attempts of the action. |
| `error_info` | `None` | Get the error information if the action failed, otherwise returns None. |
| `initializing_time` | `None` | Get the time spent in the INITIALIZING phase for the latest attempt. |
| `is_running` | `None` | Check if the action is currently running. |
| `metadata` | `None` | Get the metadata of the action. |
| `name` | `None` | Get the name of the action. |
| `phase` | `None` | Get the phase of the action. |
| `phase_durations` | `None` | Get the duration spent in each phase as a dictionary.  Returns a mapping of ActionPhase to timedelta for the latest attempt. This provides an easy way to see how long was spent queued, initializing, running, etc. |
| `queued_time` | `None` | Get the time spent in the QUEUED phase for the latest attempt. |
| `raw_phase` | `None` | Get the raw phase of the action. |
| `run_name` | `None` | Get the name of the run. |
| `running_time` | `None` | Get the time spent in the RUNNING phase for the latest attempt. |
| `runtime` | `None` | Get the runtime of the action. |
| `status` | `None` | Get the status of the action. |
| `task_name` | `None` | Get the name of the task. |
| `waiting_for_resources_time` | `None` | Get the time spent in the WAITING_FOR_RESOURCES phase for the latest attempt. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.remote > ActionDetails > Methods > done()** | Check if the action is in a terminal state (completed or failed). |
| **Flyte SDK > Packages > flyte.remote > ActionDetails > Methods > get()** | Get a run by its ID or name. |
| **Flyte SDK > Packages > flyte.remote > ActionDetails > Methods > get_details()** | Get the details of the action. |
| **Flyte SDK > Packages > flyte.remote > ActionDetails > Methods > get_phase_transitions()** | Get the phase transitions for a specific attempt, showing the granular breakdown. |
| **Flyte SDK > Packages > flyte.remote > ActionDetails > Methods > inputs()** | Return the inputs of the action. |
| **Flyte SDK > Packages > flyte.remote > ActionDetails > Methods > logs_available()** | Check if logs are available for the action, optionally for a specific attempt. |
| **Flyte SDK > Packages > flyte.remote > ActionDetails > Methods > outputs()** | Returns the outputs of the action, returns instantly if outputs are already cached, else fetches them and. |
| **Flyte SDK > Packages > flyte.remote > ActionDetails > Methods > to_dict()** | Convert the object to a JSON-serializable dictionary. |
| **Flyte SDK > Packages > flyte.remote > ActionDetails > Methods > to_json()** | Convert the object to a JSON string. |
| **Flyte SDK > Packages > flyte.remote > ActionDetails > Methods > watch()** | Watch the action for updates. |
| **Flyte SDK > Packages > flyte.remote > ActionDetails > Methods > watch_updates()** | Watch for updates to the action details, yielding each update until the action is done. |

### done()

```python
def done()
```
Check if the action is in a terminal state (completed or failed). This is a placeholder for checking the
action state.

### get()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await ActionDetails.get.aio()`.
```python
def get(
    cls,
    uri: str | None,
    run_name: str | None,
    name: str | None,
) -> ActionDetails
```
Get a run by its ID or name. If both are provided, the ID will take precedence.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `uri` | `str \| None` | The URI of the action. |
| `run_name` | `str \| None` | The name of the run. |
| `name` | `str \| None` | The name of the action. |

### get_details()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await ActionDetails.get_details.aio()`.
```python
def get_details(
    cls,
    action_id: identifier_pb2.ActionIdentifier,
) -> ActionDetails
```
Get the details of the action. This is a placeholder for getting the action details.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `action_id` | `identifier_pb2.ActionIdentifier` | |

### get_phase_transitions()

```python
def get_phase_transitions(
    attempt: int | None,
) -> List[PhaseTransitionInfo]
```
Get the phase transitions for a specific attempt, showing the granular breakdown
of time spent in each phase (queued, initializing, running, etc.).

| Parameter | Type | Description |
|-|-|-|
| `attempt` | `int \| None` | The attempt number (1-indexed). If None, uses the latest attempt. |

**Returns**

List of PhaseTransitionInfo objects, one for each phase the action went through.

### inputs()

```python
def inputs()
```
Return the inputs of the action.
Will return instantly if inputs are available else will fetch and return.

### logs_available()

```python
def logs_available(
    attempt: int | None,
) -> bool
```
Check if logs are available for the action, optionally for a specific attempt.
If attempt is None, it checks for the latest attempt.

| Parameter | Type | Description |
|-|-|-|
| `attempt` | `int \| None` | |

### outputs()

```python
def outputs()
```
Returns the outputs of the action, returns instantly if outputs are already cached, else fetches them and
returns. If Action is not in a terminal state, raise a RuntimeError.

**Returns:** ActionOutputs

### to_dict()

```python
def to_dict()
```
Convert the object to a JSON-serializable dictionary.

**Returns:** dict: A dictionary representation of the object.

### to_json()

```python
def to_json()
```
Convert the object to a JSON string.

**Returns:** str: A JSON string representation of the object.

### watch()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await ActionDetails.watch.aio()`.
```python
def watch(
    cls,
    action_id: identifier_pb2.ActionIdentifier,
) -> AsyncIterator[ActionDetails]
```
Watch the action for updates. This is a placeholder for watching the action.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `action_id` | `identifier_pb2.ActionIdentifier` | |

### watch_updates()

```python
def watch_updates(
    cache_data_on_done: bool,
) -> AsyncGenerator[ActionDetails, None]
```
Watch for updates to the action details, yielding each update until the action is done.

| Parameter | Type | Description |
|-|-|-|
| `cache_data_on_done` | `bool` | If True, cache inputs and outputs when the action completes. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.remote/actioninputs ===

# ActionInputs

**Package:** `flyte.remote`

A class representing the inputs of an action. It is used to manage the inputs of a task and its state on the
remote Union API.

ActionInputs extends from a `UserDict` and hence is accessible like a dictionary

Example Usage:
```python
action = Action.get(...)
print(action.inputs())
```
Output:
```bash
{
  "x": ...,
  "y": ...,
}
```

## Parameters

```python
class ActionInputs(
    pb2: common_pb2.Inputs,
    data: Dict[str, Any],
)
```
| Parameter | Type | Description |
|-|-|-|
| `pb2` | `common_pb2.Inputs` | |
| `data` | `Dict[str, Any]` | |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.remote > ActionInputs > Methods > clear()** | D. |
| **Flyte SDK > Packages > flyte.remote > ActionInputs > Methods > copy()** |  |
| **Flyte SDK > Packages > flyte.remote > ActionInputs > Methods > fromkeys()** |  |
| **Flyte SDK > Packages > flyte.remote > ActionInputs > Methods > get()** | D. |
| **Flyte SDK > Packages > flyte.remote > ActionInputs > Methods > items()** | D. |
| **Flyte SDK > Packages > flyte.remote > ActionInputs > Methods > keys()** | D. |
| **Flyte SDK > Packages > flyte.remote > ActionInputs > Methods > pop()** | D. |
| **Flyte SDK > Packages > flyte.remote > ActionInputs > Methods > popitem()** | D. |
| **Flyte SDK > Packages > flyte.remote > ActionInputs > Methods > setdefault()** | D. |
| **Flyte SDK > Packages > flyte.remote > ActionInputs > Methods > to_dict()** | Convert the object to a JSON-serializable dictionary. |
| **Flyte SDK > Packages > flyte.remote > ActionInputs > Methods > to_json()** | Convert the object to a JSON string. |
| **Flyte SDK > Packages > flyte.remote > ActionInputs > Methods > update()** | D. |
| **Flyte SDK > Packages > flyte.remote > ActionInputs > Methods > values()** | D. |

### clear()

```python
def clear()
```
D.clear() -&gt; None.  Remove all items from D.

### copy()

```python
def copy()
```
### fromkeys()

```python
def fromkeys(
    iterable,
    value,
)
```
| Parameter | Type | Description |
|-|-|-|
| `iterable` |  | |
| `value` |  | |

### get()

```python
def get(
    key,
    default,
)
```
D.get(k[,d]) -&gt; D[k] if k in D, else d.  d defaults to None.

| Parameter | Type | Description |
|-|-|-|
| `key` |  | |
| `default` |  | |

### items()

```python
def items()
```
D.items() -&gt; a set-like object providing a view on D's items

### keys()

```python
def keys()
```
D.keys() -&gt; a set-like object providing a view on D's keys

### pop()

```python
def pop(
    key,
    default,
)
```
D.pop(k[,d]) -&gt; v, remove specified key and return the corresponding value.
If key is not found, d is returned if given, otherwise KeyError is raised.

| Parameter | Type | Description |
|-|-|-|
| `key` |  | |
| `default` |  | |

### popitem()

```python
def popitem()
```
D.popitem() -&gt; (k, v), remove and return some (key, value) pair
as a 2-tuple; but raise KeyError if D is empty.

### setdefault()

```python
def setdefault(
    key,
    default,
)
```
D.setdefault(k[,d]) -&gt; D.get(k,d), also set D[k]=d if k not in D

| Parameter | Type | Description |
|-|-|-|
| `key` |  | |
| `default` |  | |

### to_dict()

```python
def to_dict()
```
Convert the object to a JSON-serializable dictionary.

**Returns:** dict: A dictionary representation of the object.

### to_json()

```python
def to_json()
```
Convert the object to a JSON string.

**Returns:** str: A JSON string representation of the object.

### update()

```python
def update(
    other,
    kwds,
)
```
D.update([E, ]**F) -&gt; None.  Update D from mapping/iterable E and F.
If E present and has a .keys() method, does:     for k in E: D[k] = E[k]
If E present and lacks .keys() method, does:     for (k, v) in E: D[k] = v
In either case, this is followed by: for k, v in F.items(): D[k] = v

| Parameter | Type | Description |
|-|-|-|
| `other` |  | |
| `kwds` |  | |

### values()

```python
def values()
```
D.values() -&gt; an object providing a view on D's values


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.remote/actionoutputs ===

# ActionOutputs

**Package:** `flyte.remote`

A class representing the outputs of an action. The outputs are by default represented as a Tuple. To access them,
you can simply read them as a tuple (assign to individual variables, use index to access) or you can use the
property `named_outputs` to retrieve a dictionary of outputs with keys that represent output names
which are usually auto-generated `o0, o1, o2, o3, ...`.

Example Usage:
```python
action = Action.get(...)
print(action.outputs())
```
Output:
```python
("val1", "val2", ...)
```
OR
```python
action = Action.get(...)
print(action.outputs().named_outputs)
```
Output:
```bash
{"o0": "val1", "o1": "val2", ...}
```

## Parameters

```python
class ActionOutputs(
    pb2: common_pb2.Outputs,
    data: Tuple[Any, ...],
    fields: List[str] | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `pb2` | `common_pb2.Outputs` | |
| `data` | `Tuple[Any, ...]` | |
| `fields` | `List[str] \| None` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `named_outputs` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.remote > ActionOutputs > Methods > to_dict()** | Convert the object to a JSON-serializable dictionary. |
| **Flyte SDK > Packages > flyte.remote > ActionOutputs > Methods > to_json()** | Convert the object to a JSON string. |

### to_dict()

```python
def to_dict()
```
Convert the object to a JSON-serializable dictionary.

**Returns:** dict: A dictionary representation of the object.

### to_json()

```python
def to_json()
```
Convert the object to a JSON string.

**Returns:** str: A JSON string representation of the object.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.remote/app ===

# App

**Package:** `flyte.remote`

## Parameters

```python
class App(
    pb2: app_definition_pb2.App,
)
```
| Parameter | Type | Description |
|-|-|-|
| `pb2` | `app_definition_pb2.App` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `deployment_status` | `None` | Get the deployment status of the app |
| `desired_state` | `None` | Get the desired state of the app. |
| `endpoint` | `None` | Get the public endpoint URL of the app. |
| `name` | `None` | Get the name of the app. |
| `revision` | `None` | Get the revision number of the app. |
| `url` | `None` | Get the console URL for viewing the app. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.remote > App > Methods > activate()** | Start the app. |
| **Flyte SDK > Packages > flyte.remote > App > Methods > create()** |  |
| **Flyte SDK > Packages > flyte.remote > App > Methods > deactivate()** | Stop the app. |
| **Flyte SDK > Packages > flyte.remote > App > Methods > delete()** | Delete an app by name. |
| **Flyte SDK > Packages > flyte.remote > App > Methods > ephemeral_ctx()** | Async context manager that activates the app and deactivates it when the context is exited. |
| **Flyte SDK > Packages > flyte.remote > App > Methods > ephemeral_ctx_sync()** | Context manager that activates the app and deactivates it when the context is exited. |
| **Flyte SDK > Packages > flyte.remote > App > Methods > get()** | Get an app by name. |
| **Flyte SDK > Packages > flyte.remote > App > Methods > is_active()** | Check if the app is currently active or started. |
| **Flyte SDK > Packages > flyte.remote > App > Methods > is_deactivated()** | Check if the app is currently deactivated or stopped. |
| **Flyte SDK > Packages > flyte.remote > App > Methods > listall()** |  |
| **Flyte SDK > Packages > flyte.remote > App > Methods > replace()** | Replace an existing app's that matches the given name, with a new spec and optionally labels. |
| **Flyte SDK > Packages > flyte.remote > App > Methods > to_dict()** | Convert the object to a JSON-serializable dictionary. |
| **Flyte SDK > Packages > flyte.remote > App > Methods > to_json()** | Convert the object to a JSON string. |
| **Flyte SDK > Packages > flyte.remote > App > Methods > update()** |  |
| **Flyte SDK > Packages > flyte.remote > App > Methods > watch()** | Watch for the app to reach activated or deactivated state. |

### activate()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await <App instance>.activate.aio()`.
```python
def activate(
    wait: bool,
) -> App
```
Start the app

| Parameter | Type | Description |
|-|-|-|
| `wait` | `bool` | Wait for the app to reach activated state |

### create()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await App.create.aio()`.
```python
def create(
    cls,
    app: app_definition_pb2.App,
) -> App
```
| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `app` | `app_definition_pb2.App` | |

### deactivate()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await <App instance>.deactivate.aio()`.
```python
def deactivate(
    wait: bool,
) -> App
```
Stop the app

| Parameter | Type | Description |
|-|-|-|
| `wait` | `bool` | Wait for the app to reach the deactivated state |

### delete()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await App.delete.aio()`.
```python
def delete(
    cls,
    name: str,
    project: str | None,
    domain: str | None,
)
```
Delete an app by name.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | The name of the app to delete. |
| `project` | `str \| None` | The name of the project to delete. |
| `domain` | `str \| None` | The name of the domain to delete. |

### ephemeral_ctx()

```python
def ephemeral_ctx()
```
Async context manager that activates the app and deactivates it when the context is exited.

### ephemeral_ctx_sync()

```python
def ephemeral_ctx_sync()
```
Context manager that activates the app and deactivates it when the context is exited.

### get()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await App.get.aio()`.
```python
def get(
    cls,
    name: str,
    project: str | None,
    domain: str | None,
) -> App
```
Get an app by name.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | The name of the app. |
| `project` | `str \| None` | The project of the app. |
| `domain` | `str \| None` | The domain of the app. |

**Returns:** The app remote object.

### is_active()

```python
def is_active()
```
Check if the app is currently active or started.

### is_deactivated()

```python
def is_deactivated()
```
Check if the app is currently deactivated or stopped.

### listall()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await App.listall.aio()`.
```python
def listall(
    cls,
    created_by_subject: str | None,
    sort_by: Tuple[str, Literal['asc', 'desc']] | None,
    limit: int,
) -> AsyncIterator[App]
```
| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `created_by_subject` | `str \| None` | |
| `sort_by` | `Tuple[str, Literal['asc', 'desc']] \| None` | |
| `limit` | `int` | |

### replace()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await App.replace.aio()`.
```python
def replace(
    cls,
    name: str,
    updated_app_spec: app_definition_pb2.Spec,
    reason: str,
    labels: Mapping[str, str] | None,
    project: str | None,
    domain: str | None,
) -> App
```
Replace an existing app's that matches the given name, with a new spec and optionally labels.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | Name of the new app |
| `updated_app_spec` | `app_definition_pb2.Spec` | Updated app spec |
| `reason` | `str` | |
| `labels` | `Mapping[str, str] \| None` | Optional labels for the new app |
| `project` | `str \| None` | Optional project for the new app |
| `domain` | `str \| None` | Optional domain for the new app |

**Returns:** A new app

### to_dict()

```python
def to_dict()
```
Convert the object to a JSON-serializable dictionary.

**Returns:** dict: A dictionary representation of the object.

### to_json()

```python
def to_json()
```
Convert the object to a JSON string.

**Returns:** str: A JSON string representation of the object.

### update()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await App.update.aio()`.
```python
def update(
    cls,
    updated_app_proto: app_definition_pb2.App,
    reason: str,
) -> App
```
| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `updated_app_proto` | `app_definition_pb2.App` | |
| `reason` | `str` | |

### watch()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await <App instance>.watch.aio()`.
```python
def watch(
    wait_for: WaitFor,
) -> App
```
Watch for the app to reach activated or deactivated state.

| Parameter | Type | Description |
|-|-|-|
| `wait_for` | `WaitFor` | ["activated", "deactivated"]  Returns: The app in the desired state. Raises: RuntimeError if the app did not reach desired state and failed! |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.remote/project ===

# Project

**Package:** `flyte.remote`

A class representing a project in the Union API.

## Parameters

```python
class Project(
    pb2: project_service_pb2.Project,
)
```
| Parameter | Type | Description |
|-|-|-|
| `pb2` | `project_service_pb2.Project` | |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.remote > Project > Methods > archive()** | Archive this project. |
| **Flyte SDK > Packages > flyte.remote > Project > Methods > create()** | Create a new project. |
| **Flyte SDK > Packages > flyte.remote > Project > Methods > get()** | Get a project by name. |
| **Flyte SDK > Packages > flyte.remote > Project > Methods > listall()** | List all projects. |
| **Flyte SDK > Packages > flyte.remote > Project > Methods > to_dict()** | Convert the object to a JSON-serializable dictionary. |
| **Flyte SDK > Packages > flyte.remote > Project > Methods > to_json()** | Convert the object to a JSON string. |
| **Flyte SDK > Packages > flyte.remote > Project > Methods > unarchive()** | Unarchive (activate) this project. |
| **Flyte SDK > Packages > flyte.remote > Project > Methods > update()** | Update an existing project. |

### archive()

```python
def archive()
```
Archive this project.

### create()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Project.create.aio()`.
```python
def create(
    cls,
    id: str,
    name: str,
    description: str,
    labels: Dict[str, str] | None,
) -> Project
```
Create a new project.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `id` | `str` | The unique identifier for the project. |
| `name` | `str` | The display name for the project. |
| `description` | `str` | A description for the project. |
| `labels` | `Dict[str, str] \| None` | Optional key-value labels for the project. |

### get()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Project.get.aio()`.
```python
def get(
    cls,
    name: str,
) -> Project
```
Get a project by name.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | The name of the project. |

### listall()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Project.listall.aio()`.
```python
def listall(
    cls,
    filters: str | None,
    sort_by: Tuple[str, Literal['asc', 'desc']] | None,
    archived: bool,
) -> Union[AsyncIterator[Project], Iterator[Project]]
```
List all projects.

By default, lists active (unarchived) projects. Set `archived=True` to list
archived projects instead.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `filters` | `str \| None` | The filters to apply to the project list. |
| `sort_by` | `Tuple[str, Literal['asc', 'desc']] \| None` | The sorting criteria for the project list, in the format (field, order). |
| `archived` | `bool` | If True, list archived projects. If False (default), list active projects. |

**Returns:** An iterator of projects.

### to_dict()

```python
def to_dict()
```
Convert the object to a JSON-serializable dictionary.

**Returns:** dict: A dictionary representation of the object.

### to_json()

```python
def to_json()
```
Convert the object to a JSON string.

**Returns:** str: A JSON string representation of the object.

### unarchive()

```python
def unarchive()
```
Unarchive (activate) this project.

### update()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Project.update.aio()`.
```python
def update(
    cls,
    id: str,
    name: str | None,
    description: str | None,
    labels: Dict[str, str] | None,
    state: Literal['archived', 'active'] | None,
) -> Project
```
Update an existing project.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `id` | `str` | The id of the project to update. |
| `name` | `str \| None` | New display name. If None, the existing name is preserved. |
| `description` | `str \| None` | New description. If None, the existing description is preserved. |
| `labels` | `Dict[str, str] \| None` | New labels. If None, the existing labels are preserved. |
| `state` | `Literal['archived', 'active'] \| None` | "archived" or "active". If None, the existing state is preserved. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.remote/run ===

# Run

**Package:** `flyte.remote`

A class representing a run of a task. It is used to manage the run of a task and its state on the remote
Union API.

## Parameters

```python
class Run(
    pb2: run_definition_pb2.Run,
    _details: RunDetails | None,
    _preserve_original_types: bool,
)
```
| Parameter | Type | Description |
|-|-|-|
| `pb2` | `run_definition_pb2.Run` | |
| `_details` | `RunDetails \| None` | |
| `_preserve_original_types` | `bool` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `name` | `None` | Get the name of the run. |
| `phase` | `None` | Get the phase of the run. |
| `raw_phase` | `None` | Get the raw phase of the run. |
| `url` | `None` | Get the URL of the run. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.remote > Run > Methods > abort()** | Aborts / Terminates the run. |
| **Flyte SDK > Packages > flyte.remote > Run > Methods > details()** | Get the details of the run. |
| **Flyte SDK > Packages > flyte.remote > Run > Methods > done()** | Check if the run is done. |
| **Flyte SDK > Packages > flyte.remote > Run > Methods > get()** | Get the current run. |
| **Flyte SDK > Packages > flyte.remote > Run > Methods > get_debug_url()** | Get the debug URL of the run. |
| **Flyte SDK > Packages > flyte.remote > Run > Methods > get_logs()** | Get logs for the run as an iterator of strings. |
| **Flyte SDK > Packages > flyte.remote > Run > Methods > inputs()** | Get the inputs of the run. |
| **Flyte SDK > Packages > flyte.remote > Run > Methods > listall()** | Get all runs for the current project and domain. |
| **Flyte SDK > Packages > flyte.remote > Run > Methods > outputs()** | Get the outputs of the run. |
| **Flyte SDK > Packages > flyte.remote > Run > Methods > show_logs()** |  |
| **Flyte SDK > Packages > flyte.remote > Run > Methods > sync()** | Sync the run with the remote server. |
| **Flyte SDK > Packages > flyte.remote > Run > Methods > to_dict()** | Convert the object to a JSON-serializable dictionary. |
| **Flyte SDK > Packages > flyte.remote > Run > Methods > to_json()** | Convert the object to a JSON string. |
| **Flyte SDK > Packages > flyte.remote > Run > Methods > wait()** | Wait for the run to complete, displaying a rich progress panel with status transitions,. |
| **Flyte SDK > Packages > flyte.remote > Run > Methods > watch()** | Watch the run for updates, updating the internal Run state with latest details. |

### abort()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await <Run instance>.abort.aio()`.
```python
def abort(
    reason: str,
)
```
Aborts / Terminates the run.

| Parameter | Type | Description |
|-|-|-|
| `reason` | `str` | |

### details()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await <Run instance>.details.aio()`.
```python
def details()
```
Get the details of the run. This is a placeholder for getting the run details.

### done()

```python
def done()
```
Check if the run is done.

### get()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Run.get.aio()`.
```python
def get(
    cls,
    name: str,
) -> Run
```
Get the current run.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | |

**Returns:** The current run.

### get_debug_url()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await <Run instance>.get_debug_url.aio()`.
```python
def get_debug_url()
```
Get the debug URL of the run. Returns `None` if the VS Code
Debugger log entry is not yet available in the action details.

### get_logs()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await <Run instance>.get_logs.aio()`.
```python
def get_logs(
    attempt: int | None,
    filter_system: bool,
    show_ts: bool,
) -> AsyncGenerator[str, None]
```
Get logs for the run as an iterator of strings.

Can be called synchronously (returns `Iterator[str]`) or asynchronously
via `.aio()` (returns `AsyncIterator[str]`).

| Parameter | Type | Description |
|-|-|-|
| `attempt` | `int \| None` | The attempt number to retrieve logs for (defaults to latest attempt). |
| `filter_system` | `bool` | If True, filter out system-generated log lines. |
| `show_ts` | `bool` | If True, prefix each line with an ISO-8601 timestamp. |

### inputs()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await <Run instance>.inputs.aio()`.
```python
def inputs()
```
Get the inputs of the run. This is a placeholder for getting the run inputs.

### listall()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Run.listall.aio()`.
```python
def listall(
    cls,
    in_phase: Tuple[ActionPhase | str, ...] | None,
    task_name: str | None,
    task_version: str | None,
    created_by_subject: str | None,
    sort_by: Tuple[str, Literal['asc', 'desc']] | None,
    limit: int,
    project: str | None,
    domain: str | None,
    created_at: TimeFilter | None,
    updated_at: TimeFilter | None,
) -> AsyncIterator[Run]
```
Get all runs for the current project and domain.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `in_phase` | `Tuple[ActionPhase \| str, ...] \| None` | Filter runs by one or more phases. |
| `task_name` | `str \| None` | Filter runs by task name. |
| `task_version` | `str \| None` | Filter runs by task version. |
| `created_by_subject` | `str \| None` | Filter runs by the subject that created them. (this is not username, but the subject) |
| `sort_by` | `Tuple[str, Literal['asc', 'desc']] \| None` | The sorting criteria for the Run list, in the format (field, order). |
| `limit` | `int` | The maximum number of runs to return. |
| `project` | `str \| None` | The project to list runs for. Defaults to the globally configured project. |
| `domain` | `str \| None` | The domain to list runs for. Defaults to the globally configured domain. |
| `created_at` | `TimeFilter \| None` | Filter runs by creation time range. |
| `updated_at` | `TimeFilter \| None` | Filter runs by last-update time range. |

**Returns:** An iterator of runs.

### outputs()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await <Run instance>.outputs.aio()`.
```python
def outputs()
```
Get the outputs of the run. This is a placeholder for getting the run outputs.

### show_logs()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await <Run instance>.show_logs.aio()`.
```python
def show_logs(
    attempt: int | None,
    max_lines: int,
    show_ts: bool,
    raw: bool,
    filter_system: bool,
)
```
| Parameter | Type | Description |
|-|-|-|
| `attempt` | `int \| None` | |
| `max_lines` | `int` | |
| `show_ts` | `bool` | |
| `raw` | `bool` | |
| `filter_system` | `bool` | |

### sync()

```python
def sync()
```
Sync the run with the remote server. This is a placeholder for syncing the run.

### to_dict()

```python
def to_dict()
```
Convert the object to a JSON-serializable dictionary.

**Returns:** dict: A dictionary representation of the object.

### to_json()

```python
def to_json()
```
Convert the object to a JSON string.

**Returns:** str: A JSON string representation of the object.

### wait()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await <Run instance>.wait.aio()`.
```python
def wait(
    quiet: bool,
    wait_for: Literal['terminal', 'running'],
)
```
Wait for the run to complete, displaying a rich progress panel with status transitions,
time elapsed, and error details in case of failure.

This method updates the Run's internal state, ensuring that properties like
`run.action.phase` reflect the final state after waiting completes.

| Parameter | Type | Description |
|-|-|-|
| `quiet` | `bool` | |
| `wait_for` | `Literal['terminal', 'running']` | |

### watch()

```python
def watch(
    cache_data_on_done: bool,
) -> AsyncGenerator[ActionDetails, None]
```
Watch the run for updates, updating the internal Run state with latest details.

This method updates the Run's action state, ensuring that properties like
`run.action.phase` reflect the current state after watching.

| Parameter | Type | Description |
|-|-|-|
| `cache_data_on_done` | `bool` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.remote/rundetails ===

# RunDetails

**Package:** `flyte.remote`

A class representing a run of a task. It is used to manage the run of a task and its state on the remote
Union API.

## Parameters

```python
class RunDetails(
    pb2: run_definition_pb2.RunDetails,
    _preserve_original_types: bool,
)
```
| Parameter | Type | Description |
|-|-|-|
| `pb2` | `run_definition_pb2.RunDetails` | |
| `_preserve_original_types` | `bool` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `action_id` | `None` | Get the action ID. |
| `name` | `None` | Get the name of the action. |
| `task_name` | `None` | Get the name of the task. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.remote > RunDetails > Methods > done()** | Check if the run is in a terminal state (completed or failed). |
| **Flyte SDK > Packages > flyte.remote > RunDetails > Methods > get()** | Get a run by its ID or name. |
| **Flyte SDK > Packages > flyte.remote > RunDetails > Methods > get_details()** | Get the details of the run. |
| **Flyte SDK > Packages > flyte.remote > RunDetails > Methods > inputs()** | Placeholder for inputs. |
| **Flyte SDK > Packages > flyte.remote > RunDetails > Methods > outputs()** | Placeholder for outputs. |
| **Flyte SDK > Packages > flyte.remote > RunDetails > Methods > to_dict()** | Convert the object to a JSON-serializable dictionary. |
| **Flyte SDK > Packages > flyte.remote > RunDetails > Methods > to_json()** | Convert the object to a JSON string. |

### done()

```python
def done()
```
Check if the run is in a terminal state (completed or failed). This is a placeholder for checking the
run state.

### get()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await RunDetails.get.aio()`.
```python
def get(
    cls,
    name: str | None,
) -> RunDetails
```
Get a run by its ID or name. If both are provided, the ID will take precedence.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str \| None` | The name of the run. |

### get_details()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await RunDetails.get_details.aio()`.
```python
def get_details(
    cls,
    run_id: identifier_pb2.RunIdentifier,
) -> RunDetails
```
Get the details of the run. This is a placeholder for getting the run details.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `run_id` | `identifier_pb2.RunIdentifier` | |

### inputs()

```python
def inputs()
```
Placeholder for inputs. This can be extended to handle inputs from the run context.

### outputs()

```python
def outputs()
```
Placeholder for outputs. This can be extended to handle outputs from the run context.

### to_dict()

```python
def to_dict()
```
Convert the object to a JSON-serializable dictionary.

**Returns:** dict: A dictionary representation of the object.

### to_json()

```python
def to_json()
```
Convert the object to a JSON string.

**Returns:** str: A JSON string representation of the object.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.remote/secret ===

# Secret

**Package:** `flyte.remote`

## Parameters

```python
class Secret(
    pb2: definition_pb2.Secret,
)
```
| Parameter | Type | Description |
|-|-|-|
| `pb2` | `definition_pb2.Secret` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `name` | `None` | Get the name of the secret. |
| `type` | `None` | Get the type of the secret as a string ("regular" or "image_pull"). |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.remote > Secret > Methods > create()** | Create a new secret. |
| **Flyte SDK > Packages > flyte.remote > Secret > Methods > delete()** | Delete a secret by name. |
| **Flyte SDK > Packages > flyte.remote > Secret > Methods > get()** | Retrieve a secret by name. |
| **Flyte SDK > Packages > flyte.remote > Secret > Methods > listall()** | List all secrets in the current project and domain. |
| **Flyte SDK > Packages > flyte.remote > Secret > Methods > to_dict()** | Convert the object to a JSON-serializable dictionary. |
| **Flyte SDK > Packages > flyte.remote > Secret > Methods > to_json()** | Convert the object to a JSON string. |

### create()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Secret.create.aio()`.
```python
def create(
    cls,
    name: str,
    value: Union[str, bytes],
    type: SecretTypes,
)
```
Create a new secret.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | The name of the secret. |
| `value` | `Union[str, bytes]` | The secret value as a string or bytes. |
| `type` | `SecretTypes` | Type of secret - either "regular" or "image_pull". |

### delete()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Secret.delete.aio()`.
```python
def delete(
    cls,
    name,
)
```
Delete a secret by name.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` |  | The name of the secret to delete. |

### get()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Secret.get.aio()`.
```python
def get(
    cls,
    name: str,
) -> Secret
```
Retrieve a secret by name.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | The name of the secret to retrieve. |

**Returns:** A Secret object.

### listall()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Secret.listall.aio()`.
```python
def listall(
    cls,
    limit: int,
) -> AsyncIterator[Secret]
```
List all secrets in the current project and domain.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `limit` | `int` | Maximum number of secrets to return per page. |

**Returns:** An async iterator of Secret objects.

### to_dict()

```python
def to_dict()
```
Convert the object to a JSON-serializable dictionary.

**Returns:** dict: A dictionary representation of the object.

### to_json()

```python
def to_json()
```
Convert the object to a JSON string.

**Returns:** str: A JSON string representation of the object.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.remote/task ===

# Task

**Package:** `flyte.remote`

## Parameters

```python
class Task(
    pb2: task_definition_pb2.Task,
)
```
Initialize a Task object.

| Parameter | Type | Description |
|-|-|-|
| `pb2` | `task_definition_pb2.Task` | The task protobuf definition. |

## Properties

| Property | Type | Description |
|-|-|-|
| `name` | `None` | The name of the task. |
| `url` | `None` | Get the console URL for viewing the task. |
| `version` | `None` | The version of the task. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.remote > Task > Methods > get()** | Get a task by its ID or name. |
| **Flyte SDK > Packages > flyte.remote > Task > Methods > listall()** | Get all runs for the current project and domain. |
| **Flyte SDK > Packages > flyte.remote > Task > Methods > to_dict()** | Convert the object to a JSON-serializable dictionary. |
| **Flyte SDK > Packages > flyte.remote > Task > Methods > to_json()** | Convert the object to a JSON string. |

### get()

```python
def get(
    name: str,
    project: str | None,
    domain: str | None,
    version: str | None,
    auto_version: AutoVersioning | None,
) -> LazyEntity
```
Get a task by its ID or name. If both are provided, the ID will take precedence.

Either version or auto_version are required parameters.

| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | The name of the task. |
| `project` | `str \| None` | The project of the task. |
| `domain` | `str \| None` | The domain of the task. |
| `version` | `str \| None` | The version of the task. |
| `auto_version` | `AutoVersioning \| None` | If set to "latest", the latest-by-time ordered from now, version of the task will be used. If set to "current", the version will be derived from the callee tasks context. This is useful if you are deploying all environments with the same version. If auto_version is current, you can only access the task from within a task context. |

### listall()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Task.listall.aio()`.
```python
def listall(
    cls,
    by_task_name: str | None,
    by_task_env: str | None,
    project: str | None,
    domain: str | None,
    sort_by: Tuple[str, Literal['asc', 'desc']] | None,
    limit: int,
) -> Union[AsyncIterator[Task], Iterator[Task]]
```
Get all runs for the current project and domain.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `by_task_name` | `str \| None` | If provided, only tasks with this name will be returned. |
| `by_task_env` | `str \| None` | If provided, only tasks with this environment prefix will be returned. |
| `project` | `str \| None` | The project to filter tasks by. If None, the current project will be used. |
| `domain` | `str \| None` | The domain to filter tasks by. If None, the current domain will be used. |
| `sort_by` | `Tuple[str, Literal['asc', 'desc']] \| None` | The sorting criteria for the project list, in the format (field, order). |
| `limit` | `int` | The maximum number of tasks to return. |

**Returns:** An iterator of runs.

### to_dict()

```python
def to_dict()
```
Convert the object to a JSON-serializable dictionary.

**Returns:** dict: A dictionary representation of the object.

### to_json()

```python
def to_json()
```
Convert the object to a JSON string.

**Returns:** str: A JSON string representation of the object.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.remote/taskdetails ===

# TaskDetails

**Package:** `flyte.remote`

## Parameters

```python
class TaskDetails(
    pb2: task_definition_pb2.TaskDetails,
    max_inline_io_bytes: int,
    overriden_queue: Optional[str],
)
```
| Parameter | Type | Description |
|-|-|-|
| `pb2` | `task_definition_pb2.TaskDetails` | |
| `max_inline_io_bytes` | `int` | |
| `overriden_queue` | `Optional[str]` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `cache` | `None` | The cache policy of the task. |
| `default_input_args` | `None` | The default input arguments of the task. |
| `interface` | `None` | The interface of the task. |
| `name` | `None` | The name of the task. |
| `queue` | `None` | Get the queue name to use for task execution, if overridden. |
| `required_args` | `None` | The required input arguments of the task. |
| `resources` | `None` | Get the resource requests and limits for the task as a tuple (requests, limits). |
| `secrets` | `None` | Get the list of secret keys required by the task. |
| `task_type` | `None` | The type of the task. |
| `version` | `None` | The version of the task. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.remote > TaskDetails > Methods > fetch()** |  |
| **Flyte SDK > Packages > flyte.remote > TaskDetails > Methods > get()** | Get a task by its ID or name. |
| **Flyte SDK > Packages > flyte.remote > TaskDetails > Methods > override()** | Create a new TaskDetails with overridden properties. |
| **Flyte SDK > Packages > flyte.remote > TaskDetails > Methods > to_dict()** | Convert the object to a JSON-serializable dictionary. |
| **Flyte SDK > Packages > flyte.remote > TaskDetails > Methods > to_json()** | Convert the object to a JSON string. |

### fetch()

```python
def fetch(
    name: str,
    project: str | None,
    domain: str | None,
    version: str | None,
    auto_version: AutoVersioning | None,
) -> TaskDetails
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |
| `project` | `str \| None` | |
| `domain` | `str \| None` | |
| `version` | `str \| None` | |
| `auto_version` | `AutoVersioning \| None` | |

### get()

```python
def get(
    name: str,
    project: str | None,
    domain: str | None,
    version: str | None,
    auto_version: AutoVersioning | None,
) -> LazyEntity
```
Get a task by its ID or name. If both are provided, the ID will take precedence.

Either version or auto_version are required parameters.

| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | The name of the task. |
| `project` | `str \| None` | The project of the task. |
| `domain` | `str \| None` | The domain of the task. |
| `version` | `str \| None` | The version of the task. |
| `auto_version` | `AutoVersioning \| None` | If set to "latest", the latest-by-time ordered from now, version of the task will be used. If set to "current", the version will be derived from the callee tasks context. This is useful if you are deploying all environments with the same version. If auto_version is current, you can only access the task from within a task context. |

### override()

```python
def override(
    short_name: Optional[str],
    resources: Optional[flyte.Resources],
    retries: Union[int, flyte.RetryStrategy],
    timeout: Optional[flyte.TimeoutType],
    env_vars: Optional[Dict[str, str]],
    secrets: Optional[flyte.SecretRequest],
    max_inline_io_bytes: Optional[int],
    cache: Optional[flyte.Cache],
    queue: Optional[str],
    kwargs: **kwargs,
) -> TaskDetails
```
Create a new TaskDetails with overridden properties.

| Parameter | Type | Description |
|-|-|-|
| `short_name` | `Optional[str]` | Optional short name for the task. |
| `resources` | `Optional[flyte.Resources]` | Optional resource requirements. |
| `retries` | `Union[int, flyte.RetryStrategy]` | Number of retries or retry strategy. |
| `timeout` | `Optional[flyte.TimeoutType]` | Execution timeout. |
| `env_vars` | `Optional[Dict[str, str]]` | Environment variables to set. |
| `secrets` | `Optional[flyte.SecretRequest]` | Secret requests for the task. |
| `max_inline_io_bytes` | `Optional[int]` | Maximum inline I/O size in bytes. |
| `cache` | `Optional[flyte.Cache]` | Cache configuration. |
| `queue` | `Optional[str]` | Queue name for task execution. |
| `kwargs` | `**kwargs` | |

**Returns:** A new TaskDetails instance with the overrides applied.

### to_dict()

```python
def to_dict()
```
Convert the object to a JSON-serializable dictionary.

**Returns:** dict: A dictionary representation of the object.

### to_json()

```python
def to_json()
```
Convert the object to a JSON string.

**Returns:** str: A JSON string representation of the object.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.remote/timefilter ===

# TimeFilter

**Package:** `flyte.remote`

Filter for time-based fields (e.g. created_at, updated_at).

## Parameters

```python
class TimeFilter(
    after: datetime.datetime | None,
    before: datetime.datetime | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `after` | `datetime.datetime \| None` | Return only entries at or after this datetime (inclusive). |
| `before` | `datetime.datetime \| None` | Return only entries before this datetime (exclusive). |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.remote/trigger ===

# Trigger

**Package:** `flyte.remote`

Represents a trigger in the Flyte platform.

## Parameters

```python
class Trigger(
    pb2: trigger_definition_pb2.Trigger,
    details: TriggerDetails | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `pb2` | `trigger_definition_pb2.Trigger` | |
| `details` | `TriggerDetails \| None` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `automation_spec` | `None` | Get the automation specification for the trigger. |
| `id` | `None` | Get the unique identifier for the trigger. |
| `is_active` | `None` | Check if the trigger is currently active. |
| `name` | `None` | Get the name of the trigger. |
| `task_name` | `None` | Get the name of the task associated with this trigger. |
| `url` | `None` | Get the console URL for viewing the trigger. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.remote > Trigger > Methods > create()** | Create a new trigger in the Flyte platform. |
| **Flyte SDK > Packages > flyte.remote > Trigger > Methods > delete()** | Delete a trigger by its name. |
| **Flyte SDK > Packages > flyte.remote > Trigger > Methods > get()** | Retrieve a trigger by its name and associated task name. |
| **Flyte SDK > Packages > flyte.remote > Trigger > Methods > get_details()** | Get detailed information about this trigger. |
| **Flyte SDK > Packages > flyte.remote > Trigger > Methods > listall()** | List all triggers associated with a specific task or all tasks if no task name is provided. |
| **Flyte SDK > Packages > flyte.remote > Trigger > Methods > to_dict()** | Convert the object to a JSON-serializable dictionary. |
| **Flyte SDK > Packages > flyte.remote > Trigger > Methods > to_json()** | Convert the object to a JSON string. |
| **Flyte SDK > Packages > flyte.remote > Trigger > Methods > update()** | Pause a trigger by its name and associated task name. |

### create()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Trigger.create.aio()`.
```python
def create(
    cls,
    trigger: flyte.Trigger,
    task_name: str,
    task_version: str | None,
) -> Trigger
```
Create a new trigger in the Flyte platform.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `trigger` | `flyte.Trigger` | The flyte.Trigger object containing the trigger definition. |
| `task_name` | `str` | Optional name of the task to associate with the trigger. |
| `task_version` | `str \| None` | |

### delete()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Trigger.delete.aio()`.
```python
def delete(
    cls,
    name: str,
    task_name: str,
    project: str | None,
    domain: str | None,
)
```
Delete a trigger by its name.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | |
| `task_name` | `str` | |
| `project` | `str \| None` | |
| `domain` | `str \| None` | |

### get()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Trigger.get.aio()`.
```python
def get(
    cls,
    name: str,
    task_name: str,
) -> TriggerDetails
```
Retrieve a trigger by its name and associated task name.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | |
| `task_name` | `str` | |

### get_details()

```python
def get_details()
```
Get detailed information about this trigger.

### listall()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Trigger.listall.aio()`.
```python
def listall(
    cls,
    task_name: str | None,
    task_version: str | None,
    limit: int,
) -> AsyncIterator[Trigger]
```
List all triggers associated with a specific task or all tasks if no task name is provided.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `task_name` | `str \| None` | |
| `task_version` | `str \| None` | |
| `limit` | `int` | |

### to_dict()

```python
def to_dict()
```
Convert the object to a JSON-serializable dictionary.

**Returns:** dict: A dictionary representation of the object.

### to_json()

```python
def to_json()
```
Convert the object to a JSON string.

**Returns:** str: A JSON string representation of the object.

### update()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Trigger.update.aio()`.
```python
def update(
    cls,
    name: str,
    task_name: str,
    active: bool,
)
```
Pause a trigger by its name and associated task name.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | |
| `task_name` | `str` | |
| `active` | `bool` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.remote/user ===

# User

**Package:** `flyte.remote`

Represents a user in the Flyte platform.

## Parameters

```python
class User(
    pb2: UserInfoResponse,
)
```
| Parameter | Type | Description |
|-|-|-|
| `pb2` | `UserInfoResponse` | |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.remote > User > Methods > get()** | Fetches information about the currently logged in user. |
| **Flyte SDK > Packages > flyte.remote > User > Methods > name()** | Get the name of the user. |
| **Flyte SDK > Packages > flyte.remote > User > Methods > subject()** | Get the subject identifier of the user. |
| **Flyte SDK > Packages > flyte.remote > User > Methods > to_dict()** | Convert the object to a JSON-serializable dictionary. |
| **Flyte SDK > Packages > flyte.remote > User > Methods > to_json()** | Convert the object to a JSON string. |

### get()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await User.get.aio()`.
```python
def get(
    cls,
) -> User
```
Fetches information about the currently logged in user.
Returns: A User object containing details about the user.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |

### name()

```python
def name()
```
Get the name of the user.

### subject()

```python
def subject()
```
Get the subject identifier of the user.

### to_dict()

```python
def to_dict()
```
Convert the object to a JSON-serializable dictionary.

**Returns:** dict: A dictionary representation of the object.

### to_json()

```python
def to_json()
```
Convert the object to a JSON string.

**Returns:** str: A JSON string representation of the object.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.report ===

# flyte.report

## Directory

### Classes

| Class | Description |
|-|-|
| **Flyte SDK > Packages > flyte.report > Report** |  |

### Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.report > Methods > current_report()** | Get the current report. |
| **Flyte SDK > Packages > flyte.report > Methods > flush()** | Flush the report. |
| **Flyte SDK > Packages > flyte.report > Methods > get_tab()** | Get a tab by name. |
| **Flyte SDK > Packages > flyte.report > Methods > log()** | Log content to the main tab. |
| **Flyte SDK > Packages > flyte.report > Methods > replace()** | Get the report. |

## Methods

#### current_report()

```python
def current_report()
```
Get the current report. This is a dummy report if not in a task context.

**Returns:** The current report.

#### flush()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await flush.aio()`.
```python
def flush()
```
Flush the report.

#### get_tab()

```python
def get_tab(
    name: str,
    create_if_missing: bool,
) -> flyte.report._report.Tab
```
Get a tab by name. If the tab does not exist, create it.

| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | The name of the tab. |
| `create_if_missing` | `bool` | Whether to create the tab if it does not exist. |

**Returns:** The tab.

#### log()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await log.aio()`.
```python
def log(
    content: str,
    do_flush: bool,
)
```
Log content to the main tab. The content should be a valid HTML string, but not a complete HTML document,
 as it will be inserted into a div.

| Parameter | Type | Description |
|-|-|-|
| `content` | `str` | The content to log. |
| `do_flush` | `bool` | flush the report after logging. |

#### replace()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await replace.aio()`.
```python
def replace(
    content: str,
    do_flush: bool,
)
```
Get the report. Replaces the content of the main tab.

| Parameter | Type | Description |
|-|-|-|
| `content` | `str` | |
| `do_flush` | `bool` | |

**Returns:** The report.

## Subpages
- **Flyte SDK > Packages > flyte.report > Report**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.report/report ===

# Report

**Package:** `flyte.report`

## Parameters

```python
class Report(
    name: str,
    tabs: typing.Dict[str, flyte.report._report.Tab],
    template_path: pathlib.Path,
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |
| `tabs` | `typing.Dict[str, flyte.report._report.Tab]` | |
| `template_path` | `pathlib.Path` | |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.report > Report > Methods > get_final_report()** | Get the final report as a string. |
| **Flyte SDK > Packages > flyte.report > Report > Methods > get_tab()** | Get a tab by name. |

### get_final_report()

```python
def get_final_report()
```
Get the final report as a string.

**Returns:** The final report.

### get_tab()

```python
def get_tab(
    name: str,
    create_if_missing: bool,
) -> flyte.report._report.Tab
```
Get a tab by name. If the tab does not exist, create it.

| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | The name of the tab. |
| `create_if_missing` | `bool` | Whether to create the tab if it does not exist. |

**Returns:** The tab.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.sandbox ===

# flyte.sandbox

Sandbox utilities for running isolated code inside Flyte tasks.

Warning: Experimental feature: alpha — APIs may change without notice.

`flyte.sandbox` provides two distinct sandboxing approaches:

---

**1. Orchestration sandbox** — powered by Monty
    Runs pure Python *orchestration logic* (control flow, routing, aggregation)
    with zero overhead. The Monty runtime enforces strong restrictions:
    no imports, no IO, no network access, microsecond startup.  Used via
    `@env.sandbox.orchestrator` or `flyte.sandbox.orchestrator_from_str()`.

    Sandboxed orchestrators are:

    - **Side-effect free**: No filesystem, network, or OS access
    - **Microsecond startup**: No container spin-up — runs in the same process
    - **Multiplexable**: Many orchestrators run safely on the same Python process

    Example:

        env = flyte.TaskEnvironment(name="my-env")

        @env.sandbox.orchestrator
        def route(x: int, y: int) -> int:
            return add(x, y)   # calls a worker task

        pipeline = flyte.sandbox.orchestrator_from_str(
            "add(x, y) * 2",
            inputs={"x": int, "y": int},
            output=int,
            tasks=[add],
        )

---

**2. Code sandbox** — arbitrary code in an isolated container
    Runs arbitrary Python scripts or shell commands inside an ephemeral Docker
    container. The image is built on demand from declared `packages` and
    `system_packages`, executed once, then discarded. Used via `flyte.sandbox.create()`.

    Three execution modes are supported:

    - Code mode — provide Python source that runs with automatic input/output wiring.
    - Verbatim mode — run a script that manages its own I/O via /var/inputs and /var/outputs.
    - Command mode — execute an arbitrary command or entrypoint.

    Examples
    --------

    Code mode
    ~~~~~~~~~

    Provide Python code that uses inputs as variables and assigns
    outputs as Python values.

        _stats_code = """
        import numpy as np
        nums = np.array([float(v) for v in values.split(",")])
        mean = float(np.mean(nums))
        std  = float(np.std(nums))

        window_end = dt + delta
        """

        stats_sandbox = flyte.sandbox.create(
            name="numpy-stats",
            code=_stats_code,
            inputs={
                "values": str,
                "dt": datetime.datetime,
                "delta": datetime.timedelta,
            },
            outputs={
                "mean": float,
                "std": float,
                "window_end": datetime.datetime,
            },
            packages=["numpy"],
        )

        mean, std, window_end = await stats_sandbox.run.aio(
            values="1,2,3,4,5",
            dt=datetime.datetime(2024, 1, 1),
            delta=datetime.timedelta(days=1),
        )

    Verbatim mode
    ~~~~~~~~~~~~~

    Run a script that explicitly reads inputs from /var/inputs and
    writes outputs to /var/outputs.

        _etl_script = """        import json, pathlib

        payload = json.loads(
            pathlib.Path("/var/inputs/payload").read_text()
        )
        total = sum(payload["values"])

        pathlib.Path("/var/outputs/total").write_text(str(total))
        """

        etl_sandbox = flyte.sandbox.create(
            name="etl-script",
            code=_etl_script,
            inputs={"payload": File},
            outputs={"total": int},
            auto_io=False,
        )

    Command mode
    ~~~~~~~~~~~~

    Execute an arbitrary command inside the sandbox environment.

        sandbox = flyte.sandbox.create(
            name="test-runner",
            command=["/bin/bash", "-c", "pytest /var/inputs/tests.py -q"],
            inputs={"tests.py": File},
            outputs={"exit_code": str},
        )

    Notes
    -----

    • Inputs are materialized under /var/inputs.
    • Outputs must be written to /var/outputs.
    • In code mode, inputs are available as Python variables and
    scalar outputs are captured automatically.
    • Additional Python dependencies can be specified via the
    `packages` argument.
## Directory

### Classes

| Class | Description |
|-|-|
| **Flyte SDK > Packages > flyte.sandbox > CodeTaskTemplate** | A sandboxed task created from a code string rather than a decorated function. |
| **Flyte SDK > Packages > flyte.sandbox > ImageConfig** | Configuration for Docker image building at runtime. |
| **Flyte SDK > Packages > flyte.sandbox > SandboxedConfig** | Configuration for a sandboxed task executed via Monty. |
| **Flyte SDK > Packages > flyte.sandbox > SandboxedTaskTemplate** | A task template that executes the function body in a Monty sandbox. |

### Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.sandbox > Methods > create()** | Create a stateless Python code sandbox. |
| **Flyte SDK > Packages > flyte.sandbox > Methods > orchestrate_local()** | One-shot local execution of a code string in the Monty sandbox. |
| **Flyte SDK > Packages > flyte.sandbox > Methods > orchestrator_from_str()** | Create a reusable sandboxed task from a code string. |

### Variables

| Property | Type | Description |
|-|-|-|
| `ORCHESTRATOR_SYNTAX_PROMPT` | `str` |  |
| `sandbox_environment` | `TaskEnvironment` |  |

## Methods

#### create()

```python
def create(
    name: typing.Optional[str],
    code: typing.Optional[str],
    inputs: typing.Optional[dict[str, type]],
    outputs: typing.Optional[dict[str, type]],
    command: typing.Optional[list[str]],
    arguments: typing.Optional[list[str]],
    packages: typing.Optional[list[str]],
    system_packages: typing.Optional[list[str]],
    additional_commands: typing.Optional[list[str]],
    resources: typing.Optional[flyte._resources.Resources],
    image_config: typing.Optional[flyte.sandbox._code_sandbox.ImageConfig],
    image_name: typing.Optional[str],
    image: typing.Optional[str],
    auto_io: bool,
    retries: int,
    timeout: typing.Optional[int],
    env_vars: typing.Optional[dict[str, str]],
    secrets: typing.Optional[list],
    cache: str,
) -> flyte.sandbox._code_sandbox._Sandbox
```
Create a stateless Python code sandbox.

The sandbox is **stateless** — each invocation runs in a fresh, ephemeral
container. No filesystem state, environment variables or side effects
carry over between runs.

Three modes, mutually exclusive:

- **Auto-IO mode** (`code` provided, `auto_io=True`, default): write
  just the business logic. Flyte auto-generates an argparse preamble so
  declared inputs are available as local variables, and writes declared
  scalar outputs to `/var/outputs/` automatically. No boilerplate needed.
- **Verbatim mode** (`code` provided, `auto_io=False`): run an
  arbitrary Python script as-is. CLI args for declared inputs are still
  forwarded, but the script handles all I/O itself (reading from
  `/var/inputs/`, writing to `/var/outputs/&lt;name&gt;` manually).
- **Command mode** (`command` provided): run any shell command directly,
  e.g. a compiled binary or a shell pipeline.

Call `.run()` on the returned sandbox to build the image and execute.

Example — auto-IO mode (default, no boilerplate)::

    sandbox = flyte.sandbox.create(
        name="double",
        code="result = x * 2",
        inputs={"x": int},
        outputs={"result": int},
    )
    result = await sandbox.run.aio(x=21)  # returns 42

Example — verbatim mode (complete Python script, full control)::

    sandbox = flyte.sandbox.create(
        name="etl",
        code="""
            import json, pathlib
            data = json.loads(pathlib.Path("/var/inputs/payload").read_text())
            pathlib.Path("/var/outputs/total").write_text(str(sum(data["values"])))
        """,
        inputs={"payload": File},
        outputs={"total": int},
        auto_io=False,
    )

Example — command mode::

    sandbox = flyte.sandbox.create(
        name="test-runner",
        command=["/bin/bash", "-c", pytest_cmd],
        arguments=["_", "/var/inputs/solution.py", "/var/inputs/tests.py"],
        inputs={"solution.py": File, "tests.py": File},
        outputs={"exit_code": str},
    )

| Parameter | Type | Description |
|-|-|-|
| `name` | `typing.Optional[str]` | Sandbox name. Derives task and image names. |
| `code` | `typing.Optional[str]` | Python source to run (auto-IO or verbatim mode). Mutually exclusive with `command`. |
| `inputs` | `typing.Optional[dict[str, type]]` | Input type declarations. Supported types: - Primitive: `int`, `float`, `str`, `bool` - Date/time: `datetime.datetime`, `datetime.timedelta` - IO handles: `flyte.io.File`   (bind-mounted at `/var/inputs/&lt;name&gt;`; available as a path   string in auto-IO mode) |
| `outputs` | `typing.Optional[dict[str, type]]` | Output type declarations. Supported types: - Primitive: `int`, `float`, `str`, `bool` - Date/time: `datetime.datetime` (ISO-8601), `datetime.timedelta` - IO handles: `flyte.io.File`   (user code must write the file to `/var/outputs/&lt;name&gt;`) |
| `command` | `typing.Optional[list[str]]` | Entrypoint command (command mode). Mutually exclusive with `code`. |
| `arguments` | `typing.Optional[list[str]]` | Arguments forwarded to `command` (command mode only). |
| `packages` | `typing.Optional[list[str]]` | Python packages to install via pip. |
| `system_packages` | `typing.Optional[list[str]]` | System packages to install via apt. |
| `additional_commands` | `typing.Optional[list[str]]` | Extra Dockerfile `RUN` commands. |
| `resources` | `typing.Optional[flyte._resources.Resources]` | CPU / memory resources for the container. |
| `image_config` | `typing.Optional[flyte.sandbox._code_sandbox.ImageConfig]` | Registry and Python version settings. |
| `image_name` | `typing.Optional[str]` | Explicit image name, overrides the auto-generated one. |
| `image` | `typing.Optional[str]` | Pre-built image URI. Skips the build step if provided. |
| `auto_io` | `bool` | When `True` (default), Flyte wraps `code` with an auto-generated argparse preamble and output-writing epilogue so declared inputs are available as local variables and scalar outputs are collected automatically — no boilerplate needed. When `False`, `code` is run verbatim and must handle all I/O itself. |
| `retries` | `int` | Number of task retries on failure. |
| `timeout` | `typing.Optional[int]` | Task timeout in seconds. |
| `env_vars` | `typing.Optional[dict[str, str]]` | Environment variables available inside the container. |
| `secrets` | `typing.Optional[list]` | Flyte `flyte.Secret` objects to mount. |
| `cache` | `str` | Cache behaviour — `"auto"`, `"override"`, or `"disable"`. |

**Returns:** Configured sandbox ready to `.run()`.

#### orchestrate_local()

```python
def orchestrate_local(
    source: str,
    inputs: Dict[str, Any],
    tasks: Optional[List[Any]],
    timeout_ms: int,
) -> Any
```
One-shot local execution of a code string in the Monty sandbox.

Warning: Experimental feature: alpha — APIs may change without notice.

    Sends the code + inputs to Monty and returns the result directly,
    without creating a `TaskTemplate` or going through the controller.

    The **last expression** in *source* becomes the return value::

        result = await sandbox.orchestrate_local(
            "add(x, y) * 2",
            inputs={"x": 1, "y": 2},
            tasks=[add],
        )
        # → 6

    Parameters
    ----------
    source:
        Python code string to execute in the sandbox.
    inputs:
        Mapping of input names to their values.
    tasks:
        List of external functions (tasks, durable ops) available inside the
        sandbox. Each item's `__name__` is used as the key.
    timeout_ms:
        Sandbox execution timeout in milliseconds.

| Parameter | Type | Description |
|-|-|-|
| `source` | `str` | |
| `inputs` | `Dict[str, Any]` | |
| `tasks` | `Optional[List[Any]]` | |
| `timeout_ms` | `int` | |

#### orchestrator_from_str()

```python
def orchestrator_from_str(
    source: str,
    inputs: Dict[str, type],
    output: type,
    tasks: Optional[List[Any]],
    name: str,
    timeout_ms: int,
    cache: CacheRequest,
    retries: int,
    image: Optional[Any],
) -> CodeTaskTemplate
```
Create a reusable sandboxed task from a code string.

Warning: Experimental feature: alpha — APIs may change without notice.

    The returned `CodeTaskTemplate` can be passed to `flyte.run()`
    just like a decorated task.

    The **last expression** in *source* becomes the return value::

        pipeline = sandbox.orchestrator_from_str(
            "add(x, y) * 2",
            inputs={"x": int, "y": int},
            output=int,
            tasks=[add],
        )
        result = flyte.run(pipeline, x=1, y=2)  # → 6

    Parameters
    ----------
    source:
        Python code string to execute in the sandbox.
    inputs:
        Mapping of input names to their types.
    output:
        The return type (default `NoneType`).
    tasks:
        List of external functions (tasks, durable ops) available inside the
        sandbox. Each item's `__name__` is used as the key.
    name:
        Task name (default `"sandboxed-code"`).
    timeout_ms:
        Sandbox execution timeout in milliseconds.
    cache:
        Cache policy for the task.
    retries:
        Number of retries on failure.
    image:
        Docker image to use. If not provided, a default Debian image with
        `pydantic-monty` is created automatically.

| Parameter | Type | Description |
|-|-|-|
| `source` | `str` | |
| `inputs` | `Dict[str, type]` | |
| `output` | `type` | |
| `tasks` | `Optional[List[Any]]` | |
| `name` | `str` | |
| `timeout_ms` | `int` | |
| `cache` | `CacheRequest` | |
| `retries` | `int` | |
| `image` | `Optional[Any]` | |

## Subpages
- **Flyte SDK > Packages > flyte.sandbox > CodeTaskTemplate**
- **Flyte SDK > Packages > flyte.sandbox > ImageConfig**
- **Flyte SDK > Packages > flyte.sandbox > SandboxedConfig**
- **Flyte SDK > Packages > flyte.sandbox > SandboxedTaskTemplate**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.sandbox/codetasktemplate ===

# CodeTaskTemplate

**Package:** `flyte.sandbox`

A sandboxed task created from a code string rather than a decorated function.

Unlike `SandboxedTaskTemplate` (which extracts source from a Python
function), this class accepts pre-transformed source code and an explicit
dict of external functions.  It is constructed via `flyte.sandbox.orchestrator_from_str`.

## Parameters

```python
class CodeTaskTemplate(
    name: str,
    interface: NativeInterface,
    short_name: str,
    task_type: str,
    task_type_version: int,
    image: Union[str, Image, Literal['auto']] | None,
    resources: Optional[Resources],
    cache: CacheRequest,
    interruptible: bool,
    retries: Union[int, RetryStrategy],
    reusable: Union[ReusePolicy, None],
    docs: Optional[Documentation],
    env_vars: Optional[Dict[str, str]],
    secrets: Optional[SecretRequest],
    timeout: Optional[TimeoutType],
    pod_template: Optional[Union[str, PodTemplate]],
    report: bool,
    queue: Optional[str],
    debuggable: bool,
    parent_env: Optional[weakref.ReferenceType[TaskEnvironment]],
    parent_env_name: Optional[str],
    max_inline_io_bytes: int,
    triggers: Tuple[Trigger, ...],
    links: Tuple[Link, ...],
    _call_as_synchronous: bool,
    func: F,
    plugin_config: Optional[SandboxedConfig],
    task_resolver: Optional[Any],
    _user_source: str,
    _user_input_names: List[str],
    _user_functions: Dict[str, Any],
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |
| `interface` | `NativeInterface` | |
| `short_name` | `str` | |
| `task_type` | `str` | |
| `task_type_version` | `int` | |
| `image` | `Union[str, Image, Literal['auto']] \| None` | |
| `resources` | `Optional[Resources]` | |
| `cache` | `CacheRequest` | |
| `interruptible` | `bool` | |
| `retries` | `Union[int, RetryStrategy]` | |
| `reusable` | `Union[ReusePolicy, None]` | |
| `docs` | `Optional[Documentation]` | |
| `env_vars` | `Optional[Dict[str, str]]` | |
| `secrets` | `Optional[SecretRequest]` | |
| `timeout` | `Optional[TimeoutType]` | |
| `pod_template` | `Optional[Union[str, PodTemplate]]` | |
| `report` | `bool` | |
| `queue` | `Optional[str]` | |
| `debuggable` | `bool` | |
| `parent_env` | `Optional[weakref.ReferenceType[TaskEnvironment]]` | |
| `parent_env_name` | `Optional[str]` | |
| `max_inline_io_bytes` | `int` | |
| `triggers` | `Tuple[Trigger, ...]` | |
| `links` | `Tuple[Link, ...]` | |
| `_call_as_synchronous` | `bool` | |
| `func` | `F` | |
| `plugin_config` | `Optional[SandboxedConfig]` | |
| `task_resolver` | `Optional[Any]` | |
| `_user_source` | `str` | |
| `_user_input_names` | `List[str]` | |
| `_user_functions` | `Dict[str, Any]` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `json_schema` | `None` | JSON schema for the task inputs, following the Flyte standard.  Delegates to NativeInterface.json_schema, which uses the type engine to produce a LiteralType per input and converts to JSON schema. |
| `native_interface` | `None` |  |
| `source_file` | `None` | Returns the source file of the function, if available. This is useful for debugging and tracing. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.sandbox > CodeTaskTemplate > Methods > aio()** | The aio function allows executing "sync" tasks, in an async context. |
| **Flyte SDK > Packages > flyte.sandbox > CodeTaskTemplate > Methods > config()** | Returns additional configuration for the task. |
| **Flyte SDK > Packages > flyte.sandbox > CodeTaskTemplate > Methods > container_args()** | Returns the container args for the task. |
| **Flyte SDK > Packages > flyte.sandbox > CodeTaskTemplate > Methods > custom_config()** | Returns additional configuration for the task. |
| **Flyte SDK > Packages > flyte.sandbox > CodeTaskTemplate > Methods > data_loading_config()** | This configuration allows executing raw containers in Flyte using the Flyte CoPilot system. |
| **Flyte SDK > Packages > flyte.sandbox > CodeTaskTemplate > Methods > execute()** | Execute the function body in a Monty sandbox. |
| **Flyte SDK > Packages > flyte.sandbox > CodeTaskTemplate > Methods > forward()** | Not supported — there is no Python function to call directly. |
| **Flyte SDK > Packages > flyte.sandbox > CodeTaskTemplate > Methods > override()** | Override various parameters of the task template. |
| **Flyte SDK > Packages > flyte.sandbox > CodeTaskTemplate > Methods > post()** | This is the postexecute function that will be. |
| **Flyte SDK > Packages > flyte.sandbox > CodeTaskTemplate > Methods > pre()** | This is the preexecute function that will be. |
| **Flyte SDK > Packages > flyte.sandbox > CodeTaskTemplate > Methods > sql()** | Returns the SQL for the task. |

### aio()

```python
def aio(
    args: *args,
    kwargs: **kwargs,
) -> Coroutine[Any, Any, R] | R
```
The aio function allows executing "sync" tasks, in an async context. This helps with migrating v1 defined sync
tasks to be used within an asyncio parent task.
This function will also re-raise exceptions from the underlying task.

```python
@env.task
def my_legacy_task(x: int) -> int:
    return x

@env.task
async def my_new_parent_task(n: int) -> List[int]:
    collect = []
    for x in range(n):
        collect.append(my_legacy_task.aio(x))
    return asyncio.gather(*collect)
```

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### config()

```python
def config(
    sctx: SerializationContext,
) -> Dict[str, str]
```
Returns additional configuration for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### container_args()

```python
def container_args(
    serialize_context: SerializationContext,
) -> List[str]
```
Returns the container args for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `serialize_context` | `SerializationContext` | |

### custom_config()

```python
def custom_config(
    sctx: SerializationContext,
) -> Dict[str, str]
```
Returns additional configuration for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### data_loading_config()

```python
def data_loading_config(
    sctx: SerializationContext,
) -> DataLoadingConfig
```
This configuration allows executing raw containers in Flyte using the Flyte CoPilot system
Flyte CoPilot, eliminates the needs of sdk inside the container. Any inputs required by the users container
are side-loaded in the input_path
Any outputs generated by the user container - within output_path are automatically uploaded

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### execute()

```python
def execute(
    args,
    kwargs,
) -> Any
```
Execute the function body in a Monty sandbox.

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### forward()

```python
def forward(
    args,
    kwargs,
) -> Any
```
Not supported — there is no Python function to call directly.

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### override()

```python
def override(
    short_name: Optional[str],
    resources: Optional[Resources],
    cache: Optional[CacheRequest],
    retries: Union[int, RetryStrategy],
    timeout: Optional[TimeoutType],
    reusable: Union[ReusePolicy, Literal['off'], None],
    env_vars: Optional[Dict[str, str]],
    secrets: Optional[SecretRequest],
    max_inline_io_bytes: int | None,
    pod_template: Optional[Union[str, PodTemplate]],
    queue: Optional[str],
    interruptible: Optional[bool],
    links: Tuple[Link, ...],
    kwargs: **kwargs,
) -> TaskTemplate
```
Override various parameters of the task template. This allows for dynamic configuration of the task
when it is called, such as changing the image, resources, cache policy, etc.

| Parameter | Type | Description |
|-|-|-|
| `short_name` | `Optional[str]` | Optional override for the short name of the task. |
| `resources` | `Optional[Resources]` | Optional override for the resources to use for the task. |
| `cache` | `Optional[CacheRequest]` | Optional override for the cache policy for the task. |
| `retries` | `Union[int, RetryStrategy]` | Optional override for the number of retries for the task. |
| `timeout` | `Optional[TimeoutType]` | Optional override for the timeout for the task. |
| `reusable` | `Union[ReusePolicy, Literal['off'], None]` | Optional override for the reusability policy for the task. |
| `env_vars` | `Optional[Dict[str, str]]` | Optional override for the environment variables to set for the task. |
| `secrets` | `Optional[SecretRequest]` | Optional override for the secrets that will be injected into the task at runtime. |
| `max_inline_io_bytes` | `int \| None` | Optional override for the maximum allowed size (in bytes) for all inputs and outputs passed directly to the task. |
| `pod_template` | `Optional[Union[str, PodTemplate]]` | Optional override for the pod template to use for the task. |
| `queue` | `Optional[str]` | Optional override for the queue to use for the task. |
| `interruptible` | `Optional[bool]` | Optional override for the interruptible policy for the task. |
| `links` | `Tuple[Link, ...]` | Optional override for the Links associated with the task. |
| `kwargs` | `**kwargs` | Additional keyword arguments for further overrides. Some fields like name, image, docs, and interface cannot be overridden. |

**Returns:** A new TaskTemplate instance with the overridden parameters.

### post()

```python
def post(
    return_vals: Any,
) -> Any
```
This is the postexecute function that will be
called after the task is executed

| Parameter | Type | Description |
|-|-|-|
| `return_vals` | `Any` | |

### pre()

```python
def pre(
    args,
    kwargs,
) -> Dict[str, Any]
```
This is the preexecute function that will be
called before the task is executed

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### sql()

```python
def sql(
    sctx: SerializationContext,
) -> Optional[str]
```
Returns the SQL for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.sandbox/imageconfig ===

# ImageConfig

**Package:** `flyte.sandbox`

Configuration for Docker image building at runtime.

## Parameters

```python
class ImageConfig(
    registry: typing.Optional[str],
    registry_secret: typing.Optional[str],
    python_version: typing.Optional[tuple[int, int]],
)
```
| Parameter | Type | Description |
|-|-|-|
| `registry` | `typing.Optional[str]` | |
| `registry_secret` | `typing.Optional[str]` | |
| `python_version` | `typing.Optional[tuple[int, int]]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.sandbox/sandboxedconfig ===

# SandboxedConfig

**Package:** `flyte.sandbox`

Configuration for a sandboxed task executed via Monty.

## Parameters

```python
class SandboxedConfig(
    max_memory: int,
    max_stack_depth: int,
    timeout_ms: int,
    type_check: bool,
)
```
| Parameter | Type | Description |
|-|-|-|
| `max_memory` | `int` | |
| `max_stack_depth` | `int` | |
| `timeout_ms` | `int` | |
| `type_check` | `bool` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.sandbox/sandboxedtasktemplate ===

# SandboxedTaskTemplate

**Package:** `flyte.sandbox`

A task template that executes the function body in a Monty sandbox.

For pure Python functions (no external calls), Monty executes the
entire body without pausing. For functions that call other tasks or
durable operations, `run_monty_async` handles async dispatch.

## Parameters

```python
class SandboxedTaskTemplate(
    name: str,
    interface: NativeInterface,
    short_name: str,
    task_type: str,
    task_type_version: int,
    image: Union[str, Image, Literal['auto']] | None,
    resources: Optional[Resources],
    cache: CacheRequest,
    interruptible: bool,
    retries: Union[int, RetryStrategy],
    reusable: Union[ReusePolicy, None],
    docs: Optional[Documentation],
    env_vars: Optional[Dict[str, str]],
    secrets: Optional[SecretRequest],
    timeout: Optional[TimeoutType],
    pod_template: Optional[Union[str, PodTemplate]],
    report: bool,
    queue: Optional[str],
    debuggable: bool,
    parent_env: Optional[weakref.ReferenceType[TaskEnvironment]],
    parent_env_name: Optional[str],
    max_inline_io_bytes: int,
    triggers: Tuple[Trigger, ...],
    links: Tuple[Link, ...],
    _call_as_synchronous: bool,
    func: F,
    plugin_config: Optional[SandboxedConfig],
    task_resolver: Optional[Any],
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |
| `interface` | `NativeInterface` | |
| `short_name` | `str` | |
| `task_type` | `str` | |
| `task_type_version` | `int` | |
| `image` | `Union[str, Image, Literal['auto']] \| None` | |
| `resources` | `Optional[Resources]` | |
| `cache` | `CacheRequest` | |
| `interruptible` | `bool` | |
| `retries` | `Union[int, RetryStrategy]` | |
| `reusable` | `Union[ReusePolicy, None]` | |
| `docs` | `Optional[Documentation]` | |
| `env_vars` | `Optional[Dict[str, str]]` | |
| `secrets` | `Optional[SecretRequest]` | |
| `timeout` | `Optional[TimeoutType]` | |
| `pod_template` | `Optional[Union[str, PodTemplate]]` | |
| `report` | `bool` | |
| `queue` | `Optional[str]` | |
| `debuggable` | `bool` | |
| `parent_env` | `Optional[weakref.ReferenceType[TaskEnvironment]]` | |
| `parent_env_name` | `Optional[str]` | |
| `max_inline_io_bytes` | `int` | |
| `triggers` | `Tuple[Trigger, ...]` | |
| `links` | `Tuple[Link, ...]` | |
| `_call_as_synchronous` | `bool` | |
| `func` | `F` | |
| `plugin_config` | `Optional[SandboxedConfig]` | |
| `task_resolver` | `Optional[Any]` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `json_schema` | `None` | JSON schema for the task inputs, following the Flyte standard.  Delegates to NativeInterface.json_schema, which uses the type engine to produce a LiteralType per input and converts to JSON schema. |
| `native_interface` | `None` |  |
| `source_file` | `None` | Returns the source file of the function, if available. This is useful for debugging and tracing. |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.sandbox > SandboxedTaskTemplate > Methods > aio()** | The aio function allows executing "sync" tasks, in an async context. |
| **Flyte SDK > Packages > flyte.sandbox > SandboxedTaskTemplate > Methods > config()** | Returns additional configuration for the task. |
| **Flyte SDK > Packages > flyte.sandbox > SandboxedTaskTemplate > Methods > container_args()** | Returns the container args for the task. |
| **Flyte SDK > Packages > flyte.sandbox > SandboxedTaskTemplate > Methods > custom_config()** | Returns additional configuration for the task. |
| **Flyte SDK > Packages > flyte.sandbox > SandboxedTaskTemplate > Methods > data_loading_config()** | This configuration allows executing raw containers in Flyte using the Flyte CoPilot system. |
| **Flyte SDK > Packages > flyte.sandbox > SandboxedTaskTemplate > Methods > execute()** | Execute the function body in a Monty sandbox. |
| **Flyte SDK > Packages > flyte.sandbox > SandboxedTaskTemplate > Methods > forward()** | Bypass Monty and call the function directly (for local/debug execution). |
| **Flyte SDK > Packages > flyte.sandbox > SandboxedTaskTemplate > Methods > override()** | Override various parameters of the task template. |
| **Flyte SDK > Packages > flyte.sandbox > SandboxedTaskTemplate > Methods > post()** | This is the postexecute function that will be. |
| **Flyte SDK > Packages > flyte.sandbox > SandboxedTaskTemplate > Methods > pre()** | This is the preexecute function that will be. |
| **Flyte SDK > Packages > flyte.sandbox > SandboxedTaskTemplate > Methods > sql()** | Returns the SQL for the task. |

### aio()

```python
def aio(
    args: *args,
    kwargs: **kwargs,
) -> Coroutine[Any, Any, R] | R
```
The aio function allows executing "sync" tasks, in an async context. This helps with migrating v1 defined sync
tasks to be used within an asyncio parent task.
This function will also re-raise exceptions from the underlying task.

```python
@env.task
def my_legacy_task(x: int) -> int:
    return x

@env.task
async def my_new_parent_task(n: int) -> List[int]:
    collect = []
    for x in range(n):
        collect.append(my_legacy_task.aio(x))
    return asyncio.gather(*collect)
```

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### config()

```python
def config(
    sctx: SerializationContext,
) -> Dict[str, str]
```
Returns additional configuration for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### container_args()

```python
def container_args(
    serialize_context: SerializationContext,
) -> List[str]
```
Returns the container args for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `serialize_context` | `SerializationContext` | |

### custom_config()

```python
def custom_config(
    sctx: SerializationContext,
) -> Dict[str, str]
```
Returns additional configuration for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### data_loading_config()

```python
def data_loading_config(
    sctx: SerializationContext,
) -> DataLoadingConfig
```
This configuration allows executing raw containers in Flyte using the Flyte CoPilot system
Flyte CoPilot, eliminates the needs of sdk inside the container. Any inputs required by the users container
are side-loaded in the input_path
Any outputs generated by the user container - within output_path are automatically uploaded

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### execute()

```python
def execute(
    args,
    kwargs,
) -> Any
```
Execute the function body in a Monty sandbox.

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### forward()

```python
def forward(
    args,
    kwargs,
) -> Any
```
Bypass Monty and call the function directly (for local/debug execution).

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### override()

```python
def override(
    short_name: Optional[str],
    resources: Optional[Resources],
    cache: Optional[CacheRequest],
    retries: Union[int, RetryStrategy],
    timeout: Optional[TimeoutType],
    reusable: Union[ReusePolicy, Literal['off'], None],
    env_vars: Optional[Dict[str, str]],
    secrets: Optional[SecretRequest],
    max_inline_io_bytes: int | None,
    pod_template: Optional[Union[str, PodTemplate]],
    queue: Optional[str],
    interruptible: Optional[bool],
    links: Tuple[Link, ...],
    kwargs: **kwargs,
) -> TaskTemplate
```
Override various parameters of the task template. This allows for dynamic configuration of the task
when it is called, such as changing the image, resources, cache policy, etc.

| Parameter | Type | Description |
|-|-|-|
| `short_name` | `Optional[str]` | Optional override for the short name of the task. |
| `resources` | `Optional[Resources]` | Optional override for the resources to use for the task. |
| `cache` | `Optional[CacheRequest]` | Optional override for the cache policy for the task. |
| `retries` | `Union[int, RetryStrategy]` | Optional override for the number of retries for the task. |
| `timeout` | `Optional[TimeoutType]` | Optional override for the timeout for the task. |
| `reusable` | `Union[ReusePolicy, Literal['off'], None]` | Optional override for the reusability policy for the task. |
| `env_vars` | `Optional[Dict[str, str]]` | Optional override for the environment variables to set for the task. |
| `secrets` | `Optional[SecretRequest]` | Optional override for the secrets that will be injected into the task at runtime. |
| `max_inline_io_bytes` | `int \| None` | Optional override for the maximum allowed size (in bytes) for all inputs and outputs passed directly to the task. |
| `pod_template` | `Optional[Union[str, PodTemplate]]` | Optional override for the pod template to use for the task. |
| `queue` | `Optional[str]` | Optional override for the queue to use for the task. |
| `interruptible` | `Optional[bool]` | Optional override for the interruptible policy for the task. |
| `links` | `Tuple[Link, ...]` | Optional override for the Links associated with the task. |
| `kwargs` | `**kwargs` | Additional keyword arguments for further overrides. Some fields like name, image, docs, and interface cannot be overridden. |

**Returns:** A new TaskTemplate instance with the overridden parameters.

### post()

```python
def post(
    return_vals: Any,
) -> Any
```
This is the postexecute function that will be
called after the task is executed

| Parameter | Type | Description |
|-|-|-|
| `return_vals` | `Any` | |

### pre()

```python
def pre(
    args,
    kwargs,
) -> Dict[str, Any]
```
This is the preexecute function that will be
called before the task is executed

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### sql()

```python
def sql(
    sctx: SerializationContext,
) -> Optional[str]
```
Returns the SQL for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.storage ===

# flyte.storage

## Directory

### Classes

| Class | Description |
|-|-|
| **Flyte SDK > Packages > flyte.storage > ABFS** | Any Azure Blob Storage specific configuration. |
| **Flyte SDK > Packages > flyte.storage > GCS** | Any GCS specific configuration. |
| **Flyte SDK > Packages > flyte.storage > S3** | S3 specific configuration. |
| **Flyte SDK > Packages > flyte.storage > Storage** | Data storage configuration that applies across any provider. |

### Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.storage > Methods > exists()** | Check if a path exists. |
| **Flyte SDK > Packages > flyte.storage > Methods > exists_sync()** |  |
| **Flyte SDK > Packages > flyte.storage > Methods > get()** |  |
| **Flyte SDK > Packages > flyte.storage > Methods > get_configured_fsspec_kwargs()** |  |
| **Flyte SDK > Packages > flyte.storage > Methods > get_random_local_directory()** |  |
| **Flyte SDK > Packages > flyte.storage > Methods > get_random_local_path()** | Use file_path_or_file_name, when you want a random directory, but want to preserve the leaf file name. |
| **Flyte SDK > Packages > flyte.storage > Methods > get_stream()** | Get a stream of data from a remote location. |
| **Flyte SDK > Packages > flyte.storage > Methods > get_underlying_filesystem()** |  |
| **Flyte SDK > Packages > flyte.storage > Methods > is_remote()** | Let's find a replacement. |
| **Flyte SDK > Packages > flyte.storage > Methods > join()** | Join multiple paths together. |
| **Flyte SDK > Packages > flyte.storage > open()** | Asynchronously open a file and return an async context manager. |
| **Flyte SDK > Packages > flyte.storage > put()** |  |
| **Flyte SDK > Packages > flyte.storage > put_stream()** | Put a stream of data to a remote location. |

## Methods

#### exists()

```python
def exists(
    path: str,
    kwargs,
) -> bool
```
Check if a path exists.

| Parameter | Type | Description |
|-|-|-|
| `path` | `str` | Path to be checked. |
| `kwargs` | `**kwargs` | Additional arguments to be passed to the underlying filesystem. |

**Returns:** True if the path exists, False otherwise.

#### exists_sync()

```python
def exists_sync(
    path: str,
    kwargs,
) -> bool
```
| Parameter | Type | Description |
|-|-|-|
| `path` | `str` | |
| `kwargs` | `**kwargs` | |

#### get()

```python
def get(
    from_path: str,
    to_path: Optional[str | pathlib.Path],
    recursive: bool,
    kwargs,
) -> str
```
| Parameter | Type | Description |
|-|-|-|
| `from_path` | `str` | |
| `to_path` | `Optional[str \| pathlib.Path]` | |
| `recursive` | `bool` | |
| `kwargs` | `**kwargs` | |

#### get_configured_fsspec_kwargs()

```python
def get_configured_fsspec_kwargs(
    protocol: typing.Optional[str],
    anonymous: bool,
) -> typing.Dict[str, typing.Any]
```
| Parameter | Type | Description |
|-|-|-|
| `protocol` | `typing.Optional[str]` | |
| `anonymous` | `bool` | |

#### get_random_local_directory()

```python
def get_random_local_directory()
```
**Returns:** pathlib.Path

#### get_random_local_path()

```python
def get_random_local_path(
    file_path_or_file_name: pathlib.Path | str | None,
) -> pathlib.Path
```
Use file_path_or_file_name, when you want a random directory, but want to preserve the leaf file name

| Parameter | Type | Description |
|-|-|-|
| `file_path_or_file_name` | `pathlib.Path \| str \| None` | |

#### get_stream()

```python
def get_stream(
    path: str,
    chunk_size,
    kwargs,
) -> AsyncGenerator[bytes, None]
```
Get a stream of data from a remote location.
This is useful for downloading streaming data from a remote location.
Example usage:
```python
import flyte.storage as storage
async for chunk in storage.get_stream(path="s3://my_bucket/my_file.txt"):
    process(chunk)
```

| Parameter | Type | Description |
|-|-|-|
| `path` | `str` | Path to the remote location where the data will be downloaded. |
| `chunk_size` |  | Size of each chunk to be read from the file. |
| `kwargs` | `**kwargs` | Additional arguments to be passed to the underlying filesystem. |

**Returns:** An async iterator that yields chunks of bytes.

#### get_underlying_filesystem()

```python
def get_underlying_filesystem(
    protocol: typing.Optional[str],
    anonymous: bool,
    path: typing.Optional[str],
    kwargs,
) -> fsspec.AbstractFileSystem
```
| Parameter | Type | Description |
|-|-|-|
| `protocol` | `typing.Optional[str]` | |
| `anonymous` | `bool` | |
| `path` | `typing.Optional[str]` | |
| `kwargs` | `**kwargs` | |

#### is_remote()

```python
def is_remote(
    path: typing.Union[pathlib.Path | str],
) -> bool
```
Let's find a replacement

| Parameter | Type | Description |
|-|-|-|
| `path` | `typing.Union[pathlib.Path \| str]` | |

#### join()

```python
def join(
    paths: str,
) -> str
```
Join multiple paths together. This is a wrapper around os.path.join.
# TODO replace with proper join with fsspec root etc

| Parameter | Type | Description |
|-|-|-|
| `paths` | `str` | Paths to be joined. |

#### open()

```python
def open(
    path: str,
    mode: str,
    kwargs,
) -> AsyncReadableFile | AsyncWritableFile
```
Asynchronously open a file and return an async context manager.
This function checks if the underlying filesystem supports obstore bypass.
If it does, it uses obstore to open the file. Otherwise, it falls back to
the standard _open function which uses AsyncFileSystem.

It will raise NotImplementedError if neither obstore nor AsyncFileSystem is supported.

| Parameter | Type | Description |
|-|-|-|
| `path` | `str` | |
| `mode` | `str` | |
| `kwargs` | `**kwargs` | |

#### put()

```python
def put(
    from_path: str,
    to_path: Optional[str],
    recursive: bool,
    batch_size: Optional[int],
    kwargs,
) -> str
```
| Parameter | Type | Description |
|-|-|-|
| `from_path` | `str` | |
| `to_path` | `Optional[str]` | |
| `recursive` | `bool` | |
| `batch_size` | `Optional[int]` | |
| `kwargs` | `**kwargs` | |

#### put_stream()

```python
def put_stream(
    data_iterable: typing.AsyncIterable[bytes] | bytes,
    name: str | None,
    to_path: str | None,
    kwargs,
) -> str
```
Put a stream of data to a remote location. This is useful for streaming data to a remote location.
Example usage:
```python
import flyte.storage as storage
storage.put_stream(iter([b'hello']), name="my_file.txt")
OR
storage.put_stream(iter([b'hello']), to_path="s3://my_bucket/my_file.txt")
```

| Parameter | Type | Description |
|-|-|-|
| `data_iterable` | `typing.AsyncIterable[bytes] \| bytes` | Iterable of bytes to be streamed. |
| `name` | `str \| None` | Name of the file to be created. If not provided, a random name will be generated. |
| `to_path` | `str \| None` | Path to the remote location where the data will be stored. |
| `kwargs` | `**kwargs` | Additional arguments to be passed to the underlying filesystem. |

**Returns:** The path to the remote location where the data was stored.

## Subpages
- **Flyte SDK > Packages > flyte.storage > ABFS**
- **Flyte SDK > Packages > flyte.storage > GCS**
- **Flyte SDK > Packages > flyte.storage > S3**
- **Flyte SDK > Packages > flyte.storage > Storage**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.storage/abfs ===

# ABFS

**Package:** `flyte.storage`

Any Azure Blob Storage specific configuration.

## Parameters

```python
class ABFS(
    retries: int,
    backoff: datetime.timedelta,
    enable_debug: bool,
    attach_execution_metadata: bool,
    account_name: typing.Optional[str],
    account_key: typing.Optional[str],
    tenant_id: typing.Optional[str],
    client_id: typing.Optional[str],
    client_secret: typing.Optional[str],
)
```
| Parameter | Type | Description |
|-|-|-|
| `retries` | `int` | |
| `backoff` | `datetime.timedelta` | |
| `enable_debug` | `bool` | |
| `attach_execution_metadata` | `bool` | |
| `account_name` | `typing.Optional[str]` | |
| `account_key` | `typing.Optional[str]` | |
| `tenant_id` | `typing.Optional[str]` | |
| `client_id` | `typing.Optional[str]` | |
| `client_secret` | `typing.Optional[str]` | |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.storage > ABFS > Methods > auto()** | Construct the config object automatically from environment variables. |
| **Flyte SDK > Packages > flyte.storage > ABFS > Methods > get_fsspec_kwargs()** | Returns the configuration as kwargs for constructing an fsspec filesystem. |

### auto()

```python
def auto()
```
Construct the config object automatically from environment variables.

### get_fsspec_kwargs()

```python
def get_fsspec_kwargs(
    anonymous: bool,
    kwargs,
) -> typing.Dict[str, typing.Any]
```
Returns the configuration as kwargs for constructing an fsspec filesystem.

| Parameter | Type | Description |
|-|-|-|
| `anonymous` | `bool` | |
| `kwargs` | `**kwargs` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.storage/gcs ===

# GCS

**Package:** `flyte.storage`

Any GCS specific configuration.

## Parameters

```python
class GCS(
    retries: int,
    backoff: datetime.timedelta,
    enable_debug: bool,
    attach_execution_metadata: bool,
)
```
| Parameter | Type | Description |
|-|-|-|
| `retries` | `int` | |
| `backoff` | `datetime.timedelta` | |
| `enable_debug` | `bool` | |
| `attach_execution_metadata` | `bool` | |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.storage > GCS > Methods > auto()** | Construct the config object automatically from environment variables. |
| **Flyte SDK > Packages > flyte.storage > GCS > Methods > get_fsspec_kwargs()** | Returns the configuration as kwargs for constructing an fsspec filesystem. |

### auto()

```python
def auto()
```
Construct the config object automatically from environment variables.

### get_fsspec_kwargs()

```python
def get_fsspec_kwargs(
    anonymous: bool,
    kwargs,
) -> typing.Dict[str, typing.Any]
```
Returns the configuration as kwargs for constructing an fsspec filesystem.

| Parameter | Type | Description |
|-|-|-|
| `anonymous` | `bool` | |
| `kwargs` | `**kwargs` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.storage/s3 ===

# S3

**Package:** `flyte.storage`

S3 specific configuration.

Authentication resolution used by Flyte + obstore:

1. If explicit static credentials are provided via Flyte S3 inputs/environment
(`access_key_id`/`secret_access_key`), those are used.

2. If static credentials are not provided, and both `AWS_PROFILE` and
`AWS_CONFIG_FILE` are available, Flyte configures a boto3-backed obstore
credential provider so profile-based auth can be used. This requires that the `boto3` library
is installed.

3. If neither of the above applies, obstore uses the default AWS credential chain
(for remote runs this commonly resolves via workload identity / IAM attached to
the service account and then IMDS fallbacks where applicable).

## Parameters

```python
class S3(
    retries: int,
    backoff: datetime.timedelta,
    enable_debug: bool,
    attach_execution_metadata: bool,
    endpoint: typing.Optional[str],
    access_key_id: typing.Optional[str],
    secret_access_key: typing.Optional[str],
    region: typing.Optional[str],
    addressing_style: typing.Optional[str],
)
```
| Parameter | Type | Description |
|-|-|-|
| `retries` | `int` | |
| `backoff` | `datetime.timedelta` | |
| `enable_debug` | `bool` | |
| `attach_execution_metadata` | `bool` | |
| `endpoint` | `typing.Optional[str]` | |
| `access_key_id` | `typing.Optional[str]` | |
| `secret_access_key` | `typing.Optional[str]` | |
| `region` | `typing.Optional[str]` | |
| `addressing_style` | `typing.Optional[str]` | |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.storage > S3 > Methods > auto()** |  |
| **Flyte SDK > Packages > flyte.storage > S3 > Methods > for_sandbox()** |  |
| **Flyte SDK > Packages > flyte.storage > S3 > Methods > get_fsspec_kwargs()** | Returns the configuration as kwargs for constructing an fsspec filesystem. |

### auto()

```python
def auto(
    region: str | None,
) -> S3
```
| Parameter | Type | Description |
|-|-|-|
| `region` | `str \| None` | |

**Returns:** Config

### for_sandbox()

```python
def for_sandbox()
```
### get_fsspec_kwargs()

```python
def get_fsspec_kwargs(
    anonymous: bool,
    kwargs,
) -> typing.Dict[str, typing.Any]
```
Returns the configuration as kwargs for constructing an fsspec filesystem.

| Parameter | Type | Description |
|-|-|-|
| `anonymous` | `bool` | |
| `kwargs` | `**kwargs` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.storage/storage ===

# Storage

**Package:** `flyte.storage`

Data storage configuration that applies across any provider.

## Parameters

```python
class Storage(
    retries: int,
    backoff: datetime.timedelta,
    enable_debug: bool,
    attach_execution_metadata: bool,
)
```
| Parameter | Type | Description |
|-|-|-|
| `retries` | `int` | |
| `backoff` | `datetime.timedelta` | |
| `enable_debug` | `bool` | |
| `attach_execution_metadata` | `bool` | |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.storage > Storage > Methods > auto()** | Construct the config object automatically from environment variables. |
| **Flyte SDK > Packages > flyte.storage > Storage > Methods > get_fsspec_kwargs()** | Returns the configuration as kwargs for constructing an fsspec filesystem. |

### auto()

```python
def auto()
```
Construct the config object automatically from environment variables.

### get_fsspec_kwargs()

```python
def get_fsspec_kwargs(
    anonymous: bool,
    kwargs,
) -> typing.Dict[str, typing.Any]
```
Returns the configuration as kwargs for constructing an fsspec filesystem.

| Parameter | Type | Description |
|-|-|-|
| `anonymous` | `bool` | |
| `kwargs` | `**kwargs` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.syncify ===

# flyte.syncify

# Syncify Module
This module provides the `syncify` decorator and the `Syncify` class.
The decorator can be used to convert asynchronous functions or methods into synchronous ones.
This is useful for integrating async code into synchronous contexts.

Every asynchronous function or method wrapped with `syncify` can be called synchronously using the
parenthesis `()` operator, or asynchronously using the `.aio()` method.

Example:

```python
from flyte.syncify import syncify

@syncify
async def async_function(x: str) -> str:
    return f"Hello, Async World {x}!"

# now you can call it synchronously
result = async_function("Async World")   # Note: no .aio() needed for sync calls
print(result)
# Output: Hello, Async World Async World!

# or call it asynchronously
async def main():
    result = await async_function.aio("World")    # Note the use of .aio() for async calls
    print(result)
```

## Creating a Syncify Instance
```python
from flyte.syncify. import Syncify

syncer = Syncify("my_syncer")

# Now you can use `syncer` to decorate your async functions or methods

```

## How does it work?
The Syncify class wraps asynchronous functions, classmethods, instance methods, and static methods to
 provide a synchronous interface. The wrapped methods are always executed in the context of a background loop,
 whether they are called synchronously or asynchronously. This allows for seamless integration of async code, as
 certain async libraries capture the event loop. In such a case, the Syncify class ensures that the async
 function is executed in the context of the background loop.

To use it correctly, you should wrap every async client creation and invocation with the same `Syncify`
instance. This ensures that the async code runs in the correct event loop context.
## Directory

### Classes

| Class | Description |
|-|-|
| [`Syncify`](syncify/page.md) | A decorator to convert asynchronous functions or methods into synchronous ones. |

## Subpages
- **Flyte SDK > Packages > flyte.syncify > Syncify**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.syncify/syncify ===

# Syncify

**Package:** `flyte.syncify`

A decorator to convert asynchronous functions or methods into synchronous ones.

This is useful for integrating async code into synchronous contexts.

```python
syncer = Syncify()

@syncer
async def async_function(x: str) -> str:
    return f"Hello, Async World {x}!"

# now you can call it synchronously
result = async_function("Async World")
print(result)
# Output: Hello, Async World Async World!

# or call it asynchronously
async def main():
    result = await async_function.aio("World")
    print(result)
```

## Parameters

```python
class Syncify(
    name: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.types ===

# flyte.types

# Flyte Type System

The Flyte type system provides a way to define, transform, and manipulate types in Flyte workflows.
Since the data flowing through Flyte has to often cross process, container and langauge boundaries, the type system
is designed to be serializable to a universal format that can be understood across different environments. This
universal format is based on Protocol Buffers. The types are called LiteralTypes and the runtime
representation of data is called Literals.

The type system includes:
- **TypeEngine**: The core engine that manages type transformations and serialization. This is the main entry point for
  for all the internal type transformations and serialization logic.
- **TypeTransformer**: A class that defines how to transform one type to another. This is extensible
    allowing users to define custom types and transformations.
- **Renderable**: An interface for types that can be rendered as HTML, that can be outputted to a flyte.report.

It is always possible to bypass the type system and use the `FlytePickle` type to serialize any python object
 into a pickle format. The pickle format is not human-readable, but can be passed between flyte tasks that are
 written in python. The Pickled objects cannot be represented in the UI, and may be in-efficient for large datasets.
## Directory

### Classes

| Class | Description |
|-|-|
| **Flyte SDK > Packages > flyte.types > FlytePickle** | This type is only used by flytekit internally. |
| **Flyte SDK > Packages > flyte.types > TypeEngine** | Core Extensible TypeEngine of Flytekit. |
| **Flyte SDK > Packages > flyte.types > TypeTransformer** | Base transformer type that should be implemented for every python native type that can be handled by flytekit. |

### Protocols

| Protocol | Description |
|-|-|
| **Flyte SDK > Packages > flyte.types > Renderable** |  |

### Errors

| Exception | Description |
|-|-|
| **Flyte SDK > Packages > flyte.types > TypeTransformerFailedError** |  |

### Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.types > Methods > guess_interface()** | Returns the interface of the task with guessed types, as types may not be present in current env. |
| **Flyte SDK > Packages > flyte.types > Methods > literal_string_repr()** | This method is used to convert a literal map to a string representation. |

## Methods

#### guess_interface()

```python
def guess_interface(
    interface: flyteidl2.core.interface_pb2.TypedInterface,
    default_inputs: typing.Optional[typing.Iterable[flyteidl2.task.common_pb2.NamedParameter]],
) -> flyte.models.NativeInterface
```
Returns the interface of the task with guessed types, as types may not be present in current env.

| Parameter | Type | Description |
|-|-|-|
| `interface` | `flyteidl2.core.interface_pb2.TypedInterface` | |
| `default_inputs` | `typing.Optional[typing.Iterable[flyteidl2.task.common_pb2.NamedParameter]]` | |

#### literal_string_repr()

```python
def literal_string_repr(
    lm: typing.Union[flyteidl2.core.literals_pb2.Literal, flyteidl2.task.common_pb2.NamedLiteral, flyteidl2.task.common_pb2.Inputs, flyteidl2.task.common_pb2.Outputs, flyteidl2.core.literals_pb2.LiteralMap, typing.Dict[str, flyteidl2.core.literals_pb2.Literal]],
) -> typing.Dict[str, typing.Any]
```
This method is used to convert a literal map to a string representation.

| Parameter | Type | Description |
|-|-|-|
| `lm` | `typing.Union[flyteidl2.core.literals_pb2.Literal, flyteidl2.task.common_pb2.NamedLiteral, flyteidl2.task.common_pb2.Inputs, flyteidl2.task.common_pb2.Outputs, flyteidl2.core.literals_pb2.LiteralMap, typing.Dict[str, flyteidl2.core.literals_pb2.Literal]]` | |

## Subpages
- **Flyte SDK > Packages > flyte.types > FlytePickle**
- **Flyte SDK > Packages > flyte.types > Renderable**
- **Flyte SDK > Packages > flyte.types > TypeEngine**
- **Flyte SDK > Packages > flyte.types > TypeTransformer**
- **Flyte SDK > Packages > flyte.types > TypeTransformerFailedError**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.types/flytepickle ===

# FlytePickle

**Package:** `flyte.types`

This type is only used by flytekit internally. User should not use this type.
Any type that flyte can't recognize will become FlytePickle

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.types > FlytePickle > Methods > from_pickle()** |  |
| **Flyte SDK > Packages > flyte.types > FlytePickle > Methods > python_type()** |  |
| **Flyte SDK > Packages > flyte.types > FlytePickle > Methods > to_pickle()** |  |

### from_pickle()

```python
def from_pickle(
    uri: str,
) -> typing.Any
```
| Parameter | Type | Description |
|-|-|-|
| `uri` | `str` | |

### python_type()

```python
def python_type()
```
### to_pickle()

```python
def to_pickle(
    python_val: typing.Any,
) -> str
```
| Parameter | Type | Description |
|-|-|-|
| `python_val` | `typing.Any` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.types/renderable ===

# Renderable

**Package:** `flyte.types`

```python
protocol Renderable()
```
## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.types > Renderable > Methods > to_html()** | Convert an object(markdown, pandas. |

### to_html()

```python
def to_html(
    python_value: typing.Any,
) -> str
```
Convert an object(markdown, pandas.dataframe) to HTML and return HTML as a unicode string.
Returns: An HTML document as a string.

| Parameter | Type | Description |
|-|-|-|
| `python_value` | `typing.Any` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.types/typeengine ===

# TypeEngine

**Package:** `flyte.types`

Core Extensible TypeEngine of Flytekit. This should be used to extend the capabilities of FlyteKits type system.
Users can implement their own TypeTransformers and register them with the TypeEngine. This will allow special
 handling
of user objects

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.types > TypeEngine > Methods > dict_to_literal_map()** | Given a dictionary mapping string keys to python values and a dictionary containing guessed types for such. |
| **Flyte SDK > Packages > flyte.types > TypeEngine > Methods > get_available_transformers()** | Returns all python types for which transformers are available. |
| **Flyte SDK > Packages > flyte.types > TypeEngine > Methods > get_transformer()** | Implements a recursive search for the transformer. |
| **Flyte SDK > Packages > flyte.types > TypeEngine > Methods > guess_python_type()** | Transforms a flyte-specific `LiteralType` to a regular python value. |
| **Flyte SDK > Packages > flyte.types > TypeEngine > Methods > guess_python_types()** | Transforms a list of flyte-specific `VariableEntry` objects to a dictionary of regular python values. |
| **Flyte SDK > Packages > flyte.types > TypeEngine > Methods > lazy_import_transformers()** | Only load the transformers if needed. |
| **Flyte SDK > Packages > flyte.types > TypeEngine > Methods > literal_map_to_kwargs()** | Given a `LiteralMap` (usually an input into a task - intermediate), convert to kwargs for the task. |
| **Flyte SDK > Packages > flyte.types > TypeEngine > Methods > named_tuple_to_variable_map()** | Converts a python-native `NamedTuple` to a flyte-specific VariableMap of named literals. |
| **Flyte SDK > Packages > flyte.types > TypeEngine > Methods > register()** | This should be used for all types that respond with the right type annotation when you use type(. |
| **Flyte SDK > Packages > flyte.types > TypeEngine > Methods > register_additional_type()** |  |
| **Flyte SDK > Packages > flyte.types > TypeEngine > Methods > register_restricted_type()** |  |
| **Flyte SDK > Packages > flyte.types > TypeEngine > Methods > to_html()** |  |
| **Flyte SDK > Packages > flyte.types > TypeEngine > Methods > to_literal()** |  |
| **Flyte SDK > Packages > flyte.types > TypeEngine > Methods > to_literal_checks()** |  |
| **Flyte SDK > Packages > flyte.types > TypeEngine > Methods > to_literal_type()** | Converts a python type into a flyte specific `LiteralType`. |
| **Flyte SDK > Packages > flyte.types > TypeEngine > Methods > to_python_value()** | Converts a Literal value with an expected python type into a python value. |
| **Flyte SDK > Packages > flyte.types > TypeEngine > Methods > unwrap_offloaded_literal()** |  |

### dict_to_literal_map()

```python
def dict_to_literal_map(
    d: typing.Dict[str, typing.Any],
    type_hints: Optional[typing.Dict[str, type]],
) -> LiteralMap
```
Given a dictionary mapping string keys to python values and a dictionary containing guessed types for such
string keys,
convert to a LiteralMap.

| Parameter | Type | Description |
|-|-|-|
| `d` | `typing.Dict[str, typing.Any]` | |
| `type_hints` | `Optional[typing.Dict[str, type]]` | |

### get_available_transformers()

```python
def get_available_transformers()
```
Returns all python types for which transformers are available

### get_transformer()

```python
def get_transformer(
    python_type: Type,
) -> TypeTransformer
```
Implements a recursive search for the transformer.

| Parameter | Type | Description |
|-|-|-|
| `python_type` | `Type` | |

### guess_python_type()

```python
def guess_python_type(
    flyte_type: LiteralType,
) -> Type[T]
```
Transforms a flyte-specific `LiteralType` to a regular python value.

| Parameter | Type | Description |
|-|-|-|
| `flyte_type` | `LiteralType` | |

### guess_python_types()

```python
def guess_python_types(
    flyte_variable_list: typing.List[interface_pb2.VariableEntry],
) -> typing.Dict[str, Type[Any]]
```
Transforms a list of flyte-specific `VariableEntry` objects to a dictionary of regular python values.

| Parameter | Type | Description |
|-|-|-|
| `flyte_variable_list` | `typing.List[interface_pb2.VariableEntry]` | |

### lazy_import_transformers()

```python
def lazy_import_transformers()
```
Only load the transformers if needed.

### literal_map_to_kwargs()

```python
def literal_map_to_kwargs(
    lm: LiteralMap,
    python_types: typing.Optional[typing.Dict[str, type]],
    literal_types: typing.Optional[typing.Dict[str, interface_pb2.Variable]],
) -> typing.Dict[str, typing.Any]
```
Given a `LiteralMap` (usually an input into a task - intermediate), convert to kwargs for the task

| Parameter | Type | Description |
|-|-|-|
| `lm` | `LiteralMap` | |
| `python_types` | `typing.Optional[typing.Dict[str, type]]` | |
| `literal_types` | `typing.Optional[typing.Dict[str, interface_pb2.Variable]]` | |

### named_tuple_to_variable_map()

```python
def named_tuple_to_variable_map(
    t: typing.NamedTuple,
) -> interface_pb2.VariableMap
```
Converts a python-native `NamedTuple` to a flyte-specific VariableMap of named literals.

| Parameter | Type | Description |
|-|-|-|
| `t` | `typing.NamedTuple` | |

### register()

```python
def register(
    transformer: TypeTransformer,
    additional_types: Optional[typing.List[Type]],
)
```
This should be used for all types that respond with the right type annotation when you use type(...) function

| Parameter | Type | Description |
|-|-|-|
| `transformer` | `TypeTransformer` | |
| `additional_types` | `Optional[typing.List[Type]]` | |

### register_additional_type()

```python
def register_additional_type(
    transformer: TypeTransformer[T],
    additional_type: Type[T],
    override,
)
```
| Parameter | Type | Description |
|-|-|-|
| `transformer` | `TypeTransformer[T]` | |
| `additional_type` | `Type[T]` | |
| `override` |  | |

### register_restricted_type()

```python
def register_restricted_type(
    name: str,
    type: Type[T],
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |
| `type` | `Type[T]` | |

### to_html()

```python
def to_html(
    python_val: typing.Any,
    expected_python_type: Type[typing.Any],
) -> str
```
| Parameter | Type | Description |
|-|-|-|
| `python_val` | `typing.Any` | |
| `expected_python_type` | `Type[typing.Any]` | |

### to_literal()

```python
def to_literal(
    python_val: typing.Any,
    python_type: Type[T],
    expected: types_pb2.LiteralType,
) -> literals_pb2.Literal
```
| Parameter | Type | Description |
|-|-|-|
| `python_val` | `typing.Any` | |
| `python_type` | `Type[T]` | |
| `expected` | `types_pb2.LiteralType` | |

### to_literal_checks()

```python
def to_literal_checks(
    python_val: typing.Any,
    python_type: Type[T],
    expected: LiteralType,
)
```
| Parameter | Type | Description |
|-|-|-|
| `python_val` | `typing.Any` | |
| `python_type` | `Type[T]` | |
| `expected` | `LiteralType` | |

### to_literal_type()

```python
def to_literal_type(
    python_type: Type[T],
) -> LiteralType
```
Converts a python type into a flyte specific `LiteralType`

| Parameter | Type | Description |
|-|-|-|
| `python_type` | `Type[T]` | |

### to_python_value()

```python
def to_python_value(
    lv: Literal,
    expected_python_type: Type,
) -> typing.Any
```
Converts a Literal value with an expected python type into a python value.

| Parameter | Type | Description |
|-|-|-|
| `lv` | `Literal` | |
| `expected_python_type` | `Type` | |

### unwrap_offloaded_literal()

```python
def unwrap_offloaded_literal(
    lv: literals_pb2.Literal,
) -> literals_pb2.Literal
```
| Parameter | Type | Description |
|-|-|-|
| `lv` | `literals_pb2.Literal` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.types/typetransformer ===

# TypeTransformer

**Package:** `flyte.types`

Base transformer type that should be implemented for every python native type that can be handled by flytekit

## Parameters

```python
class TypeTransformer(
    name: str,
    t: Type[T],
    enable_type_assertions: bool,
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |
| `t` | `Type[T]` | |
| `enable_type_assertions` | `bool` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `name` | `None` |  |
| `python_type` | `None` | This returns the python type |
| `type_assertions_enabled` | `None` | Indicates if the transformer wants type assertions to be enabled at the core type engine layer |

## Methods

| Method | Description |
|-|-|
| **Flyte SDK > Packages > flyte.types > TypeTransformer > Methods > assert_type()** |  |
| **Flyte SDK > Packages > flyte.types > TypeTransformer > Methods > from_binary_idl()** | This function primarily handles deserialization for untyped dicts, dataclasses, Pydantic BaseModels, and. |
| **Flyte SDK > Packages > flyte.types > TypeTransformer > Methods > get_literal_type()** | Converts the python type to a Flyte LiteralType. |
| **Flyte SDK > Packages > flyte.types > TypeTransformer > Methods > guess_python_type()** | Converts the Flyte LiteralType to a python object type. |
| **Flyte SDK > Packages > flyte.types > TypeTransformer > Methods > isinstance_generic()** |  |
| **Flyte SDK > Packages > flyte.types > TypeTransformer > Methods > schema_match()** | Check if a JSON schema fragment matches this transformer's python_type. |
| **Flyte SDK > Packages > flyte.types > TypeTransformer > Methods > to_html()** | Converts any python val (dataframe, int, float) to a html string, and it will be wrapped in the HTML div. |
| **Flyte SDK > Packages > flyte.types > TypeTransformer > Methods > to_literal()** | Converts a given python_val to a Flyte Literal, assuming the given python_val matches the declared python_type. |
| **Flyte SDK > Packages > flyte.types > TypeTransformer > Methods > to_python_value()** | Converts the given Literal to a Python Type. |

### assert_type()

```python
def assert_type(
    t: Type[T],
    v: T,
)
```
| Parameter | Type | Description |
|-|-|-|
| `t` | `Type[T]` | |
| `v` | `T` | |

### from_binary_idl()

```python
def from_binary_idl(
    binary_idl_object: Binary,
    expected_python_type: Type[T],
) -> Optional[T]
```
This function primarily handles deserialization for untyped dicts, dataclasses, Pydantic BaseModels, and
 attribute access.

For untyped dict, dataclass, and pydantic basemodel:
Life Cycle (Untyped Dict as example):
    python val -&gt; msgpack bytes -&gt; binary literal scalar -&gt; msgpack bytes -&gt; python val
                  (to_literal)                             (from_binary_idl)

For attribute access:
Life Cycle:
    python val -&gt; msgpack bytes -&gt; binary literal scalar -&gt; resolved golang value -&gt; binary literal scalar
     -&gt; msgpack bytes -&gt; python val
                  (to_literal)      (propeller attribute access)     (from_binary_idl)

| Parameter | Type | Description |
|-|-|-|
| `binary_idl_object` | `Binary` | |
| `expected_python_type` | `Type[T]` | |

### get_literal_type()

```python
def get_literal_type(
    t: Type[T],
) -> LiteralType
```
Converts the python type to a Flyte LiteralType

| Parameter | Type | Description |
|-|-|-|
| `t` | `Type[T]` | |

### guess_python_type()

```python
def guess_python_type(
    literal_type: LiteralType,
) -> Type[T]
```
Converts the Flyte LiteralType to a python object type.

| Parameter | Type | Description |
|-|-|-|
| `literal_type` | `LiteralType` | |

### isinstance_generic()

```python
def isinstance_generic(
    obj,
    generic_alias,
)
```
| Parameter | Type | Description |
|-|-|-|
| `obj` |  | |
| `generic_alias` |  | |

### schema_match()

```python
def schema_match(
    schema: dict,
) -> bool
```
Check if a JSON schema fragment matches this transformer's python_type.

For BaseModel subclasses, automatically compares the schema's title, type, and
required fields against the type's own JSON schema. For other types, returns
False by default — override if needed.

| Parameter | Type | Description |
|-|-|-|
| `schema` | `dict` | |

### to_html()

```python
def to_html(
    python_val: T,
    expected_python_type: Type[T],
) -> str
```
Converts any python val (dataframe, int, float) to a html string, and it will be wrapped in the HTML div

| Parameter | Type | Description |
|-|-|-|
| `python_val` | `T` | |
| `expected_python_type` | `Type[T]` | |

### to_literal()

```python
def to_literal(
    python_val: T,
    python_type: Type[T],
    expected: LiteralType,
) -> Literal
```
Converts a given python_val to a Flyte Literal, assuming the given python_val matches the declared python_type.
Implementers should refrain from using type(python_val) instead rely on the passed in python_type. If these
do not match (or are not allowed) the Transformer implementer should raise an AssertionError, clearly stating
what was the mismatch

| Parameter | Type | Description |
|-|-|-|
| `python_val` | `T` | The actual value to be transformed |
| `python_type` | `Type[T]` | The assumed type of the value (this matches the declared type on the function) |
| `expected` | `LiteralType` | Expected Literal Type |

### to_python_value()

```python
def to_python_value(
    lv: Literal,
    expected_python_type: Type[T],
) -> Optional[T]
```
Converts the given Literal to a Python Type. If the conversion cannot be done an AssertionError should be raised

| Parameter | Type | Description |
|-|-|-|
| `lv` | `Literal` | The received literal Value |
| `expected_python_type` | `Type[T]` | Expected native python type that should be returned |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/packages/flyte.types/typetransformerfailederror ===

# TypeTransformerFailedError

**Package:** `flyte.types`


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations ===

# Integrations

API reference for Flyte integration plugins.

## Subpages
- **Integrations > Anthropic**
- **Integrations > BigQuery**
- **Integrations > Code generation**
- **Integrations > Dask**
- **Integrations > Databricks**
- **Integrations > Gemini**
- **Integrations > Human-in-the-Loop**
- **Integrations > JSONL**
- **Integrations > MLflow**
- **Integrations > OpenAI**
- **Integrations > Polars**
- **Integrations > PyTorch**
- **Integrations > Ray**
- **Integrations > SGLang**
- **Integrations > Snowflake**
- **Integrations > Spark**
- **Integrations > Union**
- **Integrations > vLLM**
- **Integrations > Weights & Biases**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/anthropic ===

# Anthropic

## Subpages
- **Integrations > Anthropic > Classes**
- **Integrations > Anthropic > Packages**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/anthropic/classes ===

# Classes

| Class | Description |
|-|-|
| **Integrations > Anthropic > Packages > flyteplugins.anthropic > Agent** |A Claude agent configuration. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/anthropic/packages ===

# Packages

| Package | Description |
|-|-|
| **Integrations > Anthropic > Packages > flyteplugins.anthropic** | Anthropic Claude plugin for Flyte. |

## Subpages
- **Integrations > Anthropic > Packages > flyteplugins.anthropic**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/anthropic/packages/flyteplugins.anthropic ===

# flyteplugins.anthropic

Anthropic Claude plugin for Flyte.

This plugin provides integration between Flyte tasks and Anthropic's Claude API,
enabling you to use Flyte tasks as tools for Claude agents. Tool calls run with
full Flyte observability, retries, and caching.

Key features:

- Use any Flyte task as a Claude tool via `function_tool`
- Full agent loop with automatic tool dispatch via `run_agent`
- Configurable agent via `Agent` (model, system prompt, tools, iteration limits)

Basic usage example:

```python
import flyte
from flyteplugins.anthropic import Agent, function_tool, run_agent

env = flyte.TaskEnvironment(
    name="agent_env",
    image=flyte.Image.from_debian_base(name="agent").with_pip_packages(
        "flyteplugins-anthropic"
    ),
)

@env.task
async def get_weather(city: str) -> str:
    '''Get the current weather for a city.'''
    return f"Weather in {city}: sunny, 22°C"

weather_tool = function_tool(get_weather)

@env.task
async def run_weather_agent(question: str) -> str:
    return await run_agent(
        prompt=question,
        tools=[weather_tool],
        model="claude-sonnet-4-20250514",
    )
```
## Directory

### Classes

| Class | Description |
|-|-|
| **Integrations > Anthropic > Packages > flyteplugins.anthropic > Agent** | A Claude agent configuration. |

### Methods

| Method | Description |
|-|-|
| **Integrations > Anthropic > Packages > flyteplugins.anthropic > Methods > function_tool()** | Convert a function or Flyte task to an Anthropic-compatible tool. |
| **Integrations > Anthropic > Packages > flyteplugins.anthropic > Methods > run_agent()** | Run a Claude agent with the given tools and prompt. |

## Methods

#### function_tool()

```python
def function_tool(
    func: typing.Union[flyte._task.AsyncFunctionTaskTemplate, typing.Callable, NoneType],
    name: str | None,
    description: str | None,
) -> FunctionTool | partial[FunctionTool]
```
Convert a function or Flyte task to an Anthropic-compatible tool.

This function converts a Python function, @flyte.trace decorated function,
or Flyte task into a FunctionTool that can be used with Claude's tool use API.

The input_schema is derived via the Flyte type engine, producing JSON schema
This ensures that Literal types, dataclasses, FlyteFile, and other Flyte-native
types are represented correctly.

For @flyte.trace decorated functions, the tracing context is preserved
automatically since functools.wraps maintains the original function's metadata.

| Parameter | Type | Description |
|-|-|-|
| `func` | `typing.Union[flyte._task.AsyncFunctionTaskTemplate, typing.Callable, NoneType]` | The function or Flyte task to convert. |
| `name` | `str \| None` | Optional custom name for the tool. Defaults to the function name. |
| `description` | `str \| None` | Optional custom description. Defaults to the function's docstring. |

**Returns**

A FunctionTool instance that can be used with run_agent().

#### run_agent()

```python
def run_agent(
    prompt: str,
    tools: list[flyteplugins.anthropic.agents._function_tools.FunctionTool] | None,
    agent: flyteplugins.anthropic.agents._function_tools.Agent | None,
    model: str,
    system: str | None,
    max_tokens: int,
    max_iterations: int,
    api_key: str | None,
) -> str
```
Run a Claude agent with the given tools and prompt.

This function creates a Claude conversation loop that can use tools
to accomplish tasks. It handles the back-and-forth of tool calls
and responses until the agent produces a final text response.

| Parameter | Type | Description |
|-|-|-|
| `prompt` | `str` | The user prompt to send to the agent. |
| `tools` | `list[flyteplugins.anthropic.agents._function_tools.FunctionTool] \| None` | List of FunctionTool instances to make available to the agent. |
| `agent` | `flyteplugins.anthropic.agents._function_tools.Agent \| None` | Optional Agent configuration. If provided, overrides other params. |
| `model` | `str` | The Claude model to use. |
| `system` | `str \| None` | Optional system prompt. |
| `max_tokens` | `int` | Maximum tokens in the response. |
| `max_iterations` | `int` | Maximum number of tool call iterations. |
| `api_key` | `str \| None` | Anthropic API key. Defaults to ANTHROPIC_API_KEY env var. |

**Returns**

The final text response from the agent.

## Subpages
- **Integrations > Anthropic > Packages > flyteplugins.anthropic > Agent**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/anthropic/packages/flyteplugins.anthropic/agent ===

# Agent

**Package:** `flyteplugins.anthropic`

A Claude agent configuration.

This class represents the configuration for a Claude agent, including
the model to use, system instructions, and available tools.

## Parameters

```python
class Agent(
    name: str,
    instructions: str,
    model: str,
    tools: list[flyteplugins.anthropic.agents._function_tools.FunctionTool],
    max_tokens: int,
    max_iterations: int,
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | A human-readable name for this agent. Used for logging and identification only; not sent to the API. |
| `instructions` | `str` | The system prompt passed to Claude on every turn. Describes the agent's role, tone, and constraints. |
| `model` | `str` | The Claude model ID to use, e.g. `"claude-sonnet-4-20250514"`. |
| `tools` | `list[flyteplugins.anthropic.agents._function_tools.FunctionTool]` | List of `FunctionTool` instances the agent can invoke. Create tools with `function_tool()`. |
| `max_tokens` | `int` | Maximum number of tokens in each Claude response. |
| `max_iterations` | `int` | Maximum number of tool-call / response cycles before `run_agent` returns with a timeout message. |

## Methods

| Method | Description |
|-|-|
| **Integrations > Anthropic > Packages > flyteplugins.anthropic > Agent > Methods > get_anthropic_tools()** | Get tool definitions in Anthropic format. |

### get_anthropic_tools()

```python
def get_anthropic_tools()
```
Get tool definitions in Anthropic format.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/bigquery ===

# BigQuery

## Subpages
- **Integrations > BigQuery > Classes**
- **Integrations > BigQuery > Packages**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/bigquery/classes ===

# Classes

| Class | Description |
|-|-|
| **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryConfig** |Configuration for a BigQuery task. |
| **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryConnector** | |
| **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryTask** | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/bigquery/packages ===

# Packages

| Package | Description |
|-|-|
| **Integrations > BigQuery > Packages > flyteplugins.bigquery** | BigQuery connector plugin for Flyte. |

## Subpages
- **Integrations > BigQuery > Packages > flyteplugins.bigquery**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/bigquery/packages/flyteplugins.bigquery ===

# flyteplugins.bigquery

BigQuery connector plugin for Flyte.

This plugin provides integration between Flyte tasks and Google BigQuery,
enabling you to run parameterized SQL queries as Flyte tasks with full
observability, retries, and caching.

Key features:

- Parameterized SQL queries with typed inputs
- Returns query results as DataFrames
- Automatic links to the BigQuery job console in the Flyte UI
- Query cancellation on task abort

Basic usage example:

```python
import flyte
from flyte.io import DataFrame
from flyteplugins.bigquery import BigQueryConfig, BigQueryTask

config = BigQueryConfig(
    ProjectID="my-gcp-project",
    Location="US",
)

query_task = BigQueryTask(
    name="count_events",
    query_template="SELECT COUNT(*) AS total FROM `{ds}.events` WHERE date = @date",
    plugin_config=config,
    inputs={"date": str},
    output_dataframe_type=DataFrame[dict],
)

@flyte.task
def run_query(date: str) -> DataFrame[dict]:
    return query_task(date=date)
```
## Directory

### Classes

| Class | Description |
|-|-|
| [`BigQueryConfig`](bigqueryconfig/page.md) | Configuration for a BigQuery task. |
| [`BigQueryConnector`](bigqueryconnector/page.md) |  |
| [`BigQueryTask`](bigquerytask/page.md) |  |

## Subpages
- **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryConfig**
- **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryConnector**
- **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryTask**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/bigquery/packages/flyteplugins.bigquery/bigqueryconfig ===

# BigQueryConfig

**Package:** `flyteplugins.bigquery`

Configuration for a BigQuery task.

## Parameters

```python
class BigQueryConfig(
    ProjectID: str,
    Location: typing.Optional[str],
    QueryJobConfig: typing.Optional[google.cloud.bigquery.job.query.QueryJobConfig],
)
```
| Parameter | Type | Description |
|-|-|-|
| `ProjectID` | `str` | The Google Cloud project ID that owns the BigQuery dataset. |
| `Location` | `typing.Optional[str]` | The geographic location of the dataset, e.g. `"US"` or `"EU"`. Defaults to the project's default location if not specified. |
| `QueryJobConfig` | `typing.Optional[google.cloud.bigquery.job.query.QueryJobConfig]` | Optional advanced job configuration passed directly to the BigQuery client. Use this to set query parameters, destination tables, time partitioning, etc. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/bigquery/packages/flyteplugins.bigquery/bigqueryconnector ===

# BigQueryConnector

**Package:** `flyteplugins.bigquery`

## Methods

| Method | Description |
|-|-|
| **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryConnector > Methods > create()** | Return a resource meta that can be used to get the status of the task. |
| **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryConnector > Methods > delete()** | Delete the task. |
| **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryConnector > Methods > get()** | Return the status of the task, and return the outputs in some cases. |
| **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryConnector > Methods > get_logs()** | Return the metrics for the task. |
| **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryConnector > Methods > get_metrics()** | Return the metrics for the task. |

### create()

```python
def create(
    task_template: flyteidl2.core.tasks_pb2.TaskTemplate,
    inputs: typing.Optional[typing.Dict[str, typing.Any]],
    google_application_credentials: typing.Optional[str],
    kwargs,
) -> flyteplugins.bigquery.connector.BigQueryMetadata
```
Return a resource meta that can be used to get the status of the task.

| Parameter | Type | Description |
|-|-|-|
| `task_template` | `flyteidl2.core.tasks_pb2.TaskTemplate` | |
| `inputs` | `typing.Optional[typing.Dict[str, typing.Any]]` | |
| `google_application_credentials` | `typing.Optional[str]` | |
| `kwargs` | `**kwargs` | |

### delete()

```python
def delete(
    resource_meta: flyteplugins.bigquery.connector.BigQueryMetadata,
    google_application_credentials: typing.Optional[str],
    kwargs,
)
```
Delete the task. This call should be idempotent. It should raise an error if fails to delete the task.

| Parameter | Type | Description |
|-|-|-|
| `resource_meta` | `flyteplugins.bigquery.connector.BigQueryMetadata` | |
| `google_application_credentials` | `typing.Optional[str]` | |
| `kwargs` | `**kwargs` | |

### get()

```python
def get(
    resource_meta: flyteplugins.bigquery.connector.BigQueryMetadata,
    google_application_credentials: typing.Optional[str],
    kwargs,
) -> flyte.connectors._connector.Resource
```
Return the status of the task, and return the outputs in some cases. For example, bigquery job
can't write the structured dataset to the output location, so it returns the output literals to the propeller,
and the propeller will write the structured dataset to the blob store.

| Parameter | Type | Description |
|-|-|-|
| `resource_meta` | `flyteplugins.bigquery.connector.BigQueryMetadata` | |
| `google_application_credentials` | `typing.Optional[str]` | |
| `kwargs` | `**kwargs` | |

### get_logs()

```python
def get_logs(
    resource_meta: flyte.connectors._connector.ResourceMeta,
    kwargs,
) -> flyteidl2.connector.connector_pb2.GetTaskLogsResponse
```
Return the metrics for the task.

| Parameter | Type | Description |
|-|-|-|
| `resource_meta` | `flyte.connectors._connector.ResourceMeta` | |
| `kwargs` | `**kwargs` | |

### get_metrics()

```python
def get_metrics(
    resource_meta: flyte.connectors._connector.ResourceMeta,
    kwargs,
) -> flyteidl2.connector.connector_pb2.GetTaskMetricsResponse
```
Return the metrics for the task.

| Parameter | Type | Description |
|-|-|-|
| `resource_meta` | `flyte.connectors._connector.ResourceMeta` | |
| `kwargs` | `**kwargs` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/bigquery/packages/flyteplugins.bigquery/bigquerytask ===

# BigQueryTask

**Package:** `flyteplugins.bigquery`

## Parameters

```python
class BigQueryTask(
    name: str,
    query_template: str,
    plugin_config: flyteplugins.bigquery.task.BigQueryConfig,
    inputs: typing.Optional[typing.Dict[str, typing.Type]],
    output_dataframe_type: typing.Optional[typing.Type[flyte.io._dataframe.dataframe.DataFrame]],
    google_application_credentials: typing.Optional[str],
    kwargs,
)
```
To be used to query BigQuery Tables.

| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | The Name of this task, should be unique in the project |
| `query_template` | `str` | The actual query to run. We use Flyte's Golang templating format for Query templating. Refer to the templating documentation |
| `plugin_config` | `flyteplugins.bigquery.task.BigQueryConfig` | BigQueryConfig object |
| `inputs` | `typing.Optional[typing.Dict[str, typing.Type]]` | Name and type of inputs specified as an ordered dictionary |
| `output_dataframe_type` | `typing.Optional[typing.Type[flyte.io._dataframe.dataframe.DataFrame]]` | If some data is produced by this query, then you can specify the output dataframe type. |
| `google_application_credentials` | `typing.Optional[str]` | The name of the secret containing the Google Application Credentials. |
| `kwargs` | `**kwargs` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `native_interface` | `None` |  |
| `source_file` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryTask > Methods > aio()** | The aio function allows executing "sync" tasks, in an async context. |
| **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryTask > Methods > config()** | Returns additional configuration for the task. |
| **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryTask > Methods > container_args()** | Returns the container args for the task. |
| **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryTask > Methods > custom_config()** | Returns additional configuration for the task. |
| **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryTask > Methods > data_loading_config()** | This configuration allows executing raw containers in Flyte using the Flyte CoPilot system. |
| **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryTask > Methods > execute()** |  |
| **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryTask > Methods > forward()** | Think of this as a local execute method for your task. |
| **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryTask > Methods > override()** | Override various parameters of the task template. |
| **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryTask > Methods > post()** | This is the postexecute function that will be. |
| **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryTask > Methods > pre()** | This is the preexecute function that will be. |
| **Integrations > BigQuery > Packages > flyteplugins.bigquery > BigQueryTask > Methods > sql()** | Returns the SQL for the task. |

### aio()

```python
def aio(
    args: *args,
    kwargs: **kwargs,
) -> Coroutine[Any, Any, R] | R
```
The aio function allows executing "sync" tasks, in an async context. This helps with migrating v1 defined sync
tasks to be used within an asyncio parent task.
This function will also re-raise exceptions from the underlying task.

```python
@env.task
def my_legacy_task(x: int) -> int:
    return x

@env.task
async def my_new_parent_task(n: int) -> List[int]:
    collect = []
    for x in range(n):
        collect.append(my_legacy_task.aio(x))
    return asyncio.gather(*collect)
```

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### config()

```python
def config(
    sctx: SerializationContext,
) -> Dict[str, str]
```
Returns additional configuration for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### container_args()

```python
def container_args(
    sctx: SerializationContext,
) -> List[str]
```
Returns the container args for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### custom_config()

```python
def custom_config(
    sctx: flyte.models.SerializationContext,
) -> typing.Optional[typing.Dict[str, typing.Any]]
```
Returns additional configuration for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `flyte.models.SerializationContext` | |

### data_loading_config()

```python
def data_loading_config(
    sctx: SerializationContext,
) -> DataLoadingConfig
```
This configuration allows executing raw containers in Flyte using the Flyte CoPilot system
Flyte CoPilot, eliminates the needs of sdk inside the container. Any inputs required by the users container
are side-loaded in the input_path
Any outputs generated by the user container - within output_path are automatically uploaded

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### execute()

```python
def execute(
    kwargs,
) -> typing.Any
```
| Parameter | Type | Description |
|-|-|-|
| `kwargs` | `**kwargs` | |

### forward()

```python
def forward(
    args: *args,
    kwargs: **kwargs,
) -> Coroutine[Any, Any, R] | R
```
Think of this as a local execute method for your task. This function will be invoked by the __call__ method
when not in a Flyte task execution context.  See the implementation below for an example.

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### override()

```python
def override(
    short_name: Optional[str],
    resources: Optional[Resources],
    cache: Optional[CacheRequest],
    retries: Union[int, RetryStrategy],
    timeout: Optional[TimeoutType],
    reusable: Union[ReusePolicy, Literal['off'], None],
    env_vars: Optional[Dict[str, str]],
    secrets: Optional[SecretRequest],
    max_inline_io_bytes: int | None,
    pod_template: Optional[Union[str, PodTemplate]],
    queue: Optional[str],
    interruptible: Optional[bool],
    links: Tuple[Link, ...],
    kwargs: **kwargs,
) -> TaskTemplate
```
Override various parameters of the task template. This allows for dynamic configuration of the task
when it is called, such as changing the image, resources, cache policy, etc.

| Parameter | Type | Description |
|-|-|-|
| `short_name` | `Optional[str]` | Optional override for the short name of the task. |
| `resources` | `Optional[Resources]` | Optional override for the resources to use for the task. |
| `cache` | `Optional[CacheRequest]` | Optional override for the cache policy for the task. |
| `retries` | `Union[int, RetryStrategy]` | Optional override for the number of retries for the task. |
| `timeout` | `Optional[TimeoutType]` | Optional override for the timeout for the task. |
| `reusable` | `Union[ReusePolicy, Literal['off'], None]` | Optional override for the reusability policy for the task. |
| `env_vars` | `Optional[Dict[str, str]]` | Optional override for the environment variables to set for the task. |
| `secrets` | `Optional[SecretRequest]` | Optional override for the secrets that will be injected into the task at runtime. |
| `max_inline_io_bytes` | `int \| None` | Optional override for the maximum allowed size (in bytes) for all inputs and outputs passed directly to the task. |
| `pod_template` | `Optional[Union[str, PodTemplate]]` | Optional override for the pod template to use for the task. |
| `queue` | `Optional[str]` | Optional override for the queue to use for the task. |
| `interruptible` | `Optional[bool]` | Optional override for the interruptible policy for the task. |
| `links` | `Tuple[Link, ...]` | Optional override for the Links associated with the task. |
| `kwargs` | `**kwargs` | Additional keyword arguments for further overrides. Some fields like name, image, docs, and interface cannot be overridden. |

**Returns:** A new TaskTemplate instance with the overridden parameters.

### post()

```python
def post(
    return_vals: Any,
) -> Any
```
This is the postexecute function that will be
called after the task is executed

| Parameter | Type | Description |
|-|-|-|
| `return_vals` | `Any` | |

### pre()

```python
def pre(
    args,
    kwargs,
) -> Dict[str, Any]
```
This is the preexecute function that will be
called before the task is executed

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### sql()

```python
def sql(
    sctx: flyte.models.SerializationContext,
) -> typing.Optional[str]
```
Returns the SQL for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `flyte.models.SerializationContext` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/codegen ===

# Code generation

## Subpages
- **Integrations > Code generation > Classes**
- **Integrations > Code generation > Packages**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/codegen/classes ===

# Classes

| Class | Description |
|-|-|
| **Integrations > Code generation > Packages > flyteplugins.codegen > AutoCoderAgent** |Agent for single-file Python code generation with automatic testing and iteration. |
| **Integrations > Code generation > Packages > flyteplugins.codegen > CodeGenEvalResult** |Result from code generation and evaluation. |
| **Integrations > Code generation > Packages > flyteplugins.codegen > CodePlan** |Structured plan for the code solution. |
| **Integrations > Code generation > Packages > flyteplugins.codegen > CodeSolution** |Structured code solution. |
| **Integrations > Code generation > Packages > flyteplugins.codegen > ErrorDiagnosis** |Structured diagnosis of execution errors. |
| **Integrations > Code generation > Packages > flyteplugins.codegen > ImageConfig** |Configuration for Docker image building at runtime. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/codegen/packages ===

# Packages

| Package | Description |
|-|-|
| **Integrations > Code generation > Packages > flyteplugins.codegen** |  |

## Subpages
- **Integrations > Code generation > Packages > flyteplugins.codegen**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/codegen/packages/flyteplugins.codegen ===

# flyteplugins.codegen

## Directory

### Classes

| Class | Description |
|-|-|
| **Integrations > Code generation > Packages > flyteplugins.codegen > AutoCoderAgent** | Agent for single-file Python code generation with automatic testing and iteration. |
| **Integrations > Code generation > Packages > flyteplugins.codegen > CodeGenEvalResult** | Result from code generation and evaluation. |
| **Integrations > Code generation > Packages > flyteplugins.codegen > CodePlan** | Structured plan for the code solution. |
| **Integrations > Code generation > Packages > flyteplugins.codegen > CodeSolution** | Structured code solution. |
| **Integrations > Code generation > Packages > flyteplugins.codegen > ErrorDiagnosis** | Structured diagnosis of execution errors. |
| **Integrations > Code generation > Packages > flyteplugins.codegen > ImageConfig** | Configuration for Docker image building at runtime. |

## Subpages
- **Integrations > Code generation > Packages > flyteplugins.codegen > AutoCoderAgent**
- **Integrations > Code generation > Packages > flyteplugins.codegen > CodeGenEvalResult**
- **Integrations > Code generation > Packages > flyteplugins.codegen > CodePlan**
- **Integrations > Code generation > Packages > flyteplugins.codegen > CodeSolution**
- **Integrations > Code generation > Packages > flyteplugins.codegen > ErrorDiagnosis**
- **Integrations > Code generation > Packages > flyteplugins.codegen > ImageConfig**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/codegen/packages/flyteplugins.codegen/autocoderagent ===

# AutoCoderAgent

**Package:** `flyteplugins.codegen`

Agent for single-file Python code generation with automatic testing and iteration.

Generates a single Python script, builds a sandbox image with the required
dependencies, runs pytest-based tests, and iterates until tests pass.

Uses Sandbox internally for isolated code execution.

## Parameters

```python
class AutoCoderAgent(
    model: str,
    name: str,
    system_prompt: typing.Optional[str],
    api_key: typing.Optional[str],
    api_base: typing.Optional[str],
    litellm_params: typing.Optional[dict],
    base_packages: typing.Optional[list[str]],
    resources: typing.Optional[flyte._resources.Resources],
    image_config: typing.Optional[flyte.sandbox._code_sandbox.ImageConfig],
    max_iterations: int,
    max_sample_rows: int,
    skip_tests: bool,
    sandbox_retries: int,
    timeout: typing.Optional[int],
    env_vars: typing.Optional[dict[str, str]],
    secrets: typing.Optional[list],
    cache: str,
    backend: typing.Literal['litellm', 'claude'],
    agent_max_turns: int,
)
```
| Parameter | Type | Description |
|-|-|-|
| `model` | `str` | LLM model to use (required). Must support structured outputs. For backend="litellm" (default): e.g. "gpt-4.1", "claude-sonnet-4-20250514". For backend="claude": a Claude model ("sonnet", "opus", "haiku"). |
| `name` | `str` | Name for the agent (used in image naming and logging). |
| `system_prompt` | `typing.Optional[str]` | Optional system prompt to use for LLM. If not provided, a default prompt with structured output requirements is used. |
| `api_key` | `typing.Optional[str]` | Optional environment variable name for LLM API key. |
| `api_base` | `typing.Optional[str]` | Optional base URL for LLM API. |
| `litellm_params` | `typing.Optional[dict]` | Optional dict of additional parameters to pass to LiteLLM calls. |
| `base_packages` | `typing.Optional[list[str]]` | Optional list of base packages to install in the sandbox. |
| `resources` | `typing.Optional[flyte._resources.Resources]` | Optional resources for sandbox execution (default: cpu=1, 1Gi). |
| `image_config` | `typing.Optional[flyte.sandbox._code_sandbox.ImageConfig]` | Optional image configuration for sandbox execution. |
| `max_iterations` | `int` | Maximum number of generate-test-fix iterations. Defaults to 10. |
| `max_sample_rows` | `int` | Optional maximum number of rows to use for sample data. Defaults to 100. |
| `skip_tests` | `bool` | Optional flag to skip testing. Defaults to False. |
| `sandbox_retries` | `int` | Number of Flyte task-level retries for each sandbox execution. Defaults to 0. |
| `timeout` | `typing.Optional[int]` | Timeout in seconds for sandboxes. Defaults to None. |
| `env_vars` | `typing.Optional[dict[str, str]]` | Environment variables to pass to sandboxes. |
| `secrets` | `typing.Optional[list]` | flyte.Secret objects to make available to sandboxes. |
| `cache` | `str` | CacheRequest for sandboxes: "auto", "override", or "disable". Defaults to "auto". |
| `backend` | `typing.Literal['litellm', 'claude']` | Execution backend: "litellm" (default) or "claude". |
| `agent_max_turns` | `int` | Maximum agent turns when backend="claude". Defaults to 50. |

## Methods

| Method | Description |
|-|-|
| **Integrations > Code generation > Packages > flyteplugins.codegen > AutoCoderAgent > Methods > generate()** | Generate and evaluate code in an isolated sandbox. |

### generate()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await <AutoCoderAgent instance>.generate.aio()`.
```python
def generate(
    prompt: str,
    schema: typing.Optional[str],
    constraints: typing.Optional[list[str]],
    samples: typing.Optional[dict[str, pandas.core.frame.DataFrame | flyte.io._file.File]],
    inputs: typing.Optional[dict[str, type]],
    outputs: typing.Optional[dict[str, type]],
) -> flyteplugins.codegen.core.types.CodeGenEvalResult
```
Generate and evaluate code in an isolated sandbox.

Each call is independent with its own sandbox, packages and execution environment.

| Parameter | Type | Description |
|-|-|-|
| `prompt` | `str` | The prompt to generate code from. |
| `schema` | `typing.Optional[str]` | Optional free-form context about data formats, structures or schemas. Included verbatim in the LLM prompt. Use for input formats, output schemas, database schemas or any structural context the LLM needs to generate code. |
| `constraints` | `typing.Optional[list[str]]` | Optional list of constraints or requirements. |
| `samples` | `typing.Optional[dict[str, pandas.core.frame.DataFrame \| flyte.io._file.File]]` | Optional dict of sample data. Each value is sampled and included in the LLM prompt for context, and converted to a File input for the sandbox. Values are used as defaults at runtime — override them when calling `result.run()` or `result.as_task()`. Supported types: File, pd.DataFrame. |
| `inputs` | `typing.Optional[dict[str, type]]` | Optional dict declaring non-sample CLI argument types (e.g., `{"threshold": float, "mode": str}`). Sample entries are automatically added as File inputs — don't redeclare them here. Supported types: str, int, float, bool, File. |
| `outputs` | `typing.Optional[dict[str, type]]` | Optional dict defining output types (e.g., `{"result": str, "report": File}`). Supported types: str, int, float, bool, datetime, timedelta, File. |

**Returns:** CodeGenEvalResult with solution and execution details.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/codegen/packages/flyteplugins.codegen/codegenevalresult ===

# CodeGenEvalResult

**Package:** `flyteplugins.codegen`

Result from code generation and evaluation.

## Parameters

```python
class CodeGenEvalResult(
    plan: typing.Optional[flyteplugins.codegen.core.types.CodePlan],
    solution: flyteplugins.codegen.core.types.CodeSolution,
    tests: typing.Optional[str],
    success: bool,
    output: str,
    exit_code: int,
    error: typing.Optional[str],
    attempts: int,
    conversation_history: list[dict[str, str]],
    detected_packages: list[str],
    detected_system_packages: list[str],
    image: typing.Optional[str],
    total_input_tokens: int,
    total_output_tokens: int,
    declared_inputs: typing.Optional[dict[str, type]],
    declared_outputs: typing.Optional[dict[str, type]],
    data_context: typing.Optional[str],
    original_samples: typing.Optional[dict[str, flyte.io._file.File]],
    generated_schemas: typing.Optional[dict[str, str]],
)
```
Create a new model by parsing and validating input data from keyword arguments.

Raises [`ValidationError`](https://docs.pydantic.dev/latest/api/pydantic_core/#pydantic_core.ValidationError) if the input data cannot be
validated to form a valid model.

`self` is explicitly positional-only to allow `self` as a field name.

| Parameter | Type | Description |
|-|-|-|
| `plan` | `typing.Optional[flyteplugins.codegen.core.types.CodePlan]` | |
| `solution` | `flyteplugins.codegen.core.types.CodeSolution` | |
| `tests` | `typing.Optional[str]` | |
| `success` | `bool` | |
| `output` | `str` | |
| `exit_code` | `int` | |
| `error` | `typing.Optional[str]` | |
| `attempts` | `int` | |
| `conversation_history` | `list[dict[str, str]]` | |
| `detected_packages` | `list[str]` | Language packages detected by LLM from imports |
| `detected_system_packages` | `list[str]` | System packages detected by LLM |
| `image` | `typing.Optional[str]` | The Flyte Image built with all dependencies |
| `total_input_tokens` | `int` | Total input tokens used across all LLM calls |
| `total_output_tokens` | `int` | Total output tokens used across all LLM calls |
| `declared_inputs` | `typing.Optional[dict[str, type]]` | Input types (user-provided or inferred from samples) |
| `declared_outputs` | `typing.Optional[dict[str, type]]` | Output types declared by user |
| `data_context` | `typing.Optional[str]` | Extracted data context (schema, stats, patterns, samples) used for code generation |
| `original_samples` | `typing.Optional[dict[str, flyte.io._file.File]]` | Sample data converted to Files (defaults for run()/as_task()) |
| `generated_schemas` | `typing.Optional[dict[str, str]]` | Auto-generated Pandera schemas (as Python code strings) for validating data inputs |

## Methods

| Method | Description |
|-|-|
| **Integrations > Code generation > Packages > flyteplugins.codegen > CodeGenEvalResult > Methods > as_task()** | Create a sandbox that runs the generated code in an isolated sandbox. |
| **Integrations > Code generation > Packages > flyteplugins.codegen > CodeGenEvalResult > Methods > run()** | Run generated code in an isolated sandbox (one-off execution). |

### as_task()

```python
def as_task(
    name: str,
    resources: typing.Optional[flyte._resources.Resources],
    retries: int,
    timeout: typing.Optional[int],
    env_vars: typing.Optional[dict[str, str]],
    secrets: typing.Optional[list],
    cache: str,
)
```
Create a sandbox that runs the generated code in an isolated sandbox.

The generated code will write outputs to /var/outputs/{output_name} files.
Returns a callable wrapper that automatically provides the script file.

| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | Name for the sandbox |
| `resources` | `typing.Optional[flyte._resources.Resources]` | Optional resources for the task |
| `retries` | `int` | Number of retries for the task. Defaults to 0. |
| `timeout` | `typing.Optional[int]` | Timeout in seconds. Defaults to None. |
| `env_vars` | `typing.Optional[dict[str, str]]` | Environment variables to pass to the sandbox. |
| `secrets` | `typing.Optional[list]` | flyte.Secret objects to make available. |
| `cache` | `str` | CacheRequest: "auto", "override", or "disable". Defaults to "auto". |

**Returns:** Callable task wrapper with the default inputs baked in. Call with your other declared inputs.

### run()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await <CodeGenEvalResult instance>.run.aio()`.
```python
def run(
    name: str,
    resources: typing.Optional[flyte._resources.Resources],
    retries: int,
    timeout: typing.Optional[int],
    env_vars: typing.Optional[dict[str, str]],
    secrets: typing.Optional[list],
    cache: str,
    overrides,
) -> typing.Any
```
Run generated code in an isolated sandbox (one-off execution).

If samples were provided during generate(), they are used as defaults.
Override any input by passing it as a keyword argument. If no samples
exist, all declared inputs must be provided via `**overrides`.

| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | Name for the sandbox |
| `resources` | `typing.Optional[flyte._resources.Resources]` | Optional resources for the task |
| `retries` | `int` | Number of retries for the task. Defaults to 0. |
| `timeout` | `typing.Optional[int]` | Timeout in seconds. Defaults to None. |
| `env_vars` | `typing.Optional[dict[str, str]]` | Environment variables to pass to the sandbox. |
| `secrets` | `typing.Optional[list]` | flyte.Secret objects to make available. |
| `cache` | `str` | CacheRequest: "auto", "override", or "disable". Defaults to "auto". |
| `overrides` |  | |

**Returns:** Tuple of typed outputs.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/codegen/packages/flyteplugins.codegen/codeplan ===

# CodePlan

**Package:** `flyteplugins.codegen`

Structured plan for the code solution.

## Parameters

```python
class CodePlan(
    description: str,
    approach: str,
)
```
Create a new model by parsing and validating input data from keyword arguments.

Raises [`ValidationError`](https://docs.pydantic.dev/latest/api/pydantic_core/#pydantic_core.ValidationError) if the input data cannot be
validated to form a valid model.

`self` is explicitly positional-only to allow `self` as a field name.

| Parameter | Type | Description |
|-|-|-|
| `description` | `str` | Overall description of the solution |
| `approach` | `str` | High-level approach and algorithm to solve the problem |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/codegen/packages/flyteplugins.codegen/codesolution ===

# CodeSolution

**Package:** `flyteplugins.codegen`

Structured code solution.

## Parameters

```python
class CodeSolution(
    language: str,
    code: str,
    system_packages: list[str],
)
```
Create a new model by parsing and validating input data from keyword arguments.

Raises [`ValidationError`](https://docs.pydantic.dev/latest/api/pydantic_core/#pydantic_core.ValidationError) if the input data cannot be
validated to form a valid model.

`self` is explicitly positional-only to allow `self` as a field name.

| Parameter | Type | Description |
|-|-|-|
| `language` | `str` | Programming language |
| `code` | `str` | Complete executable code including imports and dependencies |
| `system_packages` | `list[str]` | System packages needed (e.g., gcc, build-essential, curl) |

## Methods

| Method | Description |
|-|-|
| **Integrations > Code generation > Packages > flyteplugins.codegen > CodeSolution > Methods > normalize_language()** |  |

### normalize_language()

```python
def normalize_language(
    v: str,
) -> str
```
| Parameter | Type | Description |
|-|-|-|
| `v` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/codegen/packages/flyteplugins.codegen/errordiagnosis ===

# ErrorDiagnosis

**Package:** `flyteplugins.codegen`

Structured diagnosis of execution errors.

## Parameters

```python
class ErrorDiagnosis(
    failures: list[flyteplugins.codegen.core.types.TestFailure],
    needs_system_packages: list[str],
    needs_language_packages: list[str],
    needs_additional_commands: list[str],
)
```
Create a new model by parsing and validating input data from keyword arguments.

Raises [`ValidationError`](https://docs.pydantic.dev/latest/api/pydantic_core/#pydantic_core.ValidationError) if the input data cannot be
validated to form a valid model.

`self` is explicitly positional-only to allow `self` as a field name.

| Parameter | Type | Description |
|-|-|-|
| `failures` | `list[flyteplugins.codegen.core.types.TestFailure]` | Individual test failures with their diagnoses |
| `needs_system_packages` | `list[str]` | System packages needed (e.g., gcc, pkg-config). |
| `needs_language_packages` | `list[str]` | Language packages needed. |
| `needs_additional_commands` | `list[str]` | Additional RUN commands (e.g., apt-get update, mkdir /data, wget files). |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/codegen/packages/flyteplugins.codegen/imageconfig ===

# ImageConfig

**Package:** `flyteplugins.codegen`

Configuration for Docker image building at runtime.

## Parameters

```python
class ImageConfig(
    registry: typing.Optional[str],
    registry_secret: typing.Optional[str],
    python_version: typing.Optional[tuple[int, int]],
)
```
| Parameter | Type | Description |
|-|-|-|
| `registry` | `typing.Optional[str]` | |
| `registry_secret` | `typing.Optional[str]` | |
| `python_version` | `typing.Optional[tuple[int, int]]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/dask ===

# Dask

## Subpages
- **Integrations > Dask > Classes**
- **Integrations > Dask > Packages**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/dask/classes ===

# Classes

| Class | Description |
|-|-|
| **Integrations > Dask > Packages > flyteplugins.dask > Dask** |Configuration for the dask task. |
| **Integrations > Dask > Packages > flyteplugins.dask > Scheduler** |Configuration for the scheduler pod. |
| **Integrations > Dask > Packages > flyteplugins.dask > WorkerGroup** |Configuration for a group of dask worker pods. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/dask/packages ===

# Packages

| Package | Description |
|-|-|
| **Integrations > Dask > Packages > flyteplugins.dask** |  |

## Subpages
- **Integrations > Dask > Packages > flyteplugins.dask**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/dask/packages/flyteplugins.dask ===

# flyteplugins.dask

## Directory

### Classes

| Class | Description |
|-|-|
| **Integrations > Dask > Packages > flyteplugins.dask > Dask** | Configuration for the dask task. |
| **Integrations > Dask > Packages > flyteplugins.dask > Scheduler** | Configuration for the scheduler pod. |
| **Integrations > Dask > Packages > flyteplugins.dask > WorkerGroup** | Configuration for a group of dask worker pods. |

## Subpages
- **Integrations > Dask > Packages > flyteplugins.dask > Dask**
- **Integrations > Dask > Packages > flyteplugins.dask > Scheduler**
- **Integrations > Dask > Packages > flyteplugins.dask > WorkerGroup**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/dask/packages/flyteplugins.dask/dask ===

# Dask

**Package:** `flyteplugins.dask`

Configuration for the dask task

## Parameters

```python
class Dask(
    scheduler: flyteplugins.dask.task.Scheduler,
    workers: flyteplugins.dask.task.WorkerGroup,
)
```
| Parameter | Type | Description |
|-|-|-|
| `scheduler` | `flyteplugins.dask.task.Scheduler` | Configuration for the scheduler pod. Optional, defaults to `Scheduler()`. |
| `workers` | `flyteplugins.dask.task.WorkerGroup` | Configuration for the pods of the default worker group. Optional, defaults to `WorkerGroup()`. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/dask/packages/flyteplugins.dask/scheduler ===

# Scheduler

**Package:** `flyteplugins.dask`

Configuration for the scheduler pod

## Parameters

```python
class Scheduler(
    image: typing.Optional[str],
    resources: typing.Optional[flyte._resources.Resources],
)
```
| Parameter | Type | Description |
|-|-|-|
| `image` | `typing.Optional[str]` | Custom image to use. If `None`, will use the same image the task was registered with. Optional, defaults to None. The image must have `dask[distributed]` installed and should have the same Python environment as the rest of the cluster (job runner pod + worker pods). |
| `resources` | `typing.Optional[flyte._resources.Resources]` | Resources to request for the scheduler pod. Optional, defaults to None. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/dask/packages/flyteplugins.dask/workergroup ===

# WorkerGroup

**Package:** `flyteplugins.dask`

Configuration for a group of dask worker pods

## Parameters

```python
class WorkerGroup(
    number_of_workers: typing.Optional[int],
    image: typing.Optional[str],
    resources: typing.Optional[flyte._resources.Resources],
)
```
| Parameter | Type | Description |
|-|-|-|
| `number_of_workers` | `typing.Optional[int]` | Number of workers to use. Optional, defaults to 1. |
| `image` | `typing.Optional[str]` | Custom image to use. If `None`, will use the same image the task was registered with. Optional, defaults to None. The image must have `dask[distributed]` installed. The provided image should have the same Python environment as the job runner/driver as well as the scheduler. |
| `resources` | `typing.Optional[flyte._resources.Resources]` | Resources to request for the worker pods. Optional, defaults to None. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/databricks ===

# Databricks

## Subpages
- **Integrations > Databricks > Classes**
- **Integrations > Databricks > Packages**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/databricks/classes ===

# Classes

| Class | Description |
|-|-|
| **Integrations > Databricks > Packages > flyteplugins.databricks > Databricks** |Configuration for a Databricks task. |
| **Integrations > Databricks > Packages > flyteplugins.databricks > DatabricksConnector** | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/databricks/packages ===

# Packages

| Package | Description |
|-|-|
| **Integrations > Databricks > Packages > flyteplugins.databricks** | Databricks connector plugin for Flyte. |

## Subpages
- **Integrations > Databricks > Packages > flyteplugins.databricks**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/databricks/packages/flyteplugins.databricks ===

# flyteplugins.databricks

Databricks connector plugin for Flyte.

This plugin provides integration between Flyte tasks and Databricks,
enabling you to run PySpark jobs on Databricks clusters as Flyte tasks
with full observability, retries, and caching.

Key features:

- Run PySpark tasks natively on Databricks clusters
- Configurable cluster spec via the Databricks Jobs API
- Automatic job lifecycle management: create, poll, cancel
- Automatic links to the Databricks job run UI in the Flyte UI

Basic usage example:

```python
import flyte
from flyteplugins.databricks import Databricks

databricks_config = Databricks(
    spark_conf={"spark.executor.memory": "4g"},
    databricks_conf={
        "run_name": "my_job",
        "new_cluster": {
            "spark_version": "13.3.x-scala2.12",
            "node_type_id": "i3.xlarge",
            "num_workers": 2,
        },
    },
    databricks_instance="myorg.cloud.databricks.com",
    databricks_token="databricks_token_secret",
)

env = flyte.TaskEnvironment(
    name="databricks_env",
    plugin_config=databricks_config,
    image=flyte.Image.from_debian_base(name="pyspark").with_pip_packages(
        "flyteplugins-databricks"
    ),
)

@env.task
def process_data(input_path: str) -> int:
    from pyspark.sql import SparkSession
    spark = SparkSession.builder.getOrCreate()
    df = spark.read.parquet(input_path)
    return df.count()
```
## Directory

### Classes

| Class | Description |
|-|-|
| **Integrations > Databricks > Packages > flyteplugins.databricks > Databricks** | Configuration for a Databricks task. |
| **Integrations > Databricks > Packages > flyteplugins.databricks > DatabricksConnector** |  |

## Subpages
- **Integrations > Databricks > Packages > flyteplugins.databricks > Databricks**
- **Integrations > Databricks > Packages > flyteplugins.databricks > DatabricksConnector**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/databricks/packages/flyteplugins.databricks/databricks ===

# Databricks

**Package:** `flyteplugins.databricks`

Configuration for a Databricks task.

Tasks configured with this will execute natively on Databricks as a
distributed PySpark job. Extends `Spark` with Databricks-specific
cluster and authentication settings.

## Parameters

```python
class Databricks(
    spark_conf: typing.Optional[typing.Dict[str, str]],
    hadoop_conf: typing.Optional[typing.Dict[str, str]],
    executor_path: typing.Optional[str],
    applications_path: typing.Optional[str],
    driver_pod: typing.Optional[flyte._pod.PodTemplate],
    executor_pod: typing.Optional[flyte._pod.PodTemplate],
    databricks_conf: typing.Optional[typing.Dict[str, typing.Union[str, dict]]],
    databricks_instance: typing.Optional[str],
    databricks_token: typing.Optional[str],
)
```
| Parameter | Type | Description |
|-|-|-|
| `spark_conf` | `typing.Optional[typing.Dict[str, str]]` | Spark configuration key-value pairs, e.g. `{"spark.executor.memory": "4g"}`. |
| `hadoop_conf` | `typing.Optional[typing.Dict[str, str]]` | Hadoop configuration key-value pairs. |
| `executor_path` | `typing.Optional[str]` | Path to the Python binary used for PySpark execution. Defaults to the interpreter path from the serialization context. |
| `applications_path` | `typing.Optional[str]` | Path to the main application file. Defaults to the task entrypoint path. |
| `driver_pod` | `typing.Optional[flyte._pod.PodTemplate]` | Pod template applied to the Spark driver pod. |
| `executor_pod` | `typing.Optional[flyte._pod.PodTemplate]` | Pod template applied to the Spark executor pods. |
| `databricks_conf` | `typing.Optional[typing.Dict[str, typing.Union[str, dict]]]` | Databricks job configuration dict compliant with the Databricks Jobs API v2.1 (also supports v2.0 use cases). Typically includes `new_cluster` or `existing_cluster_id`, `run_name`, and other job settings. |
| `databricks_instance` | `typing.Optional[str]` | Domain name of your Databricks deployment, e.g. `"myorg.cloud.databricks.com"`. |
| `databricks_token` | `typing.Optional[str]` | Name of the Flyte secret containing the Databricks API token used for authentication. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/databricks/packages/flyteplugins.databricks/databricksconnector ===

# DatabricksConnector

**Package:** `flyteplugins.databricks`

## Methods

| Method | Description |
|-|-|
| **Integrations > Databricks > Packages > flyteplugins.databricks > DatabricksConnector > Methods > create()** | Return a resource meta that can be used to get the status of the task. |
| **Integrations > Databricks > Packages > flyteplugins.databricks > DatabricksConnector > Methods > delete()** | Delete the task. |
| **Integrations > Databricks > Packages > flyteplugins.databricks > DatabricksConnector > Methods > get()** | Return the status of the task, and return the outputs in some cases. |
| **Integrations > Databricks > Packages > flyteplugins.databricks > DatabricksConnector > Methods > get_logs()** | Return the metrics for the task. |
| **Integrations > Databricks > Packages > flyteplugins.databricks > DatabricksConnector > Methods > get_metrics()** | Return the metrics for the task. |

### create()

```python
def create(
    task_template: flyteidl2.core.tasks_pb2.TaskTemplate,
    inputs: typing.Optional[typing.Dict[str, typing.Any]],
    databricks_token: typing.Optional[str],
    kwargs,
) -> flyteplugins.databricks.connector.DatabricksJobMetadata
```
Return a resource meta that can be used to get the status of the task.

| Parameter | Type | Description |
|-|-|-|
| `task_template` | `flyteidl2.core.tasks_pb2.TaskTemplate` | |
| `inputs` | `typing.Optional[typing.Dict[str, typing.Any]]` | |
| `databricks_token` | `typing.Optional[str]` | |
| `kwargs` | `**kwargs` | |

### delete()

```python
def delete(
    resource_meta: flyteplugins.databricks.connector.DatabricksJobMetadata,
    databricks_token: typing.Optional[str],
    kwargs,
)
```
Delete the task. This call should be idempotent. It should raise an error if fails to delete the task.

| Parameter | Type | Description |
|-|-|-|
| `resource_meta` | `flyteplugins.databricks.connector.DatabricksJobMetadata` | |
| `databricks_token` | `typing.Optional[str]` | |
| `kwargs` | `**kwargs` | |

### get()

```python
def get(
    resource_meta: flyteplugins.databricks.connector.DatabricksJobMetadata,
    databricks_token: typing.Optional[str],
    kwargs,
) -> flyte.connectors._connector.Resource
```
Return the status of the task, and return the outputs in some cases. For example, bigquery job
can't write the structured dataset to the output location, so it returns the output literals to the propeller,
and the propeller will write the structured dataset to the blob store.

| Parameter | Type | Description |
|-|-|-|
| `resource_meta` | `flyteplugins.databricks.connector.DatabricksJobMetadata` | |
| `databricks_token` | `typing.Optional[str]` | |
| `kwargs` | `**kwargs` | |

### get_logs()

```python
def get_logs(
    resource_meta: flyte.connectors._connector.ResourceMeta,
    kwargs,
) -> flyteidl2.connector.connector_pb2.GetTaskLogsResponse
```
Return the metrics for the task.

| Parameter | Type | Description |
|-|-|-|
| `resource_meta` | `flyte.connectors._connector.ResourceMeta` | |
| `kwargs` | `**kwargs` | |

### get_metrics()

```python
def get_metrics(
    resource_meta: flyte.connectors._connector.ResourceMeta,
    kwargs,
) -> flyteidl2.connector.connector_pb2.GetTaskMetricsResponse
```
Return the metrics for the task.

| Parameter | Type | Description |
|-|-|-|
| `resource_meta` | `flyte.connectors._connector.ResourceMeta` | |
| `kwargs` | `**kwargs` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/gemini ===

# Gemini

## Subpages
- **Integrations > Gemini > Classes**
- **Integrations > Gemini > Packages**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/gemini/classes ===

# Classes

| Class | Description |
|-|-|
| **Integrations > Gemini > Packages > flyteplugins.gemini > Agent** |A Gemini agent configuration. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/gemini/packages ===

# Packages

| Package | Description |
|-|-|
| **Integrations > Gemini > Packages > flyteplugins.gemini** | Google Gemini plugin for Flyte. |

## Subpages
- **Integrations > Gemini > Packages > flyteplugins.gemini**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/gemini/packages/flyteplugins.gemini ===

# flyteplugins.gemini

Google Gemini plugin for Flyte.

This plugin provides integration between Flyte tasks and Google's Gemini API,
enabling you to use Flyte tasks as tools for Gemini agents. Tool calls run with
full Flyte observability, retries, and caching.

Key features:

- Use any Flyte task as a Gemini tool via `function_tool`
- Full agent loop with automatic tool dispatch via `run_agent`
- Configurable agent via `Agent` (model, system prompt, tools, iteration limits)

Basic usage example:

```python
import flyte
from flyteplugins.gemini import Agent, function_tool, run_agent

env = flyte.TaskEnvironment(
    name="agent_env",
    image=flyte.Image.from_debian_base(name="agent").with_pip_packages(
        "flyteplugins-gemini"
    ),
)

@env.task
async def get_weather(city: str) -> str:
    '''Get the current weather for a city.'''
    return f"Weather in {city}: sunny, 22°C"

weather_tool = function_tool(get_weather)

@env.task
async def run_weather_agent(question: str) -> str:
    return await run_agent(
        prompt=question,
        tools=[weather_tool],
        model="gemini-2.5-flash",
    )
```
## Directory

### Classes

| Class | Description |
|-|-|
| **Integrations > Gemini > Packages > flyteplugins.gemini > Agent** | A Gemini agent configuration. |

### Methods

| Method | Description |
|-|-|
| **Integrations > Gemini > Packages > flyteplugins.gemini > Methods > function_tool()** | Convert a function or Flyte task to a Gemini-compatible tool. |
| **Integrations > Gemini > Packages > flyteplugins.gemini > Methods > run_agent()** | Run a Gemini agent with the given tools and prompt. |

## Methods

#### function_tool()

```python
def function_tool(
    func: typing.Union[flyte._task.AsyncFunctionTaskTemplate, typing.Callable, NoneType],
    name: str | None,
    description: str | None,
) -> FunctionTool | partial[FunctionTool]
```
Convert a function or Flyte task to a Gemini-compatible tool.

This function converts a Python function, @flyte.trace decorated function,
or Flyte task into a FunctionTool that can be used with Gemini's function calling API.

The input_schema is derived via the Flyte type engine, producing JSON schema.
This ensures that Literal types, dataclasses, FlyteFile, and other Flyte-native
types are represented correctly.

For @flyte.trace decorated functions, the tracing context is preserved
automatically since functools.wraps maintains the original function's metadata.

| Parameter | Type | Description |
|-|-|-|
| `func` | `typing.Union[flyte._task.AsyncFunctionTaskTemplate, typing.Callable, NoneType]` | The function or Flyte task to convert. |
| `name` | `str \| None` | Optional custom name for the tool. Defaults to the function name. |
| `description` | `str \| None` | Optional custom description. Defaults to the function's docstring. |

**Returns**

A FunctionTool instance that can be used with run_agent().

#### run_agent()

```python
def run_agent(
    prompt: str,
    tools: list[flyteplugins.gemini.agents._function_tools.FunctionTool] | None,
    agent: flyteplugins.gemini.agents._function_tools.Agent | None,
    model: str,
    system: str | None,
    max_output_tokens: int,
    max_iterations: int,
    api_key: str | None,
) -> str
```
Run a Gemini agent with the given tools and prompt.

This function creates a Gemini conversation loop that can use tools
to accomplish tasks. It handles the back-and-forth of function calls
and responses until the agent produces a final text response.

| Parameter | Type | Description |
|-|-|-|
| `prompt` | `str` | The user prompt to send to the agent. |
| `tools` | `list[flyteplugins.gemini.agents._function_tools.FunctionTool] \| None` | List of FunctionTool instances to make available to the agent. |
| `agent` | `flyteplugins.gemini.agents._function_tools.Agent \| None` | Optional Agent configuration. If provided, overrides other params. |
| `model` | `str` | The Gemini model to use. |
| `system` | `str \| None` | Optional system prompt. |
| `max_output_tokens` | `int` | Maximum tokens in the response. |
| `max_iterations` | `int` | Maximum number of tool call iterations. |
| `api_key` | `str \| None` | Google API key. Defaults to GOOGLE_API_KEY env var. |

**Returns**

The final text response from the agent.

## Subpages
- **Integrations > Gemini > Packages > flyteplugins.gemini > Agent**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/gemini/packages/flyteplugins.gemini/agent ===

# Agent

**Package:** `flyteplugins.gemini`

A Gemini agent configuration.

This class represents the configuration for a Gemini agent, including
the model to use, system instructions, and available tools.

## Parameters

```python
class Agent(
    name: str,
    instructions: str,
    model: str,
    tools: list[flyteplugins.gemini.agents._function_tools.FunctionTool],
    max_output_tokens: int,
    max_iterations: int,
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | A human-readable name for this agent. Used for logging and identification only; not sent to the API. |
| `instructions` | `str` | The system prompt passed to Gemini on every turn. Describes the agent's role, tone, and constraints. |
| `model` | `str` | The Gemini model ID to use, e.g. `"gemini-2.5-flash"`. |
| `tools` | `list[flyteplugins.gemini.agents._function_tools.FunctionTool]` | List of `FunctionTool` instances the agent can invoke. Create tools with `function_tool()`. |
| `max_output_tokens` | `int` | Maximum number of tokens in each Gemini response. |
| `max_iterations` | `int` | Maximum number of function-call / response cycles before `run_agent` returns with a timeout message. |

## Methods

| Method | Description |
|-|-|
| **Integrations > Gemini > Packages > flyteplugins.gemini > Agent > Methods > get_gemini_tools()** | Get tool definitions in Gemini format. |

### get_gemini_tools()

```python
def get_gemini_tools()
```
Get tool definitions in Gemini format.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/hitl ===

# Human-in-the-Loop

## Subpages
- **Integrations > Human-in-the-Loop > Classes**
- **Integrations > Human-in-the-Loop > Packages**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/hitl/classes ===

# Classes

| Class | Description |
|-|-|
| **Integrations > Human-in-the-Loop > Packages > flyteplugins.hitl > Event** |An event that waits for human input via an embedded FastAPI app. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/hitl/packages ===

# Packages

| Package | Description |
|-|-|
| **Integrations > Human-in-the-Loop > Packages > flyteplugins.hitl** | Human-in-the-Loop (HITL) plugin for Flyte. |

## Subpages
- **Integrations > Human-in-the-Loop > Packages > flyteplugins.hitl**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/hitl/packages/flyteplugins.hitl ===

# flyteplugins.hitl

Human-in-the-Loop (HITL) plugin for Flyte.

This plugin provides an event-based API for pausing workflows and waiting for human input.

## Basic usage:

```python
import flyte
import flyteplugins.hitl as hitl

task_env = flyte.TaskEnvironment(
    name="my-hitl-workflow",
    image=flyte.Image.from_debian_base(python_version=(3, 12)),
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    depends_on=[hitl.env],
)

@task_env.task(report=True)
async def main() -> int:
    # Create an event (this serves the app if not already running)
    event = await hitl.new_event.aio(
        "integer_input_event",
        data_type=int,
        scope="run",
        prompt="What should I add to x?",
    )
    y = await event.wait.aio()
    return y
```

## Features:

- Event-based API for human-in-the-loop workflows
- Web form for human input
- Programmatic API for automated input
- Support for int, float, str, and bool data types
- Crash-resilient polling with object storage
## Directory

### Classes

| Class | Description |
|-|-|
| **Integrations > Human-in-the-Loop > Packages > flyteplugins.hitl > Event** | An event that waits for human input via an embedded FastAPI app. |

### Methods

| Method | Description |
|-|-|
| **Integrations > Human-in-the-Loop > Packages > flyteplugins.hitl > Methods > new_event()** | Create a new human-in-the-loop event. |

### Variables

| Property | Type | Description |
|-|-|-|
| `env` | `TaskEnvironment` |  |

## Methods

#### new_event()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await new_event.aio()`.
```python
def new_event(
    name: str,
    data_type: Type[T],
    scope: EventScope,
    prompt: str,
    timeout_seconds: int,
    poll_interval_seconds: int,
) -> Event[T]
```
Create a new human-in-the-loop event.

This is a convenience function that wraps Event.create().

| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | A descriptive name for the event (used in logs and UI) |
| `data_type` | `Type[T]` | The expected type of the input (int, float, str, bool) |
| `scope` | `EventScope` | The scope of the event. Currently only "run" is supported. |
| `prompt` | `str` | The prompt to display to the human |
| `timeout_seconds` | `int` | Maximum time to wait for human input (default: 1 hour) |
| `poll_interval_seconds` | `int` | How often to check for a response (default: 5 seconds) |

**Returns**

An Event object that can be used to wait for the human input

## Subpages
- **Integrations > Human-in-the-Loop > Packages > flyteplugins.hitl > Event**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/hitl/packages/flyteplugins.hitl/event ===

# Event

**Package:** `flyteplugins.hitl`

An event that waits for human input via an embedded FastAPI app.

This class encapsulates the entire HITL functionality:
- Creates and serves a FastAPI app for receiving human input
- Provides endpoints for form-based and JSON-based submission
- Polls object storage for responses using durable sleep (crash-resilient)

The app is automatically served when the Event is created via `Event.create()`.
All infrastructure details (AppEnvironment, deployment) are abstracted away.

## Parameters

```python
class Event(
    name: str,
    scope: EventScope,
    data_type: Type[T],
    prompt: str,
    request_id: str,
    endpoint: str,
    request_path: str,
    response_path: str,
    timeout_seconds: int,
    poll_interval_seconds: int,
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |
| `scope` | `EventScope` | |
| `data_type` | `Type[T]` | |
| `prompt` | `str` | |
| `request_id` | `str` | |
| `endpoint` | `str` | |
| `request_path` | `str` | |
| `response_path` | `str` | |
| `timeout_seconds` | `int` | |
| `poll_interval_seconds` | `int` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `api_url` | `None` | API endpoint for programmatic submission. |
| `endpoint` | `None` | Base endpoint of the HITL app. |
| `form_url` | `None` | URL where humans can submit input for this event. |

## Methods

| Method | Description |
|-|-|
| **Integrations > Human-in-the-Loop > Packages > flyteplugins.hitl > Event > Methods > create()** | Create a new human-in-the-loop event and serve the app. |
| **Integrations > Human-in-the-Loop > Packages > flyteplugins.hitl > Event > Methods > wait()** | Wait for human input and return the result. |

### create()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Event.create.aio()`.
```python
def create(
    cls,
    name: str,
    data_type: Type[T],
    scope: EventScope,
    prompt: str,
    timeout_seconds: int,
    poll_interval_seconds: int,
) -> 'Event[T]'
```
Create a new human-in-the-loop event and serve the app.

This method creates an event that waits for human input via the FastAPI app.
The app is automatically served if not already running. All infrastructure
details are abstracted away - you just get an event to wait on.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | A descriptive name for the event (used in logs and UI) |
| `data_type` | `Type[T]` | The expected type of the input (int, float, str, bool) |
| `scope` | `EventScope` | The scope of the event. Currently only "run" is supported. |
| `prompt` | `str` | The prompt to display to the human |
| `timeout_seconds` | `int` | Maximum time to wait for human input (default: 1 hour) |
| `poll_interval_seconds` | `int` | How often to check for a response (default: 5 seconds) |

**Returns**

An Event object that can be used to wait for the human input

### wait()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await <Event instance>.wait.aio()`.
```python
def wait()
```
Wait for human input and return the result.

This method polls object storage for a response using durable sleep,
making it crash-resilient. If the task crashes and restarts, it will
resume polling from where it left off.

**Returns**

The value provided by the human, converted to the event's data_type

**Raises**

| Exception | Description |
|-|-|
| `TimeoutError` | If no response is received within the timeout |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/jsonl ===

# JSONL

## Subpages
- **Integrations > JSONL > Classes**
- **Integrations > JSONL > Packages**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/jsonl/classes ===

# Classes

| Class | Description |
|-|-|
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir** |A directory of sharded JSONL files. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile** |A file type for JSONL (JSON Lines) files, backed by `orjson` for fast. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/jsonl/packages ===

# Packages

| Package | Description |
|-|-|
| **Integrations > JSONL > Packages > flyteplugins.jsonl** |  |

## Subpages
- **Integrations > JSONL > Packages > flyteplugins.jsonl**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/jsonl/packages/flyteplugins.jsonl ===

# flyteplugins.jsonl

## Directory

### Classes

| Class | Description |
|-|-|
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir** | A directory of sharded JSONL files. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile** | A file type for JSONL (JSON Lines) files, backed by `orjson` for fast. |

## Subpages
- **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir**
- **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/jsonl/packages/flyteplugins.jsonl/jsonldir ===

# JsonlDir

**Package:** `flyteplugins.jsonl`

A directory of sharded JSONL files.

Provides transparent iteration across shards on read and automatic shard
rotation on write. Inherits all `Dir` capabilities (remote storage,
walk, download, etc.).

Shard files are named `part-00000.jsonl` (or `.jsonl.zst` for
compressed shards), zero-padded to 5 digits and sorted alphabetically
on read. Mixed compression within a single directory is supported.

Example (Async read)::

    @env.task
    async def process(d: JsonlDir):
        async for record in d.iter_records():
            print(record)

Example (Async write)::

    @env.task
    async def create() -&gt; JsonlDir:
        d = JsonlDir.new_remote("output_shards")
        async with d.writer(max_records_per_shard=1000) as w:
            for i in range(5000):
                await w.write({"id": i})
        return d

## Parameters

```python
class JsonlDir(
    path: str,
    name: typing.Optional[str],
    format: str,
    hash: typing.Optional[str],
)
```
Create a new model by parsing and validating input data from keyword arguments.

Raises [`ValidationError`](https://docs.pydantic.dev/latest/api/pydantic_core/#pydantic_core.ValidationError) if the input data cannot be
validated to form a valid model.

`self` is explicitly positional-only to allow `self` as a field name.

| Parameter | Type | Description |
|-|-|-|
| `path` | `str` | |
| `name` | `typing.Optional[str]` | |
| `format` | `str` | |
| `hash` | `typing.Optional[str]` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `lazy_uploader` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > download()** | Asynchronously download the entire directory to a local path. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > download_sync()** | Synchronously download the entire directory to a local path. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > exists()** | Asynchronously check if the directory exists. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > exists_sync()** | Synchronously check if the directory exists. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > from_existing_remote()** | Create a Dir reference from an existing remote directory. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > from_local()** | Asynchronously create a new Dir by uploading a local directory to remote storage. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > from_local_sync()** | Synchronously create a new Dir by uploading a local directory to remote storage. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > get_file()** | Asynchronously get a specific file from the directory by name. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > get_file_sync()** | Synchronously get a specific file from the directory by name. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > iter_arrow_batches()** | Async generator that yields Arrow RecordBatches across all shards. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > iter_arrow_batches_sync()** | Sync generator that yields Arrow RecordBatches across all shards. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > iter_batches()** | Async generator that yields lists of records in batches. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > iter_batches_sync()** | Sync generator that yields lists of records in batches. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > iter_records()** | Async generator that yields records from all shards in sorted order. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > iter_records_sync()** | Sync generator that yields records from all shards in sorted order. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > list_files()** | Asynchronously get a list of all files in the directory (non-recursive). |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > list_files_sync()** | Synchronously get a list of all files in the directory (non-recursive). |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > model_post_init()** | This function is meant to behave like a BaseModel method to initialise private attributes. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > new_remote()** | Create a new Dir reference for a remote directory that will be written to. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > pre_init()** | Internal: Pydantic validator to set default name from path. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > schema_match()** | Internal: Check if incoming schema matches Dir schema. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > walk()** | Asynchronously walk through the directory and yield File objects. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > walk_sync()** | Synchronously walk through the directory and yield File objects. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > writer()** | Async context manager returning a `JsonlDirWriter`. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlDir > Methods > writer_sync()** | Sync context manager returning a `JsonlDirWriterSync`. |

### download()

```python
def download(
    local_path: Optional[Union[str, Path]],
) -> str
```
Asynchronously download the entire directory to a local path.

Use this when you need to download all files in a directory to your local filesystem for processing.

Example (Async):

```python
@env.task
async def download_directory(d: Dir) -> str:
    local_dir = await d.download()
    # Process files in the local directory
    return local_dir
```

Example (Async - Download to specific path):

```python
@env.task
async def download_to_path(d: Dir) -> str:
    local_dir = await d.download("/tmp/my_data/")
    return local_dir
```

| Parameter | Type | Description |
|-|-|-|
| `local_path` | `Optional[Union[str, Path]]` | The local path to download the directory to. If None, a temporary directory will be used and a path will be generated. |

**Returns:** The absolute path to the downloaded directory

### download_sync()

```python
def download_sync(
    local_path: Optional[Union[str, Path]],
) -> str
```
Synchronously download the entire directory to a local path.

Use this in non-async tasks when you need to download all files in a directory to your local filesystem.

Example (Sync):

```python
@env.task
def download_directory_sync(d: Dir) -> str:
    local_dir = d.download_sync()
    # Process files in the local directory
    return local_dir
```

Example (Sync - Download to specific path):

```python
@env.task
def download_to_path_sync(d: Dir) -> str:
    local_dir = d.download_sync("/tmp/my_data/")
    return local_dir
```

| Parameter | Type | Description |
|-|-|-|
| `local_path` | `Optional[Union[str, Path]]` | The local path to download the directory to. If None, a temporary directory will be used and a path will be generated. |

**Returns:** The absolute path to the downloaded directory

### exists()

```python
def exists()
```
Asynchronously check if the directory exists.

Example (Async):

```python
@env.task
async def check_directory(d: Dir) -> bool:
    if await d.exists():
        print("Directory exists!")
        return True
    return False
```

**Returns**

True if the directory exists, False otherwise

### exists_sync()

```python
def exists_sync()
```
Synchronously check if the directory exists.

Use this in non-async tasks or when you need synchronous directory existence checking.

Example (Sync):

```python
@env.task
def check_directory_sync(d: Dir) -> bool:
    if d.exists_sync():
        print("Directory exists!")
        return True
    return False
```

**Returns**

True if the directory exists, False otherwise

### from_existing_remote()

```python
def from_existing_remote(
    remote_path: str,
    dir_cache_key: Optional[str],
) -> Dir[T]
```
Create a Dir reference from an existing remote directory.

Use this when you want to reference a directory that already exists in remote storage without uploading it.

```python
@env.task
async def process_existing_directory() -> int:
    d = Dir.from_existing_remote("s3://my-bucket/data/")
    files = await d.list_files()
    return len(files)
```

Example (With cache key):

```python
@env.task
async def process_with_cache_key() -> int:
    d = Dir.from_existing_remote("s3://my-bucket/data/", dir_cache_key="abc123")
    files = await d.list_files()
    return len(files)
```

| Parameter | Type | Description |
|-|-|-|
| `remote_path` | `str` | The remote path to the existing directory |
| `dir_cache_key` | `Optional[str]` | Optional hash value to use for cache key computation. If not specified, the cache key will be computed based on the directory's attributes. |

**Returns:** A new Dir instance pointing to the existing remote directory

### from_local()

```python
def from_local(
    local_path: Union[str, Path],
    remote_destination: Optional[str],
    dir_cache_key: Optional[str],
    batch_size: Optional[int],
) -> Dir[T]
```
Asynchronously create a new Dir by uploading a local directory to remote storage.

Use this in async tasks when you have a local directory that needs to be uploaded to remote storage.

Example (Async):

```python
@env.task
async def upload_local_directory() -> Dir:
    # Create a local directory with files
    os.makedirs("/tmp/data_dir", exist_ok=True)
    with open("/tmp/data_dir/file1.txt", "w") as f:
        f.write("data1")

    # Upload to remote storage
    remote_dir = await Dir.from_local("/tmp/data_dir/")
    return remote_dir
```

Example (Async - With specific destination):

```python
@env.task
async def upload_to_specific_path() -> Dir:
    remote_dir = await Dir.from_local("/tmp/data_dir/", "s3://my-bucket/data/")
    return remote_dir
```

Example (Async - With cache key):

```python
@env.task
async def upload_with_cache_key() -> Dir:
    remote_dir = await Dir.from_local("/tmp/data_dir/", dir_cache_key="my_cache_key_123")
    return remote_dir
```

| Parameter | Type | Description |
|-|-|-|
| `local_path` | `Union[str, Path]` | Path to the local directory |
| `remote_destination` | `Optional[str]` | Optional remote path to store the directory. If None, a path will be automatically generated. |
| `dir_cache_key` | `Optional[str]` | Optional precomputed hash value to use for cache key computation when this Dir is used as an input to discoverable tasks. If not specified, the cache key will be based on directory attributes. |
| `batch_size` | `Optional[int]` | Optional concurrency limit for uploading files. If not specified, the default value is determined by the FLYTE_IO_BATCH_SIZE environment variable (default: 32). |

**Returns:** A new Dir instance pointing to the uploaded directory

### from_local_sync()

```python
def from_local_sync(
    local_path: Union[str, Path],
    remote_destination: Optional[str],
    dir_cache_key: Optional[str],
) -> Dir[T]
```
Synchronously create a new Dir by uploading a local directory to remote storage.

Use this in non-async tasks when you have a local directory that needs to be uploaded to remote storage.

Example (Sync):

```python
@env.task
def upload_local_directory_sync() -> Dir:
    # Create a local directory with files
    os.makedirs("/tmp/data_dir", exist_ok=True)
    with open("/tmp/data_dir/file1.txt", "w") as f:
        f.write("data1")

    # Upload to remote storage
    remote_dir = Dir.from_local_sync("/tmp/data_dir/")
    return remote_dir
```

Example (Sync - With specific destination):

```python
@env.task
def upload_to_specific_path_sync() -> Dir:
    remote_dir = Dir.from_local_sync("/tmp/data_dir/", "s3://my-bucket/data/")
    return remote_dir
```

Example (Sync - With cache key):

```python
@env.task
def upload_with_cache_key_sync() -> Dir:
    remote_dir = Dir.from_local_sync("/tmp/data_dir/", dir_cache_key="my_cache_key_123")
    return remote_dir
```

| Parameter | Type | Description |
|-|-|-|
| `local_path` | `Union[str, Path]` | Path to the local directory |
| `remote_destination` | `Optional[str]` | Optional remote path to store the directory. If None, a path will be automatically generated. |
| `dir_cache_key` | `Optional[str]` | Optional precomputed hash value to use for cache key computation when this Dir is used as an input to discoverable tasks. If not specified, the cache key will be based on directory attributes. |

**Returns:** A new Dir instance pointing to the uploaded directory

### get_file()

```python
def get_file(
    file_name: str,
) -> Optional[File[T]]
```
Asynchronously get a specific file from the directory by name.

Use this when you know the name of a specific file in the directory you want to access.

Example (Async):

```python
@env.task
async def read_specific_file(d: Dir) -> str:
    file = await d.get_file("data.csv")
    if file:
        async with file.open("rb") as f:
            content = await f.read()
            return content.decode("utf-8")
    return "File not found"
```

| Parameter | Type | Description |
|-|-|-|
| `file_name` | `str` | The name of the file to get |

**Returns:** A File instance if the file exists, None otherwise

### get_file_sync()

```python
def get_file_sync(
    file_name: str,
) -> Optional[File[T]]
```
Synchronously get a specific file from the directory by name.

Use this in non-async tasks when you know the name of a specific file in the directory you want to access.

Example (Sync):

```python
@env.task
def read_specific_file_sync(d: Dir) -> str:
    file = d.get_file_sync("data.csv")
    if file:
        with file.open_sync("rb") as f:
            content = f.read()
            return content.decode("utf-8")
    return "File not found"
```

| Parameter | Type | Description |
|-|-|-|
| `file_name` | `str` | The name of the file to get |

**Returns:** A File instance if the file exists, None otherwise

### iter_arrow_batches()

```python
def iter_arrow_batches(
    batch_size: int,
    on_error: Literal['raise', 'skip'] | ErrorHandler,
) -> AsyncGenerator[Any, None]
```
Async generator that yields Arrow RecordBatches across all shards.

| Parameter | Type | Description |
|-|-|-|
| `batch_size` | `int` | Max records per RecordBatch (default 65536). |
| `on_error` | `Literal['raise', 'skip'] \| ErrorHandler` | `"raise"` (default), `"skip"`, or a callable. |

### iter_arrow_batches_sync()

```python
def iter_arrow_batches_sync(
    batch_size: int,
    on_error: Literal['raise', 'skip'] | ErrorHandler,
) -> Generator[Any, None, None]
```
Sync generator that yields Arrow RecordBatches across all shards.

| Parameter | Type | Description |
|-|-|-|
| `batch_size` | `int` | Max records per RecordBatch (default 65536). |
| `on_error` | `Literal['raise', 'skip'] \| ErrorHandler` | `"raise"` (default), `"skip"`, or a callable. |

### iter_batches()

```python
def iter_batches(
    batch_size: int,
    on_error: Literal['raise', 'skip'] | ErrorHandler,
    prefetch: bool,
    queue_size: int,
) -> AsyncGenerator[list[dict[str, Any]], None]
```
Async generator that yields lists of records in batches.

| Parameter | Type | Description |
|-|-|-|
| `batch_size` | `int` | Max records per batch (default 1000). |
| `on_error` | `Literal['raise', 'skip'] \| ErrorHandler` | `"raise"` (default), `"skip"`, or a callable. |
| `prefetch` | `bool` | Overlap next-shard I/O with current-shard processing. |
| `queue_size` | `int` | Memory safety bound on the read-ahead buffer. |

### iter_batches_sync()

```python
def iter_batches_sync(
    batch_size: int,
    on_error: Literal['raise', 'skip'] | ErrorHandler,
) -> Generator[list[dict[str, Any]], None, None]
```
Sync generator that yields lists of records in batches.

| Parameter | Type | Description |
|-|-|-|
| `batch_size` | `int` | Max records per batch (default 1000). |
| `on_error` | `Literal['raise', 'skip'] \| ErrorHandler` | `"raise"` (default), `"skip"`, or a callable. |

### iter_records()

```python
def iter_records(
    on_error: Literal['raise', 'skip'] | ErrorHandler,
    prefetch: bool,
    queue_size: int,
) -> AsyncGenerator[dict[str, Any], None]
```
Async generator that yields records from all shards in sorted order.

When *prefetch* is True (default), the next shard is read into a
bounded queue concurrently while the current shard is being yielded.
This overlaps network I/O with processing without buffering more
than one shard in memory.

| Parameter | Type | Description |
|-|-|-|
| `on_error` | `Literal['raise', 'skip'] \| ErrorHandler` | `"raise"` (default), `"skip"`, or a callable `(line_number, raw_line, exception) -&gt; None`. |
| `prefetch` | `bool` | Overlap next-shard network I/O with current-shard processing for higher throughput. |
| `queue_size` | `int` | Memory safety bound on the read-ahead buffer (default 8192). |

### iter_records_sync()

```python
def iter_records_sync(
    on_error: Literal['raise', 'skip'] | ErrorHandler,
) -> Generator[dict[str, Any], None, None]
```
Sync generator that yields records from all shards in sorted order.

| Parameter | Type | Description |
|-|-|-|
| `on_error` | `Literal['raise', 'skip'] \| ErrorHandler` | |

### list_files()

```python
def list_files()
```
Asynchronously get a list of all files in the directory (non-recursive).

Use this when you need a list of all files in the top-level directory at once.

Example (Async):

```python
@env.task
async def count_files(d: Dir) -> int:
    files = await d.list_files()
    return len(files)
```

Example (Async - Process files):

```python
@env.task
async def process_all_files(d: Dir) -> list[str]:
    files = await d.list_files()
    contents = []
    for file in files:
        async with file.open("rb") as f:
            content = await f.read()
            contents.append(content.decode("utf-8"))
    return contents
```

**Returns**

A list of File objects for files in the top-level directory

### list_files_sync()

```python
def list_files_sync()
```
Synchronously get a list of all files in the directory (non-recursive).

Use this in non-async tasks when you need a list of all files in the top-level directory at once.

Example (Sync):

```python
@env.task
def count_files_sync(d: Dir) -> int:
    files = d.list_files_sync()
    return len(files)
```

Example (Sync - Process files):

```python
@env.task
def process_all_files_sync(d: Dir) -> list[str]:
    files = d.list_files_sync()
    contents = []
    for file in files:
        with file.open_sync("rb") as f:
            content = f.read()
            contents.append(content.decode("utf-8"))
    return contents
```

**Returns**

A list of File objects for files in the top-level directory

### model_post_init()

```python
def model_post_init(
    context: Any,
)
```
This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that's what pydantic-core passes when calling it.

| Parameter | Type | Description |
|-|-|-|
| `context` | `Any` | The context. |

### new_remote()

```python
def new_remote(
    dir_name: Optional[str],
    hash: Optional[str],
) -> Dir[T]
```
Create a new Dir reference for a remote directory that will be written to.

Use this when you want to create a new directory and write files into it
directly without creating a local directory first.

| Parameter | Type | Description |
|-|-|-|
| `dir_name` | `Optional[str]` | Optional name for the remote directory. If not set, a generated name will be used. |
| `hash` | `Optional[str]` | Optional precomputed hash value to use for cache key computation when this Dir is used as an input to discoverable tasks. |

**Returns:** A new Dir instance with a generated remote path.

### pre_init()

```python
def pre_init(
    data,
)
```
Internal: Pydantic validator to set default name from path. Not intended for direct use.

| Parameter | Type | Description |
|-|-|-|
| `data` |  | |

### schema_match()

```python
def schema_match(
    incoming: dict,
)
```
Internal: Check if incoming schema matches Dir schema. Not intended for direct use.

| Parameter | Type | Description |
|-|-|-|
| `incoming` | `dict` | |

### walk()

```python
def walk(
    recursive: bool,
    max_depth: Optional[int],
) -> AsyncIterator[File[T]]
```
Asynchronously walk through the directory and yield File objects.

Use this to iterate through all files in a directory. Each yielded File can be read directly without
downloading.

Example (Async - Recursive):

```python
@env.task
async def list_all_files(d: Dir) -> list[str]:
    file_names = []
    async for file in d.walk(recursive=True):
        file_names.append(file.name)
    return file_names
```

Example (Async - Non-recursive):

```python
@env.task
async def list_top_level_files(d: Dir) -> list[str]:
    file_names = []
    async for file in d.walk(recursive=False):
        file_names.append(file.name)
    return file_names
```

Example (Async - With max depth):

```python
@env.task
async def list_files_max_depth(d: Dir) -> list[str]:
    file_names = []
    async for file in d.walk(recursive=True, max_depth=2):
        file_names.append(file.name)
    return file_names
```

Yields:
    File objects for each file found in the directory

| Parameter | Type | Description |
|-|-|-|
| `recursive` | `bool` | If True, recursively walk subdirectories. If False, only list files in the top-level directory. |
| `max_depth` | `Optional[int]` | Maximum depth for recursive walking. If None, walk through all subdirectories. |

### walk_sync()

```python
def walk_sync(
    recursive: bool,
    file_pattern: str,
    max_depth: Optional[int],
) -> Iterator[File[T]]
```
Synchronously walk through the directory and yield File objects.

Use this in non-async tasks to iterate through all files in a directory.

Example (Sync - Recursive):

```python
@env.task
def list_all_files_sync(d: Dir) -> list[str]:
    file_names = []
    for file in d.walk_sync(recursive=True):
        file_names.append(file.name)
    return file_names
```

Example (Sync - With file pattern):

```python
@env.task
def list_text_files(d: Dir) -> list[str]:
    file_names = []
    for file in d.walk_sync(recursive=True, file_pattern="*.txt"):
        file_names.append(file.name)
    return file_names
```

Example (Sync - Non-recursive with max depth):

```python
@env.task
def list_files_limited(d: Dir) -> list[str]:
    file_names = []
    for file in d.walk_sync(recursive=True, max_depth=2):
        file_names.append(file.name)
    return file_names
```

Yields:
    File objects for each file found in the directory

| Parameter | Type | Description |
|-|-|-|
| `recursive` | `bool` | If True, recursively walk subdirectories. If False, only list files in the top-level directory. |
| `file_pattern` | `str` | Glob pattern to filter files (e.g., "*.txt", "*.csv"). Default is "*" (all files). |
| `max_depth` | `Optional[int]` | Maximum depth for recursive walking. If None, walk through all subdirectories. |

### writer()

```python
def writer(
    shard_extension: str,
    max_records_per_shard: int | None,
    max_bytes_per_shard: int,
    flush_bytes: int,
    compression_level: int,
) -> AsyncGenerator[JsonlDirWriter, None]
```
Async context manager returning a `JsonlDirWriter`.

Scans the directory for existing shards and starts writing from the
next available index, so appending to an existing directory is safe.

| Parameter | Type | Description |
|-|-|-|
| `shard_extension` | `str` | File extension (e.g. `.jsonl` or `.jsonl.zst`). |
| `max_records_per_shard` | `int \| None` | Roll after this many records (None = no limit). |
| `max_bytes_per_shard` | `int` | Roll after this many uncompressed bytes (default 256 MB). |
| `flush_bytes` | `int` | Buffer flush threshold in bytes (default 1 MB). |
| `compression_level` | `int` | Zstd level (default 3, only for `.jsonl.zst`). |

### writer_sync()

```python
def writer_sync(
    shard_extension: str,
    max_records_per_shard: int | None,
    max_bytes_per_shard: int,
    flush_bytes: int,
    compression_level: int,
) -> Generator[JsonlDirWriterSync, None, None]
```
Sync context manager returning a `JsonlDirWriterSync`.

See `writer` for argument descriptions.

| Parameter | Type | Description |
|-|-|-|
| `shard_extension` | `str` | |
| `max_records_per_shard` | `int \| None` | |
| `max_bytes_per_shard` | `int` | |
| `flush_bytes` | `int` | |
| `compression_level` | `int` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/jsonl/packages/flyteplugins.jsonl/jsonlfile ===

# JsonlFile

**Package:** `flyteplugins.jsonl`

A file type for JSONL (JSON Lines) files, backed by `orjson` for fast
serialisation.

Provides streaming read and write methods that process one record at a time
without loading the entire file into memory. Inherits all `File`
capabilities (remote storage, upload/download, etc.).

Supports zstd-compressed files transparently via extension detection
(`.jsonl.zst` / `.jsonl.zstd`).

Example (Async read - compressed or uncompressed):

```python
@env.task
async def process(f: JsonlFile):
    async for record in f.iter_records():
        print(record)
```

Example (Async write - compressed or uncompressed):

```python
@env.task
async def create() -> JsonlFile:
    f = JsonlFile.new_remote("data.jsonl")
    async with f.writer() as w:
        await w.write({"key": "value"})
    return f
```

Example (Sync write - compressed or uncompressed):

```python
@env.task
def create() -> JsonlFile:
    f = JsonlFile.new_remote("data.jsonl")
    with f.writer_sync() as w:
        w.write({"key": "value"})
    return f
```

## Parameters

```python
class JsonlFile(
    path: str,
    name: typing.Optional[str],
    format: str,
    hash: typing.Optional[str],
    hash_method: typing.Optional[flyte.io._hashing_io.HashMethod],
)
```
Create a new model by parsing and validating input data from keyword arguments.

Raises [`ValidationError`](https://docs.pydantic.dev/latest/api/pydantic_core/#pydantic_core.ValidationError) if the input data cannot be
validated to form a valid model.

`self` is explicitly positional-only to allow `self` as a field name.

| Parameter | Type | Description |
|-|-|-|
| `path` | `str` | |
| `name` | `typing.Optional[str]` | |
| `format` | `str` | |
| `hash` | `typing.Optional[str]` | |
| `hash_method` | `typing.Optional[flyte.io._hashing_io.HashMethod]` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `lazy_uploader` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile > Methods > download()** | Asynchronously download the file to a local path. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile > Methods > download_sync()** | Synchronously download the file to a local path. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile > Methods > exists()** | Asynchronously check if the file exists. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile > Methods > exists_sync()** | Synchronously check if the file exists. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile > Methods > from_existing_remote()** | Create a File reference from an existing remote file. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile > Methods > from_local()** | Asynchronously create a new File object from a local file by uploading it to remote storage. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile > Methods > from_local_sync()** | Synchronously create a new File object from a local file by uploading it to remote storage. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile > Methods > iter_arrow_batches()** | Stream JSONL as Arrow RecordBatches. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile > Methods > iter_arrow_batches_sync()** | Sync generator that yields Arrow RecordBatches. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile > Methods > iter_records()** | Async generator that yields parsed dicts line by line. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile > Methods > iter_records_sync()** | Sync generator that yields parsed dicts line by line. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile > Methods > model_post_init()** | This function is meant to behave like a BaseModel method to initialise private attributes. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile > Methods > named_remote()** | Create a File reference whose remote path is derived deterministically from *name*. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile > Methods > new_remote()** | Create a new File reference for a remote file that will be written to. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile > Methods > open()** | Asynchronously open the file and return a file-like object. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile > Methods > open_sync()** | Synchronously open the file and return a file-like object. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile > Methods > pre_init()** | Internal: Pydantic validator to set default name from path. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile > Methods > schema_match()** | Internal: Check if incoming schema matches File schema. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile > Methods > writer()** | Async context manager returning a `JsonlWriter` for streaming writes. |
| **Integrations > JSONL > Packages > flyteplugins.jsonl > JsonlFile > Methods > writer_sync()** | Sync context manager returning a `JsonlWriterSync` for streaming writes. |

### download()

```python
def download(
    local_path: Optional[Union[str, Path]],
) -> str
```
Asynchronously download the file to a local path.

Use this when you need to download a remote file to your local filesystem for processing.

Example (Async):

```python
@env.task
async def download_and_process(f: File) -> str:
    local_path = await f.download()
    # Now process the local file
    with open(local_path, "r") as fh:
        return fh.read()
```

Example (Download to specific path):

```python
@env.task
async def download_to_path(f: File) -> str:
    local_path = await f.download("/tmp/myfile.csv")
    return local_path
```

| Parameter | Type | Description |
|-|-|-|
| `local_path` | `Optional[Union[str, Path]]` | The local path to download the file to. If None, a temporary directory will be used and a path will be generated. |

**Returns:** The absolute path to the downloaded file

### download_sync()

```python
def download_sync(
    local_path: Optional[Union[str, Path]],
) -> str
```
Synchronously download the file to a local path.

Use this in non-async tasks when you need to download a remote file to your local filesystem.

Example (Sync):

```python
@env.task
def download_and_process_sync(f: File) -> str:
    local_path = f.download_sync()
    # Now process the local file
    with open(local_path, "r") as fh:
        return fh.read()
```

Example (Download to specific path):

```python
@env.task
def download_to_path_sync(f: File) -> str:
    local_path = f.download_sync("/tmp/myfile.csv")
    return local_path
```

| Parameter | Type | Description |
|-|-|-|
| `local_path` | `Optional[Union[str, Path]]` | The local path to download the file to. If None, a temporary directory will be used and a path will be generated. |

**Returns:** The absolute path to the downloaded file

### exists()

```python
def exists()
```
Asynchronously check if the file exists.

Example (Async):

```python
@env.task
async def check_file(f: File) -> bool:
    if await f.exists():
        print("File exists!")
        return True
    return False
```

**Returns:** True if the file exists, False otherwise

### exists_sync()

```python
def exists_sync()
```
Synchronously check if the file exists.

Use this in non-async tasks or when you need synchronous file existence checking.

Example (Sync):

```python
@env.task
def check_file_sync(f: File) -> bool:
    if f.exists_sync():
        print("File exists!")
        return True
    return False
```

**Returns:** True if the file exists, False otherwise

### from_existing_remote()

```python
def from_existing_remote(
    remote_path: str,
    file_cache_key: Optional[str],
) -> File[T]
```
Create a File reference from an existing remote file.

Use this when you want to reference a file that already exists in remote storage without uploading it.

```python
@env.task
async def process_existing_file() -> str:
    file = File.from_existing_remote("s3://my-bucket/data.csv")
    async with file.open("rb") as f:
        content = await f.read()
    return content.decode("utf-8")
```

| Parameter | Type | Description |
|-|-|-|
| `remote_path` | `str` | The remote path to the existing file |
| `file_cache_key` | `Optional[str]` | Optional hash value to use for cache key computation. If not specified, the cache key will be computed based on the file's attributes (path, name, format). |

**Returns:** A new File instance pointing to the existing remote file

### from_local()

```python
def from_local(
    local_path: Union[str, Path],
    remote_destination: Optional[str],
    hash_method: Optional[HashMethod | str],
) -> File[T]
```
Asynchronously create a new File object from a local file by uploading it to remote storage.

        Use this in async tasks when you have a local file that needs to be uploaded to remote storage.

        Example (Async):

        ```python
        @env.task
        async def upload_local_file() -> File:
            # Create a local file
            async with aiofiles.open("/tmp/data.csv", "w") as f:
                await f.write("col1,col2
1,2
3,4
")

            # Upload to remote storage
            remote_file = await File.from_local("/tmp/data.csv")
            return remote_file
        ```

        Example (With specific destination):

        ```python
        @env.task
        async def upload_to_specific_path() -> File:
            remote_file = await File.from_local("/tmp/data.csv", "s3://my-bucket/data.csv")
            return remote_file
        ```

        Args:
            local_path: Path to the local file
            remote_destination: Optional remote path to store the file. If None, a path will be automatically generated.
            hash_method: Optional HashMethod or string to use for cache key computation. If a string is provided,
                        it will be used as a precomputed cache key. If a HashMethod is provided, it will compute
                        the hash during upload. If not specified, the cache key will be based on file attributes.

        Returns:
            A new File instance pointing to the uploaded remote file
        
| Parameter | Type | Description |
|-|-|-|
| `local_path` | `Union[str, Path]` | |
| `remote_destination` | `Optional[str]` | |
| `hash_method` | `Optional[HashMethod \| str]` | |

### from_local_sync()

```python
def from_local_sync(
    local_path: Union[str, Path],
    remote_destination: Optional[str],
    hash_method: Optional[HashMethod | str],
) -> File[T]
```
Synchronously create a new File object from a local file by uploading it to remote storage.

        Use this in non-async tasks when you have a local file that needs to be uploaded to remote storage.

        Example (Sync):

        ```python
        @env.task
        def upload_local_file_sync() -> File:
            # Create a local file
            with open("/tmp/data.csv", "w") as f:
                f.write("col1,col2
1,2
3,4
")

            # Upload to remote storage
            remote_file = File.from_local_sync("/tmp/data.csv")
            return remote_file
        ```

        Example (With specific destination):

        ```python
        @env.task
        def upload_to_specific_path() -> File:
            remote_file = File.from_local_sync("/tmp/data.csv", "s3://my-bucket/data.csv")
            return remote_file
        ```

        Args:
            local_path: Path to the local file
            remote_destination: Optional remote path to store the file. If None, a path will be automatically generated.
            hash_method: Optional HashMethod or string to use for cache key computation. If a string is provided,
                        it will be used as a precomputed cache key. If a HashMethod is provided, it will compute
                        the hash during upload. If not specified, the cache key will be based on file attributes.

        Returns:
            A new File instance pointing to the uploaded remote file
        
| Parameter | Type | Description |
|-|-|-|
| `local_path` | `Union[str, Path]` | |
| `remote_destination` | `Optional[str]` | |
| `hash_method` | `Optional[HashMethod \| str]` | |

### iter_arrow_batches()

```python
def iter_arrow_batches(
    batch_size: int,
    on_error: Literal['raise', 'skip'] | ErrorHandler,
) -> AsyncGenerator[Any, None]
```
Stream JSONL as Arrow RecordBatches.

Memory usage is bounded by batch_size.

| Parameter | Type | Description |
|-|-|-|
| `batch_size` | `int` | |
| `on_error` | `Literal['raise', 'skip'] \| ErrorHandler` | |

### iter_arrow_batches_sync()

```python
def iter_arrow_batches_sync(
    batch_size: int,
    on_error: Literal['raise', 'skip'] | ErrorHandler,
) -> Generator[Any, None, None]
```
Sync generator that yields Arrow RecordBatches.

Memory usage is bounded by batch_size.

| Parameter | Type | Description |
|-|-|-|
| `batch_size` | `int` | |
| `on_error` | `Literal['raise', 'skip'] \| ErrorHandler` | |

### iter_records()

```python
def iter_records(
    on_error: Literal['raise', 'skip'] | ErrorHandler,
) -> AsyncGenerator[dict[str, Any], None]
```
Async generator that yields parsed dicts line by line.

| Parameter | Type | Description |
|-|-|-|
| `on_error` | `Literal['raise', 'skip'] \| ErrorHandler` | |

### iter_records_sync()

```python
def iter_records_sync(
    on_error: Literal['raise', 'skip'] | ErrorHandler,
) -> Generator[dict[str, Any], None, None]
```
Sync generator that yields parsed dicts line by line.

| Parameter | Type | Description |
|-|-|-|
| `on_error` | `Literal['raise', 'skip'] \| ErrorHandler` | |

### model_post_init()

```python
def model_post_init(
    context: Any,
)
```
This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that's what pydantic-core passes when calling it.

| Parameter | Type | Description |
|-|-|-|
| `context` | `Any` | The context. |

### named_remote()

```python
def named_remote(
    name: str,
) -> File[T]
```
Create a File reference whose remote path is derived deterministically from *name*.

Unlike `new_remote`, which generates a random path on every call, this method
produces the same path for the same *name* within a given task execution. This makes
it safe across retries: the first attempt uploads to the path and subsequent retries
resolve to the identical location without re-uploading.

The path is optionally namespaced by the node ID extracted from the backend
raw-data path, which follows the convention:

    {run_name}-{node_id}-{attempt_index}

If extraction fails, the function falls back to the run base directory alone.

| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | Plain filename (e.g., "data.csv"). Must not contain path separators. |

**Returns:** A `File` instance whose path is stable across retries.

### new_remote()

```python
def new_remote(
    file_name: Optional[str],
    hash_method: Optional[HashMethod | str],
) -> File[T]
```
Create a new File reference for a remote file that will be written to.

Use this when you want to create a new file and write to it directly without creating a local file first.

Example (Async):

```python
@env.task
async def create_csv() -> File:
    df = pd.DataFrame({"col1": [1, 2], "col2": [3, 4]})
    file = File.new_remote()
    async with file.open("wb") as f:
        df.to_csv(f)
    return file
```

| Parameter | Type | Description |
|-|-|-|
| `file_name` | `Optional[str]` | Optional string specifying a remote file name. If not set, a generated file name will be returned. |
| `hash_method` | `Optional[HashMethod \| str]` | Optional HashMethod or string to use for cache key computation. If a string is provided, it will be used as a precomputed cache key. If a HashMethod is provided, it will be used to compute the hash as data is written. |

**Returns:** A new File instance with a generated remote path

### open()

```python
def open(
    mode: str,
    block_size: Optional[int],
    cache_type: str,
    cache_options: Optional[dict],
    compression: Optional[str],
    kwargs,
) -> AsyncGenerator[Union[AsyncWritableFile, AsyncReadableFile, 'HashingWriter'], None]
```
Asynchronously open the file and return a file-like object.

Use this method in async tasks to read from or write to files directly.

Example (Async Read):

```python
@env.task
async def read_file(f: File) -> str:
    async with f.open("rb") as fh:
        content = bytes(await fh.read())
        return content.decode("utf-8")
```

Example (Async Write):

```python
@env.task
async def write_file() -> File:
    f = File.new_remote()
    async with f.open("wb") as fh:
        await fh.write(b"Hello, World!")
    return f
```

Example (Streaming Read):

```python
@env.task
async def stream_read(f: File) -> str:
    content_parts = []
    async with f.open("rb", block_size=1024) as fh:
        while True:
            chunk = await fh.read()
            if not chunk:
                break
            content_parts.append(chunk)
    return b"".join(content_parts).decode("utf-8")
```

| Parameter | Type | Description |
|-|-|-|
| `mode` | `str` | The mode to open the file in (default: 'rb'). Common modes: 'rb' (read binary), 'wb' (write binary), 'rt' (read text), 'wt' (write text) |
| `block_size` | `Optional[int]` | Size of blocks for reading in bytes. Useful for streaming large files. |
| `cache_type` | `str` | Caching mechanism to use ('readahead', 'mmap', 'bytes', 'none') |
| `cache_options` | `Optional[dict]` | Dictionary of options for the cache |
| `compression` | `Optional[str]` | Compression format or None for auto-detection |
| `kwargs` | `**kwargs` | |

**Returns:** An async file-like object that can be used with async read/write operations

### open_sync()

```python
def open_sync(
    mode: str,
    block_size: Optional[int],
    cache_type: str,
    cache_options: Optional[dict],
    compression: Optional[str],
    kwargs,
) -> Generator[IO[Any], None, None]
```
Synchronously open the file and return a file-like object.

Use this method in non-async tasks to read from or write to files directly.

Example (Sync Read):

```python
@env.task
def read_file_sync(f: File) -> str:
    with f.open_sync("rb") as fh:
        content = fh.read()
        return content.decode("utf-8")
```

Example (Sync Write):

```python
@env.task
def write_file_sync() -> File:
    f = File.new_remote()
    with f.open_sync("wb") as fh:
        fh.write(b"Hello, World!")
    return f
```

| Parameter | Type | Description |
|-|-|-|
| `mode` | `str` | The mode to open the file in (default: 'rb'). Common modes: 'rb' (read binary), 'wb' (write binary), 'rt' (read text), 'wt' (write text) |
| `block_size` | `Optional[int]` | Size of blocks for reading in bytes. Useful for streaming large files. |
| `cache_type` | `str` | Caching mechanism to use ('readahead', 'mmap', 'bytes', 'none') |
| `cache_options` | `Optional[dict]` | Dictionary of options for the cache |
| `compression` | `Optional[str]` | Compression format or None for auto-detection |
| `kwargs` | `**kwargs` | |

**Returns:** A file-like object that can be used with standard read/write operations

### pre_init()

```python
def pre_init(
    data,
)
```
Internal: Pydantic validator to set default name from path. Not intended for direct use.

| Parameter | Type | Description |
|-|-|-|
| `data` |  | |

### schema_match()

```python
def schema_match(
    incoming: dict,
)
```
Internal: Check if incoming schema matches File schema. Not intended for direct use.

| Parameter | Type | Description |
|-|-|-|
| `incoming` | `dict` | |

### writer()

```python
def writer(
    flush_bytes: int,
    compression_level: int,
) -> AsyncGenerator[JsonlWriter, None]
```
Async context manager returning a `JsonlWriter` for streaming writes.

If the file path ends in `.jsonl.zst`, output is zstd-compressed.

| Parameter | Type | Description |
|-|-|-|
| `flush_bytes` | `int` | Buffer flush threshold in bytes (default 1 MB). |
| `compression_level` | `int` | Zstd compression level (default 3). Only used for `.jsonl.zst` paths. Higher = smaller files, slower writes. |

### writer_sync()

```python
def writer_sync(
    flush_bytes: int,
    compression_level: int,
) -> Generator[JsonlWriterSync, None, None]
```
Sync context manager returning a `JsonlWriterSync` for streaming writes.

If the file path ends in `.jsonl.zst`, output is zstd-compressed.

| Parameter | Type | Description |
|-|-|-|
| `flush_bytes` | `int` | Buffer flush threshold in bytes (default 1 MB). |
| `compression_level` | `int` | Zstd compression level (default 3). Only used for `.jsonl.zst` paths. Higher = smaller files, slower writes. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/mlflow ===

# MLflow

## Subpages
- **Integrations > MLflow > Classes**
- **Integrations > MLflow > Packages**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/mlflow/classes ===

# Classes

| Class | Description |
|-|-|
| **Integrations > MLflow > Packages > flyteplugins.mlflow > Mlflow** |MLflow UI link for Flyte tasks. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/mlflow/packages ===

# Packages

| Package | Description |
|-|-|
| **Integrations > MLflow > Packages > flyteplugins.mlflow** | ## Key features:. |

## Subpages
- **Integrations > MLflow > Packages > flyteplugins.mlflow**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/mlflow/packages/flyteplugins.mlflow ===

# flyteplugins.mlflow

## Key features:

- Automatic MLflow run management with `@mlflow_run` decorator
- Built-in autologging support via `autolog=True` parameter
- Auto-generated MLflow UI links via `link_host` config and the `Mlflow` link class
- Parent/child task support with run sharing
- Distributed training support (only rank 0 logs to MLflow)
- Configuration management with `mlflow_config()`

## Basic usage:

1. Manual logging with `@mlflow_run`:

   ```python
   from flyteplugins.mlflow import mlflow_run, get_mlflow_run

   @mlflow_run(
       tracking_uri="http://localhost:5000",
       experiment_name="my-experiment",
       tags={"team": "ml"},
   )
   @env.task
   async def train_model(learning_rate: float) -> str:
       import mlflow

       mlflow.log_param("lr", learning_rate)
       mlflow.log_metric("loss", 0.5)

       run = get_mlflow_run()
       return run.info.run_id
   ```

2. Automatic logging with `@mlflow_run(autolog=True)`:

   ```python
   from flyteplugins.mlflow import mlflow_run

   @mlflow_run(
       autolog=True,
       framework="sklearn",
       tracking_uri="http://localhost:5000",
       log_models=True,
       log_datasets=False,
       experiment_id="846992856162999",
   )
   @env.task
   async def train_sklearn_model():
       from sklearn.linear_model import LogisticRegression

       model = LogisticRegression()
       model.fit(X, y)  # Autolog captures parameters, metrics, and model
   ```

3. Workflow-level configuration with `mlflow_config()`:

   ```python
   from flyteplugins.mlflow import mlflow_config

   r = flyte.with_runcontext(
       custom_context=mlflow_config(
           tracking_uri="http://localhost:5000",
           experiment_id="846992856162999",
           tags={"team": "ml"},
       )
   ).run(train_model, learning_rate=0.001)
   ```

4. Per-task config overrides with context manager:

   ```python
   @mlflow_run
   @env.task
   async def parent_task():
       # Override config for a specific child task
       with mlflow_config(run_mode="new", tags={"role": "child"}):
           await child_task()
   ```

5. Run modes — control run creation vs sharing:

   ```python
   @mlflow_run                      # "auto": new run if no parent, else share parent's
   @mlflow_run(run_mode="new")      # Always create a new run
   ```

6. HPO — objective can be a Flyte task with `run_mode="new"`:

   ```python
   @mlflow_run(run_mode="new")
   @env.task
   def objective(params: dict) -> float:
       mlflow.log_params(params)
       loss = train(params)
       mlflow.log_metric("loss", loss)
       return loss
   ```

7. Distributed training (only rank 0 logs):

   ```python
   @mlflow_run  # Auto-detects rank from RANK env var
   @env.task
   async def distributed_train():
       ...
   ```

8. MLflow UI links — auto-generated via `link_host`:

   ```python
   from flyteplugins.mlflow import Mlflow, mlflow_config

   # Set link_host at workflow level — children with Mlflow() link
   # auto-get the URL after the parent creates the run.
   r = flyte.with_runcontext(
       custom_context=mlflow_config(
           tracking_uri="http://localhost:5000",
           link_host="http://localhost:5000",
       )
   ).run(parent_task)

   # Attach the link to child tasks:
   @mlflow_run
   @env.task(links=[Mlflow()])
   async def child_task(): ...

   # Custom URL template (e.g. Databricks):
   mlflow_config(
       link_host="https://dbc-xxx.cloud.databricks.com",
       link_template="{host}/ml/experiments/{experiment_id}/runs/{run_id}",
   )
   ```

Decorator order: `@mlflow_run` must be outermost (before `@env.task`):

```python
@mlflow_run
@env.task
async def my_task(): ...

@mlflow_run(autolog=True, framework="sklearn")
@env.task
async def my_task(): ...
```
## Directory

### Classes

| Class | Description |
|-|-|
| **Integrations > MLflow > Packages > flyteplugins.mlflow > Mlflow** | MLflow UI link for Flyte tasks. |

### Methods

| Method | Description |
|-|-|
| **Integrations > MLflow > Packages > flyteplugins.mlflow > Methods > get_mlflow_context()** | Retrieve current MLflow configuration from Flyte context. |
| **Integrations > MLflow > Packages > flyteplugins.mlflow > Methods > get_mlflow_run()** | Get the current MLflow run if within a `@mlflow_run` decorated task or trace. |
| **Integrations > MLflow > Packages > flyteplugins.mlflow > Methods > mlflow_config()** | Create MLflow configuration. |
| **Integrations > MLflow > Packages > flyteplugins.mlflow > Methods > mlflow_run()** | Decorator to manage MLflow runs for Flyte tasks and plain functions. |

## Methods

#### get_mlflow_context()

```python
def get_mlflow_context()
```
Retrieve current MLflow configuration from Flyte context.

#### get_mlflow_run()

```python
def get_mlflow_run()
```
Get the current MLflow run if within a `@mlflow_run` decorated task or trace.

The run is started when the `@mlflow_run` decorator enters.
Returns None if not within an `mlflow_run` context.

**Returns:** `mlflow.ActiveRun` | `None`: The current MLflow active run or None.

#### mlflow_config()

```python
def mlflow_config(
    tracking_uri: typing.Optional[str],
    experiment_name: typing.Optional[str],
    experiment_id: typing.Optional[str],
    run_name: typing.Optional[str],
    run_id: typing.Optional[str],
    tags: typing.Optional[dict[str, str]],
    run_mode: typing.Literal['auto', 'new', 'nested'],
    autolog: bool,
    framework: typing.Optional[str],
    log_models: typing.Optional[bool],
    log_datasets: typing.Optional[bool],
    autolog_kwargs: typing.Optional[dict[str, typing.Any]],
    link_host: typing.Optional[str],
    link_template: typing.Optional[str],
    kwargs: **kwargs,
) -> flyteplugins.mlflow._context._MLflowConfig
```
Create MLflow configuration.

Works in two contexts:
1. With `flyte.with_runcontext()` for global configuration
2. As a context manager to override configuration

| Parameter | Type | Description |
|-|-|-|
| `tracking_uri` | `typing.Optional[str]` | MLflow tracking server URI. |
| `experiment_name` | `typing.Optional[str]` | MLflow experiment name. |
| `experiment_id` | `typing.Optional[str]` | MLflow experiment ID. |
| `run_name` | `typing.Optional[str]` | Human-readable run name. |
| `run_id` | `typing.Optional[str]` | Explicit MLflow run ID. |
| `tags` | `typing.Optional[dict[str, str]]` | MLflow run tags. |
| `run_mode` | `typing.Literal['auto', 'new', 'nested']` | Flyte-specific run mode ("auto", "new", "nested"). |
| `autolog` | `bool` | Enable MLflow autologging. |
| `framework` | `typing.Optional[str]` | Framework-specific autolog (e.g. "sklearn", "pytorch"). |
| `log_models` | `typing.Optional[bool]` | Whether to log models automatically. |
| `log_datasets` | `typing.Optional[bool]` | Whether to log datasets automatically. |
| `autolog_kwargs` | `typing.Optional[dict[str, typing.Any]]` | Extra parameters passed to mlflow.autolog(). |
| `link_host` | `typing.Optional[str]` | MLflow UI host for auto-generating task links. |
| `link_template` | `typing.Optional[str]` | Custom URL template. Defaults to standard MLflow UI format. Available placeholders: `{host}`, `{experiment_id}`, `{run_id}`. |
| `kwargs` | `**kwargs` | |

#### mlflow_run()

```python
def mlflow_run(
    _func: typing.Optional[~F],
    run_mode: typing.Literal['auto', 'new', 'nested'],
    tracking_uri: typing.Optional[str],
    experiment_name: typing.Optional[str],
    experiment_id: typing.Optional[str],
    run_name: typing.Optional[str],
    run_id: typing.Optional[str],
    tags: typing.Optional[dict[str, str]],
    autolog: bool,
    framework: typing.Optional[str],
    log_models: typing.Optional[bool],
    log_datasets: typing.Optional[bool],
    autolog_kwargs: typing.Optional[dict[str, typing.Any]],
    rank: typing.Optional[int],
    kwargs,
) -> ~F
```
Decorator to manage MLflow runs for Flyte tasks and plain functions.

Handles both manual logging and autologging. For autologging, pass
`autolog=True` and optionally `framework` to select a specific
framework (e.g. `"sklearn"`).

Decorator Order:
    @mlflow_run must be the outermost decorator::

        @mlflow_run
        @env.task
        async def my_task():
            ...

| Parameter | Type | Description |
|-|-|-|
| `_func` | `typing.Optional[~F]` | |
| `run_mode` | `typing.Literal['auto', 'new', 'nested']` | "auto" (default), "new", or "nested". - "auto": reuse parent run if available, else create new. - "new": always create a new independent run. - "nested": create a new run nested under the parent via   `mlflow.parentRunId` tag. Works across processes/containers. |
| `tracking_uri` | `typing.Optional[str]` | MLflow tracking server URL. |
| `experiment_name` | `typing.Optional[str]` | MLflow experiment name (exclusive with experiment_id). |
| `experiment_id` | `typing.Optional[str]` | MLflow experiment ID (exclusive with experiment_name). |
| `run_name` | `typing.Optional[str]` | Human-readable run name (exclusive with run_id). |
| `run_id` | `typing.Optional[str]` | MLflow run ID (exclusive with run_name). |
| `tags` | `typing.Optional[dict[str, str]]` | Dictionary of tags for the run. |
| `autolog` | `bool` | Enable MLflow autologging. |
| `framework` | `typing.Optional[str]` | MLflow framework name for autolog (e.g. "sklearn", "pytorch"). |
| `log_models` | `typing.Optional[bool]` | Whether to log models automatically (requires autolog). |
| `log_datasets` | `typing.Optional[bool]` | Whether to log datasets automatically (requires autolog). |
| `autolog_kwargs` | `typing.Optional[dict[str, typing.Any]]` | Extra parameters passed to `mlflow.autolog()`. |
| `rank` | `typing.Optional[int]` | Process rank for distributed training (only rank 0 logs). |
| `kwargs` | `**kwargs` | |

## Subpages
- **Integrations > MLflow > Packages > flyteplugins.mlflow > Mlflow**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/mlflow/packages/flyteplugins.mlflow/mlflow ===

# Mlflow

**Package:** `flyteplugins.mlflow`

MLflow UI link for Flyte tasks.

Resolves the link URL from one of two sources (in priority order):

1. **Explicit link** — set at definition or override time::

       @env.task(links=[Mlflow(link="https://mlflow.example.com/...")])

       task.override(links=[Mlflow(link="https://...")])()

2. **Context link** — auto-generated from `link_host` (and optional
   `link_template`) set via `mlflow_config()`. Propagates to child
   tasks that share or nest under the parent's run. Cleared when a task
   creates an independent run (`run_mode="new"`). For nested runs
   (`run_mode="nested"`), the parent link is kept and the link name
   is automatically set to "MLflow (parent)".

## Parameters

```python
class Mlflow(
    name: str,
    link: str,
    _decorator_run_mode: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |
| `link` | `str` | |
| `_decorator_run_mode` | `str` | |

## Methods

| Method | Description |
|-|-|
| **Integrations > MLflow > Packages > flyteplugins.mlflow > Mlflow > Methods > get_link()** | Returns a task log link given the action. |

### get_link()

```python
def get_link(
    run_name: str,
    project: str,
    domain: str,
    context: dict[str, str],
    parent_action_name: str,
    action_name: str,
    pod_name: str,
    kwargs,
) -> str
```
Returns a task log link given the action.
Link can have template variables that are replaced by the backend.

| Parameter | Type | Description |
|-|-|-|
| `run_name` | `str` | The name of the run. |
| `project` | `str` | The project name. |
| `domain` | `str` | The domain name. |
| `context` | `dict[str, str]` | Additional context for generating the link. |
| `parent_action_name` | `str` | The name of the parent action. |
| `action_name` | `str` | The name of the action. |
| `pod_name` | `str` | The name of the pod. |
| `kwargs` | `**kwargs` | Additional keyword arguments. |

**Returns:** The generated link.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/openai ===

# OpenAI

## Subpages
- [flyteplugins.openai.agents](flyteplugins.openai.agents/)


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/polars ===

# Polars

## Subpages
- **Integrations > Polars > Classes**
- **Integrations > Polars > Packages**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/polars/classes ===

# Classes

| Class | Description |
|-|-|
| **Integrations > Polars > Packages > flyteplugins.polars.df_transformer > ParquetToPolarsDecodingHandler** | |
| **Integrations > Polars > Packages > flyteplugins.polars.df_transformer > ParquetToPolarsLazyFrameDecodingHandler** | |
| **Integrations > Polars > Packages > flyteplugins.polars.df_transformer > PolarsLazyFrameToParquetEncodingHandler** | |
| **Integrations > Polars > Packages > flyteplugins.polars.df_transformer > PolarsToParquetEncodingHandler** | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/polars/packages ===

# Packages

| Package | Description |
|-|-|
| **Integrations > Polars > Packages > flyteplugins.polars.df_transformer** |  |

## Subpages
- **Integrations > Polars > Packages > flyteplugins.polars.df_transformer**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/polars/packages/flyteplugins.polars.df_transformer ===

# flyteplugins.polars.df_transformer

## Directory

### Classes

| Class | Description |
|-|-|
| **Integrations > Polars > Packages > flyteplugins.polars.df_transformer > ParquetToPolarsDecodingHandler** |  |
| **Integrations > Polars > Packages > flyteplugins.polars.df_transformer > ParquetToPolarsLazyFrameDecodingHandler** |  |
| **Integrations > Polars > Packages > flyteplugins.polars.df_transformer > PolarsLazyFrameToParquetEncodingHandler** |  |
| **Integrations > Polars > Packages > flyteplugins.polars.df_transformer > PolarsToParquetEncodingHandler** |  |

### Methods

| Method | Description |
|-|-|
| **Integrations > Polars > Packages > flyteplugins.polars.df_transformer > Methods > get_polars_storage_options()** | Get storage options in a format compatible with Polars. |

### Variables

| Property | Type | Description |
|-|-|-|
| `PARQUET` | `str` |  |

## Methods

#### get_polars_storage_options()

```python
def get_polars_storage_options(
    protocol: typing.Optional[str],
    anonymous: bool,
) -> typing.Dict[str, str]
```
Get storage options in a format compatible with Polars.

Polars requires storage_options to be a flat dict with string keys and values,
unlike fsspec which accepts nested dicts and complex objects.

| Parameter | Type | Description |
|-|-|-|
| `protocol` | `typing.Optional[str]` | |
| `anonymous` | `bool` | |

## Subpages
- **Integrations > Polars > Packages > flyteplugins.polars.df_transformer > ParquetToPolarsDecodingHandler**
- **Integrations > Polars > Packages > flyteplugins.polars.df_transformer > ParquetToPolarsLazyFrameDecodingHandler**
- **Integrations > Polars > Packages > flyteplugins.polars.df_transformer > PolarsLazyFrameToParquetEncodingHandler**
- **Integrations > Polars > Packages > flyteplugins.polars.df_transformer > PolarsToParquetEncodingHandler**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/polars/packages/flyteplugins.polars.df_transformer/parquettopolarsdecodinghandler ===

# ParquetToPolarsDecodingHandler

**Package:** `flyteplugins.polars.df_transformer`

## Parameters

```python
def ParquetToPolarsDecodingHandler()
```
Extend this abstract class, implement the decode function, and register your concrete class with the
DataFrameTransformerEngine class in order for the core flytekit type engine to handle
dataframe libraries. This is the decoder interface, meaning it is used when there is a Flyte Literal value,
and we have to get a Python value out of it. For the other way, see the DataFrameEncoder

## Properties

| Property | Type | Description |
|-|-|-|
| `protocol` | `None` |  |
| `python_type` | `None` |  |
| `supported_format` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Integrations > Polars > Packages > flyteplugins.polars.df_transformer > ParquetToPolarsDecodingHandler > Methods > decode()** | This is code that will be called by the dataset transformer engine to ultimately translate from a Flyte Literal. |

### decode()

```python
def decode(
    flyte_value: flyteidl2.core.literals_pb2.StructuredDataset,
    current_task_metadata: flyteidl2.core.literals_pb2.StructuredDatasetMetadata,
) -> pl.DataFrame
```
This is code that will be called by the dataset transformer engine to ultimately translate from a Flyte Literal
value into a Python instance.

    of those dataframes.

| Parameter | Type | Description |
|-|-|-|
| `flyte_value` | `flyteidl2.core.literals_pb2.StructuredDataset` | This will be a Flyte IDL DataFrame Literal - do not confuse this with the DataFrame class defined also in this module. |
| `current_task_metadata` | `flyteidl2.core.literals_pb2.StructuredDatasetMetadata` | Metadata object containing the type (and columns if any) for the currently executing task. This type may have more or less information than the type information bundled inside the incoming flyte_value. |

**Returns:** This function can either return an instance of the dataframe that this decoder handles, or an iterator


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/polars/packages/flyteplugins.polars.df_transformer/parquettopolarslazyframedecodinghandler ===

# ParquetToPolarsLazyFrameDecodingHandler

**Package:** `flyteplugins.polars.df_transformer`

## Parameters

```python
def ParquetToPolarsLazyFrameDecodingHandler()
```
Extend this abstract class, implement the decode function, and register your concrete class with the
DataFrameTransformerEngine class in order for the core flytekit type engine to handle
dataframe libraries. This is the decoder interface, meaning it is used when there is a Flyte Literal value,
and we have to get a Python value out of it. For the other way, see the DataFrameEncoder

## Properties

| Property | Type | Description |
|-|-|-|
| `protocol` | `None` |  |
| `python_type` | `None` |  |
| `supported_format` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Integrations > Polars > Packages > flyteplugins.polars.df_transformer > ParquetToPolarsLazyFrameDecodingHandler > Methods > decode()** | This is code that will be called by the dataset transformer engine to ultimately translate from a Flyte Literal. |

### decode()

```python
def decode(
    flyte_value: flyteidl2.core.literals_pb2.StructuredDataset,
    current_task_metadata: flyteidl2.core.literals_pb2.StructuredDatasetMetadata,
) -> pl.LazyFrame
```
This is code that will be called by the dataset transformer engine to ultimately translate from a Flyte Literal
value into a Python instance.

    of those dataframes.

| Parameter | Type | Description |
|-|-|-|
| `flyte_value` | `flyteidl2.core.literals_pb2.StructuredDataset` | This will be a Flyte IDL DataFrame Literal - do not confuse this with the DataFrame class defined also in this module. |
| `current_task_metadata` | `flyteidl2.core.literals_pb2.StructuredDatasetMetadata` | Metadata object containing the type (and columns if any) for the currently executing task. This type may have more or less information than the type information bundled inside the incoming flyte_value. |

**Returns:** This function can either return an instance of the dataframe that this decoder handles, or an iterator


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/polars/packages/flyteplugins.polars.df_transformer/polarslazyframetoparquetencodinghandler ===

# PolarsLazyFrameToParquetEncodingHandler

**Package:** `flyteplugins.polars.df_transformer`

## Parameters

```python
def PolarsLazyFrameToParquetEncodingHandler()
```
Extend this abstract class, implement the encode function, and register your concrete class with the
DataFrameTransformerEngine class in order for the core flytekit type engine to handle
dataframe libraries. This is the encoding interface, meaning it is used when there is a Python value that the
flytekit type engine is trying to convert into a Flyte Literal. For the other way, see
the DataFrameEncoder

## Properties

| Property | Type | Description |
|-|-|-|
| `protocol` | `None` |  |
| `python_type` | `None` |  |
| `supported_format` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Integrations > Polars > Packages > flyteplugins.polars.df_transformer > PolarsLazyFrameToParquetEncodingHandler > Methods > encode()** | Even if the user code returns a plain dataframe instance, the dataset transformer engine will wrap the. |

### encode()

```python
def encode(
    dataframe: flyte.io._dataframe.dataframe.DataFrame,
    structured_dataset_type: flyteidl2.core.types_pb2.StructuredDatasetType,
) -> flyteidl2.core.literals_pb2.StructuredDataset
```
Even if the user code returns a plain dataframe instance, the dataset transformer engine will wrap the
incoming dataframe with defaults set for that dataframe
type. This simplifies this function's interface as a lot of data that could be specified by the user using
the
# TODO: Do we need to add a flag to indicate if it was wrapped by the transformer or by the user?

  DataFrame wrapper class used as input to this function - that is the user facing Python class.
  This function needs to return the IDL DataFrame.

| Parameter | Type | Description |
|-|-|-|
| `dataframe` | `flyte.io._dataframe.dataframe.DataFrame` | This is a DataFrame wrapper object. See more info above. |
| `structured_dataset_type` | `flyteidl2.core.types_pb2.StructuredDatasetType` | This the DataFrameType, as found in the LiteralType of the interface of the task that invoked this encoding call. It is passed along to encoders so that authors of encoders can include it in the returned literals.DataFrame. See the IDL for more information on why this literal in particular carries the type information along with it. If the encoder doesn't supply it, it will also be filled in after the encoder runs by the transformer engine. |

**Returns:** This function should return a DataFrame literal object. Do not confuse this with the


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/polars/packages/flyteplugins.polars.df_transformer/polarstoparquetencodinghandler ===

# PolarsToParquetEncodingHandler

**Package:** `flyteplugins.polars.df_transformer`

## Parameters

```python
def PolarsToParquetEncodingHandler()
```
Extend this abstract class, implement the encode function, and register your concrete class with the
DataFrameTransformerEngine class in order for the core flytekit type engine to handle
dataframe libraries. This is the encoding interface, meaning it is used when there is a Python value that the
flytekit type engine is trying to convert into a Flyte Literal. For the other way, see
the DataFrameEncoder

## Properties

| Property | Type | Description |
|-|-|-|
| `protocol` | `None` |  |
| `python_type` | `None` |  |
| `supported_format` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Integrations > Polars > Packages > flyteplugins.polars.df_transformer > PolarsToParquetEncodingHandler > Methods > encode()** | Even if the user code returns a plain dataframe instance, the dataset transformer engine will wrap the. |

### encode()

```python
def encode(
    dataframe: flyte.io._dataframe.dataframe.DataFrame,
    structured_dataset_type: flyteidl2.core.types_pb2.StructuredDatasetType,
) -> flyteidl2.core.literals_pb2.StructuredDataset
```
Even if the user code returns a plain dataframe instance, the dataset transformer engine will wrap the
incoming dataframe with defaults set for that dataframe
type. This simplifies this function's interface as a lot of data that could be specified by the user using
the
# TODO: Do we need to add a flag to indicate if it was wrapped by the transformer or by the user?

  DataFrame wrapper class used as input to this function - that is the user facing Python class.
  This function needs to return the IDL DataFrame.

| Parameter | Type | Description |
|-|-|-|
| `dataframe` | `flyte.io._dataframe.dataframe.DataFrame` | This is a DataFrame wrapper object. See more info above. |
| `structured_dataset_type` | `flyteidl2.core.types_pb2.StructuredDatasetType` | This the DataFrameType, as found in the LiteralType of the interface of the task that invoked this encoding call. It is passed along to encoders so that authors of encoders can include it in the returned literals.DataFrame. See the IDL for more information on why this literal in particular carries the type information along with it. If the encoder doesn't supply it, it will also be filled in after the encoder runs by the transformer engine. |

**Returns:** This function should return a DataFrame literal object. Do not confuse this with the


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/pytorch ===

# PyTorch

## Subpages
- **Integrations > PyTorch > Classes**
- **Integrations > PyTorch > Packages**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/pytorch/classes ===

# Classes

| Class | Description |
|-|-|
| **Integrations > PyTorch > Packages > flyteplugins.pytorch > Elastic** |Elastic defines the configuration for running a PyTorch elastic job using torch. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/pytorch/packages ===

# Packages

| Package | Description |
|-|-|
| **Integrations > PyTorch > Packages > flyteplugins.pytorch** |  |

## Subpages
- **Integrations > PyTorch > Packages > flyteplugins.pytorch**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/pytorch/packages/flyteplugins.pytorch ===

# flyteplugins.pytorch

## Directory

### Classes

| Class | Description |
|-|-|
| **Integrations > PyTorch > Packages > flyteplugins.pytorch > Elastic** | Elastic defines the configuration for running a PyTorch elastic job using torch. |

## Subpages
- **Integrations > PyTorch > Packages > flyteplugins.pytorch > Elastic**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/pytorch/packages/flyteplugins.pytorch/elastic ===

# Elastic

**Package:** `flyteplugins.pytorch`

Elastic defines the configuration for running a PyTorch elastic job using torch.distributed.

When a worker fails (e.g. CUDA OOM), the elastic agent detects the failure and
restarts all workers as a group. Each restart cycle has a cost determined by the
NCCL timeout settings below. The total worst-case time before the job fails is::

    (max_restarts + 1) * (nccl_collective_timeout_sec + nccl_heartbeat_timeout_sec)

For example, with defaults (max_restarts=3, collective=600s, heartbeat=300s):
4 * 900s = 60 min. With aggressive settings (max_restarts=0, collective=60s,
heartbeat=60s): 1 * 120s = 2 min.

## Parameters

```python
class Elastic(
    nnodes: typing.Union[int, str],
    nproc_per_node: int,
    rdzv_backend: typing.Literal['c10d', 'etcd', 'etcd-v2'],
    run_policy: typing.Optional[flyteplugins.pytorch.task.RunPolicy],
    monitor_interval: int,
    max_restarts: int,
    rdzv_configs: typing.Dict[str, typing.Any],
    nccl_heartbeat_timeout_sec: typing.Optional[int],
    nccl_async_error_handling: bool,
    nccl_collective_timeout_sec: typing.Optional[int],
    nccl_enable_monitoring: bool,
)
```
| Parameter | Type | Description |
|-|-|-|
| `nnodes` | `typing.Union[int, str]` | Number of nodes to use. Can be a fixed int or a range string (e.g., "2:4" for elastic training). |
| `nproc_per_node` | `int` | Number of processes to launch per node. |
| `rdzv_backend` | `typing.Literal['c10d', 'etcd', 'etcd-v2']` | Rendezvous backend to use. Typically "c10d". Defaults to "c10d". |
| `run_policy` | `typing.Optional[flyteplugins.pytorch.task.RunPolicy]` | Run policy applied to the job execution. Defaults to None. |
| `monitor_interval` | `int` | Interval (in seconds) the elastic agent polls worker process health. Once a worker process exits, detection takes at most this long. Defaults to 3. |
| `max_restarts` | `int` | Maximum number of worker group restarts before the elastic agent gives up and raises `ChildFailedError`. Each restart kills all workers and relaunches the entire group. If the failure is deterministic (e.g. model too large for GPU memory), restarts just repeat the same failure — set to 0 to fail immediately. Use higher values for transient failures (e.g. spot instance preemption, occasional OOM from variable batch sizes). Defaults to 3. |
| `rdzv_configs` | `typing.Dict[str, typing.Any]` | Rendezvous configuration key-value pairs. Defaults to {"timeout": 900, "join_timeout": 900}. |
| `nccl_heartbeat_timeout_sec` | `typing.Optional[int]` | Timeout in seconds for the NCCL heartbeat monitor thread. After the collective timeout fires and the NCCL watchdog aborts the communicator, the heartbeat monitor waits this long before sending SIGABRT to kill the worker process. This is the second phase of failure detection — it converts a stuck NCCL abort into a hard process kill. Defaults to 300 (5 min) instead of PyTorch's 1800s (30 min). Set to None to use PyTorch default. |
| `nccl_async_error_handling` | `bool` | When True, sets TORCH_NCCL_ASYNC_ERROR_HANDLING=1 so that NCCL aborts stuck collectives asynchronously instead of blocking indefinitely. This causes the worker process to crash-exit on a stuck collective, which the elastic agent detects within `monitor_interval` seconds (~3s by default) — much faster than waiting for the heartbeat timeout. Defaults to False (PyTorch default behavior). |
| `nccl_collective_timeout_sec` | `typing.Optional[int]` | Timeout in seconds for individual NCCL collective operations (e.g. all-reduce inside loss.backward()). This is the timeout passed to `torch.distributed.init_process_group`. When a worker desyncs (e.g. skips a collective after OOM), surviving workers block in the collective for this long before the NCCL watchdog fires. This is the first phase of failure detection. PyTorch default is 600s (10 min). Set to None to use PyTorch default. |
| `nccl_enable_monitoring` | `bool` | When True, sets TORCH_NCCL_ENABLE_MONITORING=1 to activate NCCL's built-in monitoring thread. The monitoring thread checks each worker's heartbeat counter and sends SIGABRT when it stalls, which is what drives `nccl_heartbeat_timeout_sec`. Defaults to True. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/ray ===

# Ray

## Subpages
- **Integrations > Ray > Classes**
- **Integrations > Ray > Packages**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/ray/classes ===

# Classes

| Class | Description |
|-|-|
| **Integrations > Ray > Packages > flyteplugins.ray > HeadNodeConfig** | |
| **Integrations > Ray > Packages > flyteplugins.ray > RayJobConfig** | |
| **Integrations > Ray > Packages > flyteplugins.ray > WorkerNodeConfig** | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/ray/packages ===

# Packages

| Package | Description |
|-|-|
| **Integrations > Ray > Packages > flyteplugins.ray** |  |

## Subpages
- **Integrations > Ray > Packages > flyteplugins.ray**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/ray/packages/flyteplugins.ray ===

# flyteplugins.ray

## Directory

### Classes

| Class | Description |
|-|-|
| **Integrations > Ray > Packages > flyteplugins.ray > HeadNodeConfig** |  |
| **Integrations > Ray > Packages > flyteplugins.ray > RayJobConfig** |  |
| **Integrations > Ray > Packages > flyteplugins.ray > WorkerNodeConfig** |  |

## Subpages
- **Integrations > Ray > Packages > flyteplugins.ray > HeadNodeConfig**
- **Integrations > Ray > Packages > flyteplugins.ray > RayJobConfig**
- **Integrations > Ray > Packages > flyteplugins.ray > WorkerNodeConfig**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/ray/packages/flyteplugins.ray/headnodeconfig ===

# HeadNodeConfig

**Package:** `flyteplugins.ray`

## Parameters

```python
class HeadNodeConfig(
    ray_start_params: typing.Optional[typing.Dict[str, str]],
    pod_template: typing.Optional[flyte._pod.PodTemplate],
    requests: typing.Optional[flyte._resources.Resources],
    limits: typing.Optional[flyte._resources.Resources],
)
```
| Parameter | Type | Description |
|-|-|-|
| `ray_start_params` | `typing.Optional[typing.Dict[str, str]]` | |
| `pod_template` | `typing.Optional[flyte._pod.PodTemplate]` | |
| `requests` | `typing.Optional[flyte._resources.Resources]` | |
| `limits` | `typing.Optional[flyte._resources.Resources]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/ray/packages/flyteplugins.ray/rayjobconfig ===

# RayJobConfig

**Package:** `flyteplugins.ray`

## Parameters

```python
class RayJobConfig(
    worker_node_config: typing.List[flyteplugins.ray.task.WorkerNodeConfig],
    head_node_config: typing.Optional[flyteplugins.ray.task.HeadNodeConfig],
    enable_autoscaling: bool,
    runtime_env: typing.Optional[dict],
    address: typing.Optional[str],
    shutdown_after_job_finishes: bool,
    ttl_seconds_after_finished: typing.Optional[int],
)
```
| Parameter | Type | Description |
|-|-|-|
| `worker_node_config` | `typing.List[flyteplugins.ray.task.WorkerNodeConfig]` | |
| `head_node_config` | `typing.Optional[flyteplugins.ray.task.HeadNodeConfig]` | |
| `enable_autoscaling` | `bool` | |
| `runtime_env` | `typing.Optional[dict]` | |
| `address` | `typing.Optional[str]` | |
| `shutdown_after_job_finishes` | `bool` | |
| `ttl_seconds_after_finished` | `typing.Optional[int]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/ray/packages/flyteplugins.ray/workernodeconfig ===

# WorkerNodeConfig

**Package:** `flyteplugins.ray`

## Parameters

```python
class WorkerNodeConfig(
    group_name: str,
    replicas: int,
    min_replicas: typing.Optional[int],
    max_replicas: typing.Optional[int],
    ray_start_params: typing.Optional[typing.Dict[str, str]],
    pod_template: typing.Optional[flyte._pod.PodTemplate],
    requests: typing.Optional[flyte._resources.Resources],
    limits: typing.Optional[flyte._resources.Resources],
)
```
| Parameter | Type | Description |
|-|-|-|
| `group_name` | `str` | |
| `replicas` | `int` | |
| `min_replicas` | `typing.Optional[int]` | |
| `max_replicas` | `typing.Optional[int]` | |
| `ray_start_params` | `typing.Optional[typing.Dict[str, str]]` | |
| `pod_template` | `typing.Optional[flyte._pod.PodTemplate]` | |
| `requests` | `typing.Optional[flyte._resources.Resources]` | |
| `limits` | `typing.Optional[flyte._resources.Resources]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/sglang ===

# SGLang

## Subpages
- **Integrations > SGLang > Classes**
- **Integrations > SGLang > Packages**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/sglang/classes ===

# Classes

| Class | Description |
|-|-|
| **Integrations > SGLang > Packages > flyteplugins.sglang > SGLangAppEnvironment** |App environment backed by SGLang for serving large language models. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/sglang/packages ===

# Packages

| Package | Description |
|-|-|
| **Integrations > SGLang > Packages > flyteplugins.sglang** |  |

## Subpages
- **Integrations > SGLang > Packages > flyteplugins.sglang**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/sglang/packages/flyteplugins.sglang ===

# flyteplugins.sglang

## Directory

### Classes

| Class | Description |
|-|-|
| **Integrations > SGLang > Packages > flyteplugins.sglang > SGLangAppEnvironment** | App environment backed by SGLang for serving large language models. |

### Variables

| Property | Type | Description |
|-|-|-|
| `DEFAULT_SGLANG_IMAGE` | `Image` |  |

## Subpages
- **Integrations > SGLang > Packages > flyteplugins.sglang > SGLangAppEnvironment**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/sglang/packages/flyteplugins.sglang/sglangappenvironment ===

# SGLangAppEnvironment

**Package:** `flyteplugins.sglang`

App environment backed by SGLang for serving large language models.

This environment sets up an SGLang server with the specified model and configuration.

## Parameters

```python
class SGLangAppEnvironment(
    name: str,
    depends_on: List[Environment],
    pod_template: Optional[Union[str, PodTemplate]],
    description: Optional[str],
    secrets: Optional[SecretRequest],
    env_vars: Optional[Dict[str, str]],
    resources: Optional[Resources],
    interruptible: bool,
    args: *args,
    command: Optional[Union[List[str], str]],
    requires_auth: bool,
    scaling: Scaling,
    domain: Domain | None,
    links: List[Link],
    include: List[str],
    parameters: List[Parameter],
    cluster_pool: str,
    timeouts: Timeouts,
    image: str | Image | Literal['auto'],
    type: str,
    port: int | Port,
    extra_args: str | list[str],
    model_path: str | RunOutput,
    model_hf_path: str,
    model_id: str,
    stream_model: bool,
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | The name of the application. |
| `depends_on` | `List[Environment]` | |
| `pod_template` | `Optional[Union[str, PodTemplate]]` | |
| `description` | `Optional[str]` | |
| `secrets` | `Optional[SecretRequest]` | Secrets that are requested for application. |
| `env_vars` | `Optional[Dict[str, str]]` | Environment variables to set for the application. |
| `resources` | `Optional[Resources]` | |
| `interruptible` | `bool` | |
| `args` | `*args` | |
| `command` | `Optional[Union[List[str], str]]` | |
| `requires_auth` | `bool` | Whether the public URL requires authentication. |
| `scaling` | `Scaling` | Scaling configuration for the app environment. |
| `domain` | `Domain \| None` | Domain to use for the app. |
| `links` | `List[Link]` | |
| `include` | `List[str]` | |
| `parameters` | `List[Parameter]` | |
| `cluster_pool` | `str` | The target cluster_pool where the app should be deployed. |
| `timeouts` | `Timeouts` | |
| `image` | `str \| Image \| Literal['auto']` | |
| `type` | `str` | Type of app. |
| `port` | `int \| Port` | Port application listens to. Defaults to 8000 for SGLang. |
| `extra_args` | `str \| list[str]` | Extra args to pass to `python -m sglang.launch_server`. See https://docs.sglang.io/advanced_features/server_arguments.html for details. |
| `model_path` | `str \| RunOutput` | Remote path to model (e.g., s3 |
| `model_hf_path` | `str` | Hugging Face path to model (e.g., Qwen/Qwen3-0.6B). |
| `model_id` | `str` | Model id that is exposed by SGLang. |
| `stream_model` | `bool` | Set to True to stream model from blob store to the GPU directly. If False, the model will be downloaded to the local file system first and then loaded into the GPU. |

## Properties

| Property | Type | Description |
|-|-|-|
| `endpoint` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Integrations > SGLang > Packages > flyteplugins.sglang > SGLangAppEnvironment > Methods > add_dependency()** | Add a dependency to the environment. |
| **Integrations > SGLang > Packages > flyteplugins.sglang > SGLangAppEnvironment > Methods > clone_with()** |  |
| **Integrations > SGLang > Packages > flyteplugins.sglang > SGLangAppEnvironment > Methods > container_args()** | Return the container arguments for SGLang. |
| **Integrations > SGLang > Packages > flyteplugins.sglang > SGLangAppEnvironment > Methods > container_cmd()** |  |
| **Integrations > SGLang > Packages > flyteplugins.sglang > SGLangAppEnvironment > Methods > get_port()** |  |
| **Integrations > SGLang > Packages > flyteplugins.sglang > SGLangAppEnvironment > Methods > on_shutdown()** | Decorator to define the shutdown function for the app environment. |
| **Integrations > SGLang > Packages > flyteplugins.sglang > SGLangAppEnvironment > Methods > on_startup()** | Decorator to define the startup function for the app environment. |
| **Integrations > SGLang > Packages > flyteplugins.sglang > SGLangAppEnvironment > Methods > server()** | Decorator to define the server function for the app environment. |

### add_dependency()

```python
def add_dependency(
    env: Environment,
)
```
Add a dependency to the environment.

| Parameter | Type | Description |
|-|-|-|
| `env` | `Environment` | |

### clone_with()

```python
def clone_with(
    name: str,
    image: Optional[Union[str, Image, Literal['auto']]],
    resources: Optional[Resources],
    env_vars: Optional[dict[str, str]],
    secrets: Optional[SecretRequest],
    depends_on: Optional[list[Environment]],
    description: Optional[str],
    interruptible: Optional[bool],
    kwargs: **kwargs,
) -> SGLangAppEnvironment
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |
| `image` | `Optional[Union[str, Image, Literal['auto']]]` | |
| `resources` | `Optional[Resources]` | |
| `env_vars` | `Optional[dict[str, str]]` | |
| `secrets` | `Optional[SecretRequest]` | |
| `depends_on` | `Optional[list[Environment]]` | |
| `description` | `Optional[str]` | |
| `interruptible` | `Optional[bool]` | |
| `kwargs` | `**kwargs` | |

### container_args()

```python
def container_args(
    serialization_context: SerializationContext,
) -> list[str]
```
Return the container arguments for SGLang.

| Parameter | Type | Description |
|-|-|-|
| `serialization_context` | `SerializationContext` | |

### container_cmd()

```python
def container_cmd(
    serialize_context: SerializationContext,
    parameter_overrides: list[Parameter] | None,
) -> List[str]
```
| Parameter | Type | Description |
|-|-|-|
| `serialize_context` | `SerializationContext` | |
| `parameter_overrides` | `list[Parameter] \| None` | |

### get_port()

```python
def get_port()
```
### on_shutdown()

```python
def on_shutdown(
    fn: Callable[..., None],
) -> Callable[..., None]
```
Decorator to define the shutdown function for the app environment.

This function is called after the server function is called.

This decorated function can be a sync or async function, and accepts input
parameters based on the Parameters defined in the AppEnvironment
definition.

| Parameter | Type | Description |
|-|-|-|
| `fn` | `Callable[..., None]` | |

### on_startup()

```python
def on_startup(
    fn: Callable[..., None],
) -> Callable[..., None]
```
Decorator to define the startup function for the app environment.

This function is called before the server function is called.

The decorated function can be a sync or async function, and accepts input
parameters based on the Parameters defined in the AppEnvironment
definition.

| Parameter | Type | Description |
|-|-|-|
| `fn` | `Callable[..., None]` | |

### server()

```python
def server(
    fn: Callable[..., None],
) -> Callable[..., None]
```
Decorator to define the server function for the app environment.

This decorated function can be a sync or async function, and accepts input
parameters based on the Parameters defined in the AppEnvironment
definition.

| Parameter | Type | Description |
|-|-|-|
| `fn` | `Callable[..., None]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/snowflake ===

# Snowflake

## Subpages
- **Integrations > Snowflake > Classes**
- **Integrations > Snowflake > Packages**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/snowflake/classes ===

# Classes

| Class | Description |
|-|-|
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > Snowflake** | |
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > SnowflakeConfig** |Configure a Snowflake Task using a `SnowflakeConfig` object. |
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > SnowflakeConnector** | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/snowflake/packages ===

# Packages

| Package | Description |
|-|-|
| **Integrations > Snowflake > Packages > flyteplugins.snowflake** | Key features:. |

## Subpages
- **Integrations > Snowflake > Packages > flyteplugins.snowflake**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/snowflake/packages/flyteplugins.snowflake ===

# flyteplugins.snowflake

Key features:

- Parameterized SQL queries with typed inputs
- Key-pair and password-based authentication
- Returns query results as DataFrames
- Automatic links to the Snowflake query dashboard in the Flyte UI
- Query cancellation on task abort

Basic usage example:
```python
import flyte
from flyte.io import DataFrame
from flyteplugins.snowflake import Snowflake, SnowflakeConfig

config = SnowflakeConfig(
    account="myorg-myaccount",
    user="flyte_user",
    database="ANALYTICS",
    schema="PUBLIC",
    warehouse="COMPUTE_WH",
)

count_users = Snowflake(
    name="count_users",
    query_template="SELECT COUNT(*) FROM users",
    plugin_config=config,
    output_dataframe_type=DataFrame,
)

flyte.TaskEnvironment.from_task("snowflake_env", count_users)

if __name__ == "__main__":
    flyte.init_from_config()

    # Run locally (connector runs in-process, requires credentials and packages locally)
    run = flyte.with_runcontext(mode="local").run(count_users)

    # Run remotely (connector runs on the control plane)
    run = flyte.with_runcontext(mode="remote").run(count_users)

    print(run.url)
```
## Directory

### Classes

| Class | Description |
|-|-|
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > Snowflake** |  |
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > SnowflakeConfig** | Configure a Snowflake Task using a `SnowflakeConfig` object. |
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > SnowflakeConnector** |  |

## Subpages
- **Integrations > Snowflake > Packages > flyteplugins.snowflake > Snowflake**
- **Integrations > Snowflake > Packages > flyteplugins.snowflake > SnowflakeConfig**
- **Integrations > Snowflake > Packages > flyteplugins.snowflake > SnowflakeConnector**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/snowflake/packages/flyteplugins.snowflake/snowflake ===

# Snowflake

**Package:** `flyteplugins.snowflake`

## Parameters

```python
class Snowflake(
    name: str,
    query_template: str,
    plugin_config: flyteplugins.snowflake.task.SnowflakeConfig,
    inputs: typing.Optional[typing.Dict[str, typing.Type]],
    output_dataframe_type: typing.Optional[typing.Type],
    secret_group: typing.Optional[str],
    snowflake_private_key: typing.Optional[str],
    snowflake_private_key_passphrase: typing.Optional[str],
    batch: bool,
    kwargs,
)
```
Task to run parameterized SQL queries against Snowflake.

Note: For password authentication or other auth methods, pass them via `connection_kwargs`.

| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | The name of this task. |
| `query_template` | `str` | The actual query to run. This can be parameterized using Python's printf-style string formatting with named parameters (e.g. %(param_name)s). |
| `plugin_config` | `flyteplugins.snowflake.task.SnowflakeConfig` | `SnowflakeConfig` object containing connection metadata. |
| `inputs` | `typing.Optional[typing.Dict[str, typing.Type]]` | Name and type of inputs specified as a dictionary. |
| `output_dataframe_type` | `typing.Optional[typing.Type]` | If some data is produced by this query, then you can specify the output dataframe type. |
| `secret_group` | `typing.Optional[str]` | Optional group for secrets in the secret store. The environment variable name is auto-generated from `{secret_group}_{key}`, uppercased with hyphens replaced by underscores. If omitted, the key alone is used. |
| `snowflake_private_key` | `typing.Optional[str]` | The secret key for the Snowflake private key (key-pair auth). |
| `snowflake_private_key_passphrase` | `typing.Optional[str]` | The secret key for the private key passphrase (if encrypted). |
| `batch` | `bool` | When True, list inputs are expanded into a multi-row VALUES clause. The query_template should contain a single `VALUES (%(col)s, ...)` placeholder and each input should be a list of equal length. |
| `kwargs` | `**kwargs` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `native_interface` | `None` |  |
| `source_file` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > Snowflake > Methods > aio()** | The aio function allows executing "sync" tasks, in an async context. |
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > Snowflake > Methods > config()** | Returns additional configuration for the task. |
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > Snowflake > Methods > container_args()** | Returns the container args for the task. |
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > Snowflake > Methods > custom_config()** | Returns additional configuration for the task. |
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > Snowflake > Methods > data_loading_config()** | This configuration allows executing raw containers in Flyte using the Flyte CoPilot system. |
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > Snowflake > Methods > execute()** |  |
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > Snowflake > Methods > forward()** | Think of this as a local execute method for your task. |
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > Snowflake > Methods > override()** | Override various parameters of the task template. |
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > Snowflake > Methods > post()** | This is the postexecute function that will be. |
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > Snowflake > Methods > pre()** | This is the preexecute function that will be. |
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > Snowflake > Methods > sql()** | Returns the SQL for the task. |

### aio()

```python
def aio(
    args: *args,
    kwargs: **kwargs,
) -> Coroutine[Any, Any, R] | R
```
The aio function allows executing "sync" tasks, in an async context. This helps with migrating v1 defined sync
tasks to be used within an asyncio parent task.
This function will also re-raise exceptions from the underlying task.

```python
@env.task
def my_legacy_task(x: int) -> int:
    return x

@env.task
async def my_new_parent_task(n: int) -> List[int]:
    collect = []
    for x in range(n):
        collect.append(my_legacy_task.aio(x))
    return asyncio.gather(*collect)
```

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### config()

```python
def config(
    sctx: SerializationContext,
) -> Dict[str, str]
```
Returns additional configuration for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### container_args()

```python
def container_args(
    sctx: SerializationContext,
) -> List[str]
```
Returns the container args for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### custom_config()

```python
def custom_config(
    sctx: flyte.models.SerializationContext,
) -> typing.Optional[typing.Dict[str, typing.Any]]
```
Returns additional configuration for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `flyte.models.SerializationContext` | |

### data_loading_config()

```python
def data_loading_config(
    sctx: SerializationContext,
) -> DataLoadingConfig
```
This configuration allows executing raw containers in Flyte using the Flyte CoPilot system
Flyte CoPilot, eliminates the needs of sdk inside the container. Any inputs required by the users container
are side-loaded in the input_path
Any outputs generated by the user container - within output_path are automatically uploaded

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `SerializationContext` | |

### execute()

```python
def execute(
    kwargs,
) -> typing.Any
```
| Parameter | Type | Description |
|-|-|-|
| `kwargs` | `**kwargs` | |

### forward()

```python
def forward(
    args: *args,
    kwargs: **kwargs,
) -> Coroutine[Any, Any, R] | R
```
Think of this as a local execute method for your task. This function will be invoked by the __call__ method
when not in a Flyte task execution context.  See the implementation below for an example.

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### override()

```python
def override(
    short_name: Optional[str],
    resources: Optional[Resources],
    cache: Optional[CacheRequest],
    retries: Union[int, RetryStrategy],
    timeout: Optional[TimeoutType],
    reusable: Union[ReusePolicy, Literal['off'], None],
    env_vars: Optional[Dict[str, str]],
    secrets: Optional[SecretRequest],
    max_inline_io_bytes: int | None,
    pod_template: Optional[Union[str, PodTemplate]],
    queue: Optional[str],
    interruptible: Optional[bool],
    links: Tuple[Link, ...],
    kwargs: **kwargs,
) -> TaskTemplate
```
Override various parameters of the task template. This allows for dynamic configuration of the task
when it is called, such as changing the image, resources, cache policy, etc.

| Parameter | Type | Description |
|-|-|-|
| `short_name` | `Optional[str]` | Optional override for the short name of the task. |
| `resources` | `Optional[Resources]` | Optional override for the resources to use for the task. |
| `cache` | `Optional[CacheRequest]` | Optional override for the cache policy for the task. |
| `retries` | `Union[int, RetryStrategy]` | Optional override for the number of retries for the task. |
| `timeout` | `Optional[TimeoutType]` | Optional override for the timeout for the task. |
| `reusable` | `Union[ReusePolicy, Literal['off'], None]` | Optional override for the reusability policy for the task. |
| `env_vars` | `Optional[Dict[str, str]]` | Optional override for the environment variables to set for the task. |
| `secrets` | `Optional[SecretRequest]` | Optional override for the secrets that will be injected into the task at runtime. |
| `max_inline_io_bytes` | `int \| None` | Optional override for the maximum allowed size (in bytes) for all inputs and outputs passed directly to the task. |
| `pod_template` | `Optional[Union[str, PodTemplate]]` | Optional override for the pod template to use for the task. |
| `queue` | `Optional[str]` | Optional override for the queue to use for the task. |
| `interruptible` | `Optional[bool]` | Optional override for the interruptible policy for the task. |
| `links` | `Tuple[Link, ...]` | Optional override for the Links associated with the task. |
| `kwargs` | `**kwargs` | Additional keyword arguments for further overrides. Some fields like name, image, docs, and interface cannot be overridden. |

**Returns:** A new TaskTemplate instance with the overridden parameters.

### post()

```python
def post(
    return_vals: Any,
) -> Any
```
This is the postexecute function that will be
called after the task is executed

| Parameter | Type | Description |
|-|-|-|
| `return_vals` | `Any` | |

### pre()

```python
def pre(
    args,
    kwargs,
) -> Dict[str, Any]
```
This is the preexecute function that will be
called before the task is executed

| Parameter | Type | Description |
|-|-|-|
| `args` | `*args` | |
| `kwargs` | `**kwargs` | |

### sql()

```python
def sql(
    sctx: flyte.models.SerializationContext,
) -> typing.Optional[str]
```
Returns the SQL for the task. This is a set of key-value pairs that can be used to
configure the task execution environment at runtime. This is usually used by plugins.

| Parameter | Type | Description |
|-|-|-|
| `sctx` | `flyte.models.SerializationContext` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/snowflake/packages/flyteplugins.snowflake/snowflakeconfig ===

# SnowflakeConfig

**Package:** `flyteplugins.snowflake`

Configure a Snowflake Task using a `SnowflakeConfig` object.

Additional connection parameters (role, authenticator, session_parameters, etc.) can be passed
via connection_kwargs.
See: https://docs.snowflake.com/en/developer-guide/python-connector/python-connector-api

## Parameters

```python
class SnowflakeConfig(
    account: str,
    database: str,
    schema: str,
    warehouse: str,
    user: str,
    connection_kwargs: typing.Optional[typing.Dict[str, typing.Any]],
)
```
| Parameter | Type | Description |
|-|-|-|
| `account` | `str` | The Snowflake account identifier. |
| `database` | `str` | The Snowflake database name. |
| `schema` | `str` | The Snowflake schema name. |
| `warehouse` | `str` | The Snowflake warehouse name. |
| `user` | `str` | The Snowflake user name. |
| `connection_kwargs` | `typing.Optional[typing.Dict[str, typing.Any]]` | Optional dictionary of additional Snowflake connection parameters. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/snowflake/packages/flyteplugins.snowflake/snowflakeconnector ===

# SnowflakeConnector

**Package:** `flyteplugins.snowflake`

## Methods

| Method | Description |
|-|-|
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > SnowflakeConnector > Methods > create()** | Submit a query to Snowflake asynchronously. |
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > SnowflakeConnector > Methods > delete()** | Cancel a running Snowflake query. |
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > SnowflakeConnector > Methods > get()** | Poll the status of a Snowflake query. |
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > SnowflakeConnector > Methods > get_logs()** | Return the metrics for the task. |
| **Integrations > Snowflake > Packages > flyteplugins.snowflake > SnowflakeConnector > Methods > get_metrics()** | Return the metrics for the task. |

### create()

```python
def create(
    task_template: flyteidl2.core.tasks_pb2.TaskTemplate,
    inputs: typing.Optional[typing.Dict[str, typing.Any]],
    snowflake_private_key: typing.Optional[str],
    snowflake_private_key_passphrase: typing.Optional[str],
    kwargs,
) -> flyteplugins.snowflake.connector.SnowflakeJobMetadata
```
Submit a query to Snowflake asynchronously.

| Parameter | Type | Description |
|-|-|-|
| `task_template` | `flyteidl2.core.tasks_pb2.TaskTemplate` | The Flyte task template containing the SQL query and configuration. |
| `inputs` | `typing.Optional[typing.Dict[str, typing.Any]]` | Optional dictionary of input parameters for parameterized queries. |
| `snowflake_private_key` | `typing.Optional[str]` | The private key content set as a Flyte secret. |
| `snowflake_private_key_passphrase` | `typing.Optional[str]` | The passphrase for the private key set as a Flyte secret, if any. |
| `kwargs` | `**kwargs` | |

**Returns:** A SnowflakeJobMetadata object containing the query ID and link to the query dashboard.

### delete()

```python
def delete(
    resource_meta: flyteplugins.snowflake.connector.SnowflakeJobMetadata,
    snowflake_private_key: typing.Optional[str],
    snowflake_private_key_passphrase: typing.Optional[str],
    kwargs,
)
```
Cancel a running Snowflake query.

| Parameter | Type | Description |
|-|-|-|
| `resource_meta` | `flyteplugins.snowflake.connector.SnowflakeJobMetadata` | The SnowflakeJobMetadata containing the query ID. |
| `snowflake_private_key` | `typing.Optional[str]` | The private key content set as a Flyte secret. |
| `snowflake_private_key_passphrase` | `typing.Optional[str]` | The passphrase for the private key set as a Flyte secret, if any. |
| `kwargs` | `**kwargs` | |

### get()

```python
def get(
    resource_meta: flyteplugins.snowflake.connector.SnowflakeJobMetadata,
    snowflake_private_key: typing.Optional[str],
    snowflake_private_key_passphrase: typing.Optional[str],
    kwargs,
) -> flyte.connectors._connector.Resource
```
Poll the status of a Snowflake query.

| Parameter | Type | Description |
|-|-|-|
| `resource_meta` | `flyteplugins.snowflake.connector.SnowflakeJobMetadata` | The SnowflakeJobMetadata containing the query ID. |
| `snowflake_private_key` | `typing.Optional[str]` | The private key content set as a Flyte secret. |
| `snowflake_private_key_passphrase` | `typing.Optional[str]` | The passphrase for the private key set as a Flyte secret, if any. |
| `kwargs` | `**kwargs` | |

**Returns:** A Resource object containing the query results and a link to the query dashboard.

### get_logs()

```python
def get_logs(
    resource_meta: flyte.connectors._connector.ResourceMeta,
    kwargs,
) -> flyteidl2.connector.connector_pb2.GetTaskLogsResponse
```
Return the metrics for the task.

| Parameter | Type | Description |
|-|-|-|
| `resource_meta` | `flyte.connectors._connector.ResourceMeta` | |
| `kwargs` | `**kwargs` | |

### get_metrics()

```python
def get_metrics(
    resource_meta: flyte.connectors._connector.ResourceMeta,
    kwargs,
) -> flyteidl2.connector.connector_pb2.GetTaskMetricsResponse
```
Return the metrics for the task.

| Parameter | Type | Description |
|-|-|-|
| `resource_meta` | `flyte.connectors._connector.ResourceMeta` | |
| `kwargs` | `**kwargs` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/spark ===

# Spark

## Subpages
- **Integrations > Spark > Classes**
- **Integrations > Spark > Packages**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/spark/classes ===

# Classes

| Class | Description |
|-|-|
| **Integrations > Spark > Packages > flyteplugins.spark > ParquetToSparkDecoder** | |
| **Integrations > Spark > Packages > flyteplugins.spark > Spark** |Use this to configure a SparkContext for a your task. |
| **Integrations > Spark > Packages > flyteplugins.spark > SparkToParquetEncoder** | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/spark/packages ===

# Packages

| Package | Description |
|-|-|
| **Integrations > Spark > Packages > flyteplugins.spark** |  |

## Subpages
- **Integrations > Spark > Packages > flyteplugins.spark**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/spark/packages/flyteplugins.spark ===

# flyteplugins.spark

## Directory

### Classes

| Class | Description |
|-|-|
| **Integrations > Spark > Packages > flyteplugins.spark > ParquetToSparkDecoder** |  |
| **Integrations > Spark > Packages > flyteplugins.spark > Spark** | Use this to configure a SparkContext for a your task. |
| **Integrations > Spark > Packages > flyteplugins.spark > SparkToParquetEncoder** |  |

## Subpages
- **Integrations > Spark > Packages > flyteplugins.spark > ParquetToSparkDecoder**
- **Integrations > Spark > Packages > flyteplugins.spark > Spark**
- **Integrations > Spark > Packages > flyteplugins.spark > SparkToParquetEncoder**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/spark/packages/flyteplugins.spark/parquettosparkdecoder ===

# ParquetToSparkDecoder

**Package:** `flyteplugins.spark`

## Parameters

```python
def ParquetToSparkDecoder()
```
Extend this abstract class, implement the decode function, and register your concrete class with the
DataFrameTransformerEngine class in order for the core flytekit type engine to handle
dataframe libraries. This is the decoder interface, meaning it is used when there is a Flyte Literal value,
and we have to get a Python value out of it. For the other way, see the DataFrameEncoder

## Properties

| Property | Type | Description |
|-|-|-|
| `protocol` | `None` |  |
| `python_type` | `None` |  |
| `supported_format` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Integrations > Spark > Packages > flyteplugins.spark > ParquetToSparkDecoder > Methods > decode()** | This is code that will be called by the dataset transformer engine to ultimately translate from a Flyte Literal. |

### decode()

```python
def decode(
    flyte_value: flyteidl2.core.literals_pb2.StructuredDataset,
    current_task_metadata: flyteidl2.core.literals_pb2.StructuredDatasetMetadata,
) -> pyspark.sql.dataframe.DataFrame
```
This is code that will be called by the dataset transformer engine to ultimately translate from a Flyte Literal
value into a Python instance.

    of those dataframes.

| Parameter | Type | Description |
|-|-|-|
| `flyte_value` | `flyteidl2.core.literals_pb2.StructuredDataset` | This will be a Flyte IDL DataFrame Literal - do not confuse this with the DataFrame class defined also in this module. |
| `current_task_metadata` | `flyteidl2.core.literals_pb2.StructuredDatasetMetadata` | Metadata object containing the type (and columns if any) for the currently executing task. This type may have more or less information than the type information bundled inside the incoming flyte_value. |

**Returns:** This function can either return an instance of the dataframe that this decoder handles, or an iterator


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/spark/packages/flyteplugins.spark/spark ===

# Spark

**Package:** `flyteplugins.spark`

Use this to configure a SparkContext for a your task. Task's marked with this will automatically execute
natively onto K8s as a distributed execution of spark

## Parameters

```python
class Spark(
    spark_conf: typing.Optional[typing.Dict[str, str]],
    hadoop_conf: typing.Optional[typing.Dict[str, str]],
    executor_path: typing.Optional[str],
    applications_path: typing.Optional[str],
    driver_pod: typing.Optional[flyte._pod.PodTemplate],
    executor_pod: typing.Optional[flyte._pod.PodTemplate],
)
```
| Parameter | Type | Description |
|-|-|-|
| `spark_conf` | `typing.Optional[typing.Dict[str, str]]` | Spark configuration dictionary. |
| `hadoop_conf` | `typing.Optional[typing.Dict[str, str]]` | Hadoop configuration dictionary. |
| `executor_path` | `typing.Optional[str]` | Path to the Python binary for PySpark execution. |
| `applications_path` | `typing.Optional[str]` | Path to the main application file. |
| `driver_pod` | `typing.Optional[flyte._pod.PodTemplate]` | Pod template for the driver pod. |
| `executor_pod` | `typing.Optional[flyte._pod.PodTemplate]` | Pod template for the executor pods. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/spark/packages/flyteplugins.spark/sparktoparquetencoder ===

# SparkToParquetEncoder

**Package:** `flyteplugins.spark`

## Parameters

```python
def SparkToParquetEncoder()
```
Extend this abstract class, implement the encode function, and register your concrete class with the
DataFrameTransformerEngine class in order for the core flytekit type engine to handle
dataframe libraries. This is the encoding interface, meaning it is used when there is a Python value that the
flytekit type engine is trying to convert into a Flyte Literal. For the other way, see
the DataFrameEncoder

## Properties

| Property | Type | Description |
|-|-|-|
| `protocol` | `None` |  |
| `python_type` | `None` |  |
| `supported_format` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Integrations > Spark > Packages > flyteplugins.spark > SparkToParquetEncoder > Methods > encode()** | Even if the user code returns a plain dataframe instance, the dataset transformer engine will wrap the. |

### encode()

```python
def encode(
    dataframe: flyte.io._dataframe.dataframe.DataFrame,
    structured_dataset_type: flyteidl2.core.types_pb2.StructuredDatasetType,
) -> flyteidl2.core.literals_pb2.StructuredDataset
```
Even if the user code returns a plain dataframe instance, the dataset transformer engine will wrap the
incoming dataframe with defaults set for that dataframe
type. This simplifies this function's interface as a lot of data that could be specified by the user using
the
# TODO: Do we need to add a flag to indicate if it was wrapped by the transformer or by the user?

  DataFrame wrapper class used as input to this function - that is the user facing Python class.
  This function needs to return the IDL DataFrame.

| Parameter | Type | Description |
|-|-|-|
| `dataframe` | `flyte.io._dataframe.dataframe.DataFrame` | This is a DataFrame wrapper object. See more info above. |
| `structured_dataset_type` | `flyteidl2.core.types_pb2.StructuredDatasetType` | This the DataFrameType, as found in the LiteralType of the interface of the task that invoked this encoding call. It is passed along to encoders so that authors of encoders can include it in the returned literals.DataFrame. See the IDL for more information on why this literal in particular carries the type information along with it. If the encoder doesn't supply it, it will also be filled in after the encoder runs by the transformer engine. |

**Returns:** This function should return a DataFrame literal object. Do not confuse this with the


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/union ===

# Union

## Subpages
- **Integrations > Union > Classes**
- **Integrations > Union > Packages**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/union/classes ===

# Classes

| Class | Description |
|-|-|
| **Integrations > Union > Packages > flyteplugins.union.remote > ApiKey** |Represents a Union API Key (OAuth Application). |
| **Integrations > Union > Packages > flyteplugins.union.remote > Assignment** |Represents role/policy assignments for an identity. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Cluster** |Represents a Union cluster. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Member** |Represents a Union organization member (user or application). |
| **Integrations > Union > Packages > flyteplugins.union.remote > Policy** |Represents a Union RBAC Policy. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Role** |Represents a Union RBAC Role. |
| **Integrations > Union > Packages > flyteplugins.union.remote > User** |Represents a Union user. |
| **Integrations > Union > Packages > flyteplugins.union.utils.auth > AppClientCredentials** |Application client credentials for API key. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/union/packages ===

# Packages

| Package | Description |
|-|-|
| **Integrations > Union > Packages > flyteplugins.union.cli** |  |
| **Integrations > Union > Packages > flyteplugins.union.internal.validate.validate.validate_pb2** | Generated protocol buffer code. |
| **Integrations > Union > Packages > flyteplugins.union.remote** | Union remote control plane objects. |
| **Integrations > Union > Packages > flyteplugins.union.utils.auth** |  |

## Subpages
- **Integrations > Union > Packages > flyteplugins.union.cli**
- **Integrations > Union > Packages > flyteplugins.union.internal.validate.validate.validate_pb2**
- **Integrations > Union > Packages > flyteplugins.union.remote**
- **Integrations > Union > Packages > flyteplugins.union.utils.auth**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/union/packages/flyteplugins.union.cli ===

# flyteplugins.union.cli

## Directory

### Methods

| Method | Description |
|-|-|
| **Integrations > Union > Packages > flyteplugins.union.cli > Methods > edit_with_retry()** | Open an editor and retry or save to file on failure. |

## Methods

#### edit_with_retry()

```python
def edit_with_retry(
    yaml_text: str,
    apply_fn,
    console,
    noun: str,
)
```
Open an editor and retry or save to file on failure.

| Parameter | Type | Description |
|-|-|-|
| `yaml_text` | `str` | Initial YAML content to edit. |
| `apply_fn` |  | Callable that takes the edited YAML string and applies it. Should raise on failure. |
| `console` |  | Rich console for output. |
| `noun` | `str` | Name of the resource for messages (e.g. "role", "policy"). |

**Returns:** The result of apply_fn on success, or None if cancelled.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/union/packages/flyteplugins.union.internal.validate.validate.validate_pb2 ===

# flyteplugins.union.internal.validate.validate.validate_pb2

Generated protocol buffer code.
## Directory

### Variables

| Property | Type | Description |
|-|-|-|
| `DISABLED_FIELD_NUMBER` | `int` |  |
| `HTTP_HEADER_NAME` | `int` |  |
| `HTTP_HEADER_VALUE` | `int` |  |
| `IGNORED_FIELD_NUMBER` | `int` |  |
| `REQUIRED_FIELD_NUMBER` | `int` |  |
| `RULES_FIELD_NUMBER` | `int` |  |
| `UNKNOWN` | `int` |  |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/union/packages/flyteplugins.union.remote ===

# flyteplugins.union.remote

Union remote control plane objects.

This module provides remote object classes for Union-specific control plane
entities, following the same pattern as flyte.remote objects.

Example:
    from flyteplugins.union.remote import ApiKey

    # List all API keys
    keys = ApiKey.listall()
    for key in keys:
        print(key.client_id)

    # Create a new API key
    api_key = ApiKey.create(name="my-ci-key")
    print(api_key.client_secret)

    # Get a specific API key
    key = ApiKey.get(client_id="my-client-id")

    # Delete an API key
    ApiKey.delete(client_id="my-client-id")
## Directory

### Classes

| Class | Description |
|-|-|
| **Integrations > Union > Packages > flyteplugins.union.remote > ApiKey** | Represents a Union API Key (OAuth Application). |
| **Integrations > Union > Packages > flyteplugins.union.remote > Assignment** | Represents role/policy assignments for an identity. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Cluster** | Represents a Union cluster. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Member** | Represents a Union organization member (user or application). |
| **Integrations > Union > Packages > flyteplugins.union.remote > Policy** | Represents a Union RBAC Policy. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Role** | Represents a Union RBAC Role. |
| **Integrations > Union > Packages > flyteplugins.union.remote > User** | Represents a Union user. |

## Subpages
- **Integrations > Union > Packages > flyteplugins.union.remote > ApiKey**
- **Integrations > Union > Packages > flyteplugins.union.remote > Assignment**
- **Integrations > Union > Packages > flyteplugins.union.remote > Cluster**
- **Integrations > Union > Packages > flyteplugins.union.remote > Member**
- **Integrations > Union > Packages > flyteplugins.union.remote > Policy**
- **Integrations > Union > Packages > flyteplugins.union.remote > Role**
- **Integrations > Union > Packages > flyteplugins.union.remote > User**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/union/packages/flyteplugins.union.remote/apikey ===

# ApiKey

**Package:** `flyteplugins.union.remote`

Represents a Union API Key (OAuth Application).

API Keys in Union are OAuth 2.0 applications that can be used for
headless authentication. They support client credentials flow for
machine-to-machine authentication.

## Parameters

```python
class ApiKey(
    pb2: App,
    organization: str | None,
    encoded_credentials: str | None,
)
```
| Parameter | Type | Description |
|-|-|-|
| `pb2` | `App` | The underlying protobuf App message |
| `organization` | `str \| None` | The organization this API key belongs to (for serverless) |
| `encoded_credentials` | `str \| None` | Base64-encoded credentials for UNION_API_KEY env var |

## Properties

| Property | Type | Description |
|-|-|-|
| `client_id` | `None` | The OAuth client ID. |
| `client_name` | `None` | The human-readable name of the API key. |
| `client_secret` | `None` | The OAuth client secret (only available on creation). |

## Methods

| Method | Description |
|-|-|
| **Integrations > Union > Packages > flyteplugins.union.remote > ApiKey > Methods > create()** | Create a new API key. |
| **Integrations > Union > Packages > flyteplugins.union.remote > ApiKey > Methods > delete()** | Delete an API key. |
| **Integrations > Union > Packages > flyteplugins.union.remote > ApiKey > Methods > get()** | Get an API key by client ID. |
| **Integrations > Union > Packages > flyteplugins.union.remote > ApiKey > Methods > listall()** | List all API keys. |
| **Integrations > Union > Packages > flyteplugins.union.remote > ApiKey > Methods > to_dict()** | Convert the object to a JSON-serializable dictionary. |
| **Integrations > Union > Packages > flyteplugins.union.remote > ApiKey > Methods > to_json()** | Convert the object to a JSON string. |
| **Integrations > Union > Packages > flyteplugins.union.remote > ApiKey > Methods > update()** | Update an API key. |

### create()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await ApiKey.create.aio()`.
```python
def create(
    cls,
    name: str,
    redirect_uris: list[str] | None,
) -> ApiKey
```
Create a new API key.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | Human-readable name for the API key |
| `redirect_uris` | `list[str] \| None` | OAuth redirect URIs (defaults to localhost callback) |

**Returns**

ApiKey instance with client_secret populated

**Raises**

| Exception | Description |
|-|-|
| `Exception` | If API key creation fails |

### delete()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await ApiKey.delete.aio()`.
```python
def delete(
    cls,
    client_id: str,
)
```
Delete an API key.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `client_id` | `str` | The OAuth client ID to delete |

**Raises**

| Exception | Description |
|-|-|
| `Exception` | If deletion fails |

### get()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await ApiKey.get.aio()`.
```python
def get(
    cls,
    client_id: str,
) -> ApiKey
```
Get an API key by client ID.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `client_id` | `str` | The OAuth client ID |

**Returns**

ApiKey instance

**Raises**

| Exception | Description |
|-|-|
| `Exception` | If API key not found |

### listall()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await ApiKey.listall.aio()`.
```python
def listall(
    cls,
    limit: int,
) -> AsyncIterator[ApiKey]
```
List all API keys.

Yields:
    ApiKey instances

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `limit` | `int` | Maximum number of keys to return |

### to_dict()

```python
def to_dict()
```
Convert the object to a JSON-serializable dictionary.

**Returns:** dict: A dictionary representation of the object.

### to_json()

```python
def to_json()
```
Convert the object to a JSON string.

**Returns:** str: A JSON string representation of the object.

### update()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await ApiKey.update.aio()`.
```python
def update(
    cls,
    client_id: str,
    client_name: str | None,
    redirect_uris: list[str] | None,
) -> ApiKey
```
Update an API key.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `client_id` | `str` | The OAuth client ID to update |
| `client_name` | `str \| None` | New name for the API key |
| `redirect_uris` | `list[str] \| None` | New redirect URIs |

**Returns**

Updated ApiKey instance

**Raises**

| Exception | Description |
|-|-|
| `Exception` | If update fails |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/union/packages/flyteplugins.union.remote/assignment ===

# Assignment

**Package:** `flyteplugins.union.remote`

Represents role/policy assignments for an identity.

## Parameters

```python
class Assignment(
    pb2: IdentityAssignment,
)
```
| Parameter | Type | Description |
|-|-|-|
| `pb2` | `IdentityAssignment` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `policies` | `None` |  |
| `roles` | `None` |  |
| `subject` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Integrations > Union > Packages > flyteplugins.union.remote > Assignment > Methods > create()** | Assign a policy to an identity. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Assignment > Methods > get()** | Get assignments for an identity. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Assignment > Methods > listall()** | List assignments for all members in the organization. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Assignment > Methods > to_dict()** | Convert the object to a JSON-serializable dictionary. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Assignment > Methods > to_json()** | Convert the object to a JSON string. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Assignment > Methods > unassign()** | Unassign a policy from an identity. |

### create()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Assignment.create.aio()`.
```python
def create(
    cls,
    user_subject: str | None,
    creds_subject: str | None,
    email: str | None,
    policy: str,
) -> Assignment
```
Assign a policy to an identity.

Exactly one of user_subject, creds_subject, or email must be provided.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `user_subject` | `str \| None` | User subject identifier. |
| `creds_subject` | `str \| None` | Client credentials application subject. |
| `email` | `str \| None` | User email for lookup. |
| `policy` | `str` | Policy name to assign. |

**Returns:** Assignment for the identity after the policy is assigned.

### get()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Assignment.get.aio()`.
```python
def get(
    cls,
    user_subject: str | None,
    creds_subject: str | None,
) -> Assignment
```
Get assignments for an identity.

One of user_subject or creds_subject must be provided.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `user_subject` | `str \| None` | |
| `creds_subject` | `str \| None` | |

### listall()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Assignment.listall.aio()`.
```python
def listall(
    cls,
    limit: int,
) -> AsyncIterator[Assignment]
```
List assignments for all members in the organization.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `limit` | `int` | |

### to_dict()

```python
def to_dict()
```
Convert the object to a JSON-serializable dictionary.

**Returns:** dict: A dictionary representation of the object.

### to_json()

```python
def to_json()
```
Convert the object to a JSON string.

**Returns:** str: A JSON string representation of the object.

### unassign()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Assignment.unassign.aio()`.
```python
def unassign(
    cls,
    user_subject: str | None,
    creds_subject: str | None,
    policy: str,
)
```
Unassign a policy from an identity.

One of user_subject or creds_subject must be provided.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `user_subject` | `str \| None` | |
| `creds_subject` | `str \| None` | |
| `policy` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/union/packages/flyteplugins.union.remote/cluster ===

# Cluster

**Package:** `flyteplugins.union.remote`

Represents a Union cluster.

## Parameters

```python
class Cluster(
    pb2: ClusterPb2,
)
```
| Parameter | Type | Description |
|-|-|-|
| `pb2` | `ClusterPb2` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `health` | `None` |  |
| `health_display` | `None` |  |
| `monitoring_info` | `None` |  |
| `name` | `None` |  |
| `organization` | `None` |  |
| `state` | `None` |  |
| `tunnel_status` | `None` |  |
| `tunnel_status_display` | `None` |  |
| `tunnel_url` | `None` |  |
| `unhealthy_reasons` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Integrations > Union > Packages > flyteplugins.union.remote > Cluster > Methods > get()** | Get a cluster by name. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Cluster > Methods > listall()** | List all clusters in the organization. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Cluster > Methods > to_dict()** | Convert the object to a JSON-serializable dictionary. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Cluster > Methods > to_json()** | Convert the object to a JSON string. |

### get()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Cluster.get.aio()`.
```python
def get(
    cls,
    name: str,
) -> Cluster
```
Get a cluster by name.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | |

### listall()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Cluster.listall.aio()`.
```python
def listall(
    cls,
    limit: int,
) -> AsyncIterator[Cluster]
```
List all clusters in the organization.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `limit` | `int` | Maximum number of clusters to return. |

### to_dict()

```python
def to_dict()
```
Convert the object to a JSON-serializable dictionary.

**Returns:** dict: A dictionary representation of the object.

### to_json()

```python
def to_json()
```
Convert the object to a JSON string.

**Returns:** str: A JSON string representation of the object.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/union/packages/flyteplugins.union.remote/member ===

# Member

**Package:** `flyteplugins.union.remote`

Represents a Union organization member (user or application).

## Parameters

```python
class Member(
    pb2: EnrichedIdentity,
)
```
| Parameter | Type | Description |
|-|-|-|
| `pb2` | `EnrichedIdentity` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `identity_type` | `None` |  |
| `is_application` | `None` |  |
| `is_user` | `None` |  |
| `name` | `None` |  |
| `subject` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Integrations > Union > Packages > flyteplugins.union.remote > Member > Methods > listall()** | List all members in the organization. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Member > Methods > to_dict()** | Convert the object to a JSON-serializable dictionary. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Member > Methods > to_json()** | Convert the object to a JSON string. |

### listall()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Member.listall.aio()`.
```python
def listall(
    cls,
) -> AsyncIterator[Member]
```
List all members in the organization.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |

### to_dict()

```python
def to_dict()
```
Convert the object to a JSON-serializable dictionary.

**Returns:** dict: A dictionary representation of the object.

### to_json()

```python
def to_json()
```
Convert the object to a JSON string.

**Returns:** str: A JSON string representation of the object.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/union/packages/flyteplugins.union.remote/policy ===

# Policy

**Package:** `flyteplugins.union.remote`

Represents a Union RBAC Policy.

## Parameters

```python
class Policy(
    pb2: PolicyPb2,
)
```
| Parameter | Type | Description |
|-|-|-|
| `pb2` | `PolicyPb2` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `bindings` | `None` |  |
| `description` | `None` |  |
| `name` | `None` |  |
| `organization` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Integrations > Union > Packages > flyteplugins.union.remote > Policy > Methods > create()** | Create a new policy. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Policy > Methods > delete()** | Delete a policy. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Policy > Methods > get()** | Get a policy by name. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Policy > Methods > listall()** | List all policies in the organization. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Policy > Methods > to_dict()** | Convert the object to a JSON-serializable dictionary. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Policy > Methods > to_json()** | Convert the object to a JSON string. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Policy > Methods > update()** | Update a policy by diffing bindings and applying add/remove operations. |

### create()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Policy.create.aio()`.
```python
def create(
    cls,
    name: str,
    description: str,
    bindings: list[dict] | None,
) -> Policy
```
Create a new policy.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | |
| `description` | `str` | |
| `bindings` | `list[dict] \| None` | |

### delete()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Policy.delete.aio()`.
```python
def delete(
    cls,
    name: str,
)
```
Delete a policy.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | |

### get()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Policy.get.aio()`.
```python
def get(
    cls,
    name: str,
) -> Policy
```
Get a policy by name.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | |

### listall()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Policy.listall.aio()`.
```python
def listall(
    cls,
    limit: int,
) -> AsyncIterator[Policy]
```
List all policies in the organization.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `limit` | `int` | |

### to_dict()

```python
def to_dict()
```
Convert the object to a JSON-serializable dictionary.

**Returns:** dict: A dictionary representation of the object.

### to_json()

```python
def to_json()
```
Convert the object to a JSON string.

**Returns:** str: A JSON string representation of the object.

### update()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Policy.update.aio()`.
```python
def update(
    cls,
    name: str,
    old_bindings: list[dict],
    new_bindings: list[dict],
) -> Policy
```
Update a policy by diffing bindings and applying add/remove operations.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | |
| `old_bindings` | `list[dict]` | |
| `new_bindings` | `list[dict]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/union/packages/flyteplugins.union.remote/role ===

# Role

**Package:** `flyteplugins.union.remote`

Represents a Union RBAC Role.

## Parameters

```python
class Role(
    pb2: RolePb2,
)
```
| Parameter | Type | Description |
|-|-|-|
| `pb2` | `RolePb2` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `actions` | `None` |  |
| `description` | `None` |  |
| `name` | `None` |  |
| `organization` | `None` |  |
| `role_type` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Integrations > Union > Packages > flyteplugins.union.remote > Role > Methods > create()** | Create a new role. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Role > Methods > delete()** | Delete a role. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Role > Methods > get()** | Get a role by name. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Role > Methods > listall()** | List all roles in the organization. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Role > Methods > to_dict()** | Convert the object to a JSON-serializable dictionary. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Role > Methods > to_json()** | Convert the object to a JSON string. |
| **Integrations > Union > Packages > flyteplugins.union.remote > Role > Methods > update()** | Update a role. |

### create()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Role.create.aio()`.
```python
def create(
    cls,
    name: str,
    description: str,
    actions: list[str] | None,
) -> Role
```
Create a new role.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | |
| `description` | `str` | |
| `actions` | `list[str] \| None` | |

### delete()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Role.delete.aio()`.
```python
def delete(
    cls,
    name: str,
)
```
Delete a role.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | |

### get()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Role.get.aio()`.
```python
def get(
    cls,
    name: str,
) -> Role
```
Get a role by name.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | |

### listall()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Role.listall.aio()`.
```python
def listall(
    cls,
    limit: int,
) -> AsyncIterator[Role]
```
List all roles in the organization.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `limit` | `int` | |

### to_dict()

```python
def to_dict()
```
Convert the object to a JSON-serializable dictionary.

**Returns:** dict: A dictionary representation of the object.

### to_json()

```python
def to_json()
```
Convert the object to a JSON string.

**Returns:** str: A JSON string representation of the object.

### update()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await Role.update.aio()`.
```python
def update(
    cls,
    name: str,
    description: str,
    actions: list[str] | None,
)
```
Update a role.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `name` | `str` | |
| `description` | `str` | |
| `actions` | `list[str] \| None` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/union/packages/flyteplugins.union.remote/user ===

# User

**Package:** `flyteplugins.union.remote`

Represents a Union user.

## Parameters

```python
class User(
    pb2: UserPb2,
)
```
| Parameter | Type | Description |
|-|-|-|
| `pb2` | `UserPb2` | |

## Properties

| Property | Type | Description |
|-|-|-|
| `email` | `None` |  |
| `first_name` | `None` |  |
| `last_name` | `None` |  |
| `subject` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Integrations > Union > Packages > flyteplugins.union.remote > User > Methods > create()** | Create (invite) a new user. |
| **Integrations > Union > Packages > flyteplugins.union.remote > User > Methods > delete()** | Delete a user. |
| **Integrations > Union > Packages > flyteplugins.union.remote > User > Methods > get()** | Get a user by subject identifier. |
| **Integrations > Union > Packages > flyteplugins.union.remote > User > Methods > listall()** | List all users in the organization. |
| **Integrations > Union > Packages > flyteplugins.union.remote > User > Methods > to_dict()** | Convert the object to a JSON-serializable dictionary. |
| **Integrations > Union > Packages > flyteplugins.union.remote > User > Methods > to_json()** | Convert the object to a JSON string. |

### create()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await User.create.aio()`.
```python
def create(
    cls,
    first_name: str,
    last_name: str,
    email: str,
) -> User
```
Create (invite) a new user.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `first_name` | `str` | The user's first name. |
| `last_name` | `str` | The user's last name. |
| `email` | `str` | The user's email address. |

**Returns:** User instance for the newly created user.

### delete()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await User.delete.aio()`.
```python
def delete(
    cls,
    subject: str,
)
```
Delete a user.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `subject` | `str` | |

### get()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await User.get.aio()`.
```python
def get(
    cls,
    subject: str,
) -> User
```
Get a user by subject identifier.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `subject` | `str` | |

### listall()

> [!NOTE] This method can be called both synchronously or asynchronously.
> Default invocation is sync and will block.
> To call it asynchronously, use the function `.aio()` on the method name itself, e.g.,:
> `result = await User.listall.aio()`.
```python
def listall(
    cls,
    limit: int,
    email: str | None,
) -> AsyncIterator[User]
```
List all users in the organization.

| Parameter | Type | Description |
|-|-|-|
| `cls` |  | |
| `limit` | `int` | Maximum number of users to return. |
| `email` | `str \| None` | Filter by email (server-side, exact match). |

### to_dict()

```python
def to_dict()
```
Convert the object to a JSON-serializable dictionary.

**Returns:** dict: A dictionary representation of the object.

### to_json()

```python
def to_json()
```
Convert the object to a JSON string.

**Returns:** str: A JSON string representation of the object.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/union/packages/flyteplugins.union.utils.auth ===

# flyteplugins.union.utils.auth

## Directory

### Classes

| Class | Description |
|-|-|
| **Integrations > Union > Packages > flyteplugins.union.utils.auth > AppClientCredentials** | Application client credentials for API key. |

### Methods

| Method | Description |
|-|-|
| **Integrations > Union > Packages > flyteplugins.union.utils.auth > Methods > encode_app_client_credentials()** | Encode app credentials as a base64 string for use as UNION_API_KEY. |
| **Integrations > Union > Packages > flyteplugins.union.utils.auth > Methods > is_serverless_endpoint()** | Check if endpoint is a Union serverless endpoint. |

## Methods

#### encode_app_client_credentials()

```python
def encode_app_client_credentials(
    app_credentials: flyteplugins.union.utils.auth.AppClientCredentials,
) -> str
```
Encode app credentials as a base64 string for use as UNION_API_KEY.

| Parameter | Type | Description |
|-|-|-|
| `app_credentials` | `flyteplugins.union.utils.auth.AppClientCredentials` | The application credentials to encode |

**Returns:** Base64-encoded credential string

#### is_serverless_endpoint()

```python
def is_serverless_endpoint(
    endpoint: str,
) -> bool
```
Check if endpoint is a Union serverless endpoint.

| Parameter | Type | Description |
|-|-|-|
| `endpoint` | `str` | |

## Subpages
- **Integrations > Union > Packages > flyteplugins.union.utils.auth > AppClientCredentials**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/union/packages/flyteplugins.union.utils.auth/appclientcredentials ===

# AppClientCredentials

**Package:** `flyteplugins.union.utils.auth`

Application client credentials for API key.

## Parameters

```python
class AppClientCredentials(
    endpoint: str,
    client_id: str,
    client_secret: str,
    org: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `endpoint` | `str` | |
| `client_id` | `str` | |
| `client_secret` | `str` | |
| `org` | `str` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/vllm ===

# vLLM

## Subpages
- **Integrations > vLLM > Classes**
- **Integrations > vLLM > Packages**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/vllm/classes ===

# Classes

| Class | Description |
|-|-|
| **Integrations > vLLM > Packages > flyteplugins.vllm > VLLMAppEnvironment** |App environment backed by vLLM for serving large language models. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/vllm/packages ===

# Packages

| Package | Description |
|-|-|
| **Integrations > vLLM > Packages > flyteplugins.vllm** |  |

## Subpages
- **Integrations > vLLM > Packages > flyteplugins.vllm**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/vllm/packages/flyteplugins.vllm ===

# flyteplugins.vllm

## Directory

### Classes

| Class | Description |
|-|-|
| **Integrations > vLLM > Packages > flyteplugins.vllm > VLLMAppEnvironment** | App environment backed by vLLM for serving large language models. |

### Variables

| Property | Type | Description |
|-|-|-|
| `DEFAULT_VLLM_IMAGE` | `Image` |  |

## Subpages
- **Integrations > vLLM > Packages > flyteplugins.vllm > VLLMAppEnvironment**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/vllm/packages/flyteplugins.vllm/vllmappenvironment ===

# VLLMAppEnvironment

**Package:** `flyteplugins.vllm`

App environment backed by vLLM for serving large language models.

This environment sets up a vLLM server with the specified model and configuration.

## Parameters

```python
class VLLMAppEnvironment(
    name: str,
    depends_on: List[Environment],
    pod_template: Optional[Union[str, PodTemplate]],
    description: Optional[str],
    secrets: Optional[SecretRequest],
    env_vars: Optional[Dict[str, str]],
    resources: Optional[Resources],
    interruptible: bool,
    args: *args,
    command: Optional[Union[List[str], str]],
    requires_auth: bool,
    scaling: Scaling,
    domain: Domain | None,
    links: List[Link],
    include: List[str],
    parameters: List[Parameter],
    cluster_pool: str,
    timeouts: Timeouts,
    image: str | Image | Literal['auto'],
    type: str,
    port: int | Port,
    extra_args: str | list[str],
    model_path: str | RunOutput,
    model_hf_path: str,
    model_id: str,
    stream_model: bool,
)
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | The name of the application. |
| `depends_on` | `List[Environment]` | |
| `pod_template` | `Optional[Union[str, PodTemplate]]` | |
| `description` | `Optional[str]` | |
| `secrets` | `Optional[SecretRequest]` | Secrets that are requested for application. |
| `env_vars` | `Optional[Dict[str, str]]` | Environment variables to set for the application. |
| `resources` | `Optional[Resources]` | |
| `interruptible` | `bool` | |
| `args` | `*args` | |
| `command` | `Optional[Union[List[str], str]]` | |
| `requires_auth` | `bool` | Whether the public URL requires authentication. |
| `scaling` | `Scaling` | Scaling configuration for the app environment. |
| `domain` | `Domain \| None` | Domain to use for the app. |
| `links` | `List[Link]` | |
| `include` | `List[str]` | |
| `parameters` | `List[Parameter]` | |
| `cluster_pool` | `str` | The target cluster_pool where the app should be deployed. |
| `timeouts` | `Timeouts` | |
| `image` | `str \| Image \| Literal['auto']` | |
| `type` | `str` | Type of app. |
| `port` | `int \| Port` | Port application listens to. Defaults to 8000 for vLLM. |
| `extra_args` | `str \| list[str]` | Extra args to pass to `vllm serve`. See https://docs.vllm.ai/en/stable/configuration/engine_args or run `vllm serve --help` for details. |
| `model_path` | `str \| RunOutput` | Remote path to model (e.g., s3 |
| `model_hf_path` | `str` | Hugging Face path to model (e.g., Qwen/Qwen3-0.6B). |
| `model_id` | `str` | Model id that is exposed by vllm. |
| `stream_model` | `bool` | Set to True to stream model from blob store to the GPU directly. If False, the model will be downloaded to the local file system first and then loaded into the GPU. |

## Properties

| Property | Type | Description |
|-|-|-|
| `endpoint` | `None` |  |

## Methods

| Method | Description |
|-|-|
| **Integrations > vLLM > Packages > flyteplugins.vllm > VLLMAppEnvironment > Methods > add_dependency()** | Add a dependency to the environment. |
| **Integrations > vLLM > Packages > flyteplugins.vllm > VLLMAppEnvironment > Methods > clone_with()** |  |
| **Integrations > vLLM > Packages > flyteplugins.vllm > VLLMAppEnvironment > Methods > container_args()** | Return the container arguments for vLLM. |
| **Integrations > vLLM > Packages > flyteplugins.vllm > VLLMAppEnvironment > Methods > container_cmd()** |  |
| **Integrations > vLLM > Packages > flyteplugins.vllm > VLLMAppEnvironment > Methods > get_port()** |  |
| **Integrations > vLLM > Packages > flyteplugins.vllm > VLLMAppEnvironment > Methods > on_shutdown()** | Decorator to define the shutdown function for the app environment. |
| **Integrations > vLLM > Packages > flyteplugins.vllm > VLLMAppEnvironment > Methods > on_startup()** | Decorator to define the startup function for the app environment. |
| **Integrations > vLLM > Packages > flyteplugins.vllm > VLLMAppEnvironment > Methods > server()** | Decorator to define the server function for the app environment. |

### add_dependency()

```python
def add_dependency(
    env: Environment,
)
```
Add a dependency to the environment.

| Parameter | Type | Description |
|-|-|-|
| `env` | `Environment` | |

### clone_with()

```python
def clone_with(
    name: str,
    image: Optional[Union[str, Image, Literal['auto']]],
    resources: Optional[Resources],
    env_vars: Optional[dict[str, str]],
    secrets: Optional[SecretRequest],
    depends_on: Optional[list[Environment]],
    description: Optional[str],
    interruptible: Optional[bool],
    kwargs: **kwargs,
) -> VLLMAppEnvironment
```
| Parameter | Type | Description |
|-|-|-|
| `name` | `str` | |
| `image` | `Optional[Union[str, Image, Literal['auto']]]` | |
| `resources` | `Optional[Resources]` | |
| `env_vars` | `Optional[dict[str, str]]` | |
| `secrets` | `Optional[SecretRequest]` | |
| `depends_on` | `Optional[list[Environment]]` | |
| `description` | `Optional[str]` | |
| `interruptible` | `Optional[bool]` | |
| `kwargs` | `**kwargs` | |

### container_args()

```python
def container_args(
    serialization_context: SerializationContext,
) -> list[str]
```
Return the container arguments for vLLM.

| Parameter | Type | Description |
|-|-|-|
| `serialization_context` | `SerializationContext` | |

### container_cmd()

```python
def container_cmd(
    serialize_context: SerializationContext,
    parameter_overrides: list[Parameter] | None,
) -> List[str]
```
| Parameter | Type | Description |
|-|-|-|
| `serialize_context` | `SerializationContext` | |
| `parameter_overrides` | `list[Parameter] \| None` | |

### get_port()

```python
def get_port()
```
### on_shutdown()

```python
def on_shutdown(
    fn: Callable[..., None],
) -> Callable[..., None]
```
Decorator to define the shutdown function for the app environment.

This function is called after the server function is called.

This decorated function can be a sync or async function, and accepts input
parameters based on the Parameters defined in the AppEnvironment
definition.

| Parameter | Type | Description |
|-|-|-|
| `fn` | `Callable[..., None]` | |

### on_startup()

```python
def on_startup(
    fn: Callable[..., None],
) -> Callable[..., None]
```
Decorator to define the startup function for the app environment.

This function is called before the server function is called.

The decorated function can be a sync or async function, and accepts input
parameters based on the Parameters defined in the AppEnvironment
definition.

| Parameter | Type | Description |
|-|-|-|
| `fn` | `Callable[..., None]` | |

### server()

```python
def server(
    fn: Callable[..., None],
) -> Callable[..., None]
```
Decorator to define the server function for the app environment.

This decorated function can be a sync or async function, and accepts input
parameters based on the Parameters defined in the AppEnvironment
definition.

| Parameter | Type | Description |
|-|-|-|
| `fn` | `Callable[..., None]` | |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/wandb ===

# Weights & Biases

## Subpages
- **Integrations > Weights & Biases > Classes**
- **Integrations > Weights & Biases > Packages**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/wandb/classes ===

# Classes

| Class | Description |
|-|-|
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb > Wandb** |Generates a Weights & Biases run link. |
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb > WandbSweep** |Generates a Weights & Biases Sweep link. |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/wandb/packages ===

# Packages

| Package | Description |
|-|-|
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb** | ## Key features:. |

## Subpages
- **Integrations > Weights & Biases > Packages > flyteplugins.wandb**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/wandb/packages/flyteplugins.wandb ===

# flyteplugins.wandb

## Key features:

- Automatic W&B run initialization with `@wandb_init` decorator
- Automatic W&B links in Flyte UI pointing to runs and sweeps
- Parent/child task support with automatic run reuse
- W&B sweep creation and management with `@wandb_sweep` decorator
- Configuration management with `wandb_config()` and `wandb_sweep_config()`
- Distributed training support (auto-detects PyTorch DDP/torchrun)

## Basic usage:

1. Simple task with W&B logging:

   ```python
   from flyteplugins.wandb import wandb_init, get_wandb_run

   @wandb_init(project="my-project", entity="my-team")
   @env.task
   async def train_model(learning_rate: float) -> str:
       wandb_run = get_wandb_run()
       wandb_run.log({"loss": 0.5, "learning_rate": learning_rate})
       return wandb_run.id
   ```

2. Parent/Child Tasks with Run Reuse:

   ```python
   @wandb_init  # Automatically reuses parent's run ID
   @env.task
   async def child_task(x: int) -> str:
       wandb_run = get_wandb_run()
       wandb_run.log({"child_metric": x * 2})
       return wandb_run.id

   @wandb_init(project="my-project", entity="my-team")
   @env.task
   async def parent_task() -> str:
       wandb_run = get_wandb_run()
       wandb_run.log({"parent_metric": 100})

       # Child reuses parent's run by default (run_mode="auto")
       await child_task(5)
       return wandb_run.id
   ```

3. Configuration with context manager:

   ```python
   from flyteplugins.wandb import wandb_config

   r = flyte.with_runcontext(
       custom_context=wandb_config(
           project="my-project",
           entity="my-team",
           tags=["experiment-1"]
       )
   ).run(train_model, learning_rate=0.001)
   ```

4. Creating new runs for child tasks:

   ```python
   @wandb_init(run_mode="new")  # Always creates a new run
   @env.task
   async def independent_child() -> str:
       wandb_run = get_wandb_run()
       wandb_run.log({"independent_metric": 42})
       return wandb_run.id
   ```

5. Running sweep agents in parallel:

   ```python
   import asyncio
   from flyteplugins.wandb import wandb_sweep, get_wandb_sweep_id, get_wandb_context

   @wandb_init
   async def objective():
       wandb_run = wandb.run
       config = wandb_run.config
       ...

       wandb_run.log({"loss": loss_value})

   @wandb_sweep
   @env.task
   async def sweep_agent(agent_id: int, sweep_id: str, count: int = 5) -> int:
       wandb.agent(sweep_id, function=objective, count=count, project=get_wandb_context().project)
       return agent_id

   @wandb_sweep
   @env.task
   async def run_parallel_sweep(num_agents: int = 2, trials_per_agent: int = 5) -> str:
       sweep_id = get_wandb_sweep_id()

       # Launch agents in parallel
       agent_tasks = [
           sweep_agent(agent_id=i + 1, sweep_id=sweep_id, count=trials_per_agent)
           for i in range(num_agents)
       ]

       # Wait for all agents to complete
       await asyncio.gather(*agent_tasks)
       return sweep_id

   # Run with 2 parallel agents
   r = flyte.with_runcontext(
       custom_context={
           **wandb_config(project="my-project", entity="my-team"),
           **wandb_sweep_config(
               method="random",
               metric={"name": "loss", "goal": "minimize"},
               parameters={
                   "learning_rate": {"min": 0.0001, "max": 0.1},
                   "batch_size": {"values": [16, 32, 64]},
               }
           )
       }
   ).run(run_parallel_sweep, num_agents=2, trials_per_agent=5)
   ```

6. Distributed Training Support:

   The plugin auto-detects distributed training from environment variables
   (RANK, WORLD_SIZE, LOCAL_RANK, etc.) set by torchrun/torch.distributed.elastic.

   The `rank_scope` parameter controls the scope of run creation:
   - `"global"` (default): Global scope - 1 run/group across all workers
   - `"worker"`: Worker scope - 1 run/group per worker

   By default (`run_mode="auto"`, `rank_scope="global"`):
   - Single-node: Only rank 0 logs (1 run)
   - Multi-node: Only global rank 0 logs (1 run)

   ```python
   from flyteplugins.pytorch.task import Elastic
   from flyteplugins.wandb import wandb_init, get_wandb_run

   torch_env = flyte.TaskEnvironment(
       name="torch_env",
       resources=flyte.Resources(cpu=(1, 2), memory=("1Gi", "5Gi"), gpu="V100:4"),
       plugin_config=Elastic(nnodes=2, nproc_per_node=2),
   )

   @wandb_init
   @torch_env.task
   async def train_distributed():
       torch.distributed.init_process_group("nccl")

       # Only global rank 0 gets a W&B run, other ranks get None
       run = get_wandb_run()
       if run:
           run.log({"loss": loss})

       return run.id if run else "non-primary-rank"
   ```

   Use `rank_scope="worker"` to get 1 run per worker:

   ```python
   @wandb_init(rank_scope="worker")
   @torch_env.task
   async def train_distributed_per_worker():
       # Multi-node: local rank 0 of each worker gets a W&B run (1 run per worker)
       run = get_wandb_run()
       if run:
           run.log({"loss": loss})
       return run.id if run else "non-primary-rank"
   ```

   Use `run_mode="shared"` for all ranks to log to shared run(s):

   ```python
   @wandb_init(run_mode="shared")  # rank_scope="global": 1 shared run across all ranks
   @torch_env.task
   async def train_distributed_shared():
       # All ranks log to the same W&B run (with x_label to identify each rank)
       run = get_wandb_run()
       run.log({"rank_metric": value})
       return run.id

   @wandb_init(run_mode="shared", rank_scope="worker")  # 1 shared run per worker
   @torch_env.task
   async def train_distributed_shared_per_worker():
       run = get_wandb_run()
       run.log({"rank_metric": value})
       return run.id
   ```

   Use `run_mode="new"` for each rank to have its own W&B run:

   ```python
   @wandb_init(run_mode="new")  # rank_scope="global": all runs in 1 group
   @torch_env.task
   async def train_distributed_separate_runs():
       # Each rank gets its own W&B run (grouped in W&B UI)
       # Run IDs: {base}-rank-{global_rank}
       run = get_wandb_run()
       run.log({"rank_metric": value})
       return run.id

   @wandb_init(run_mode="new", rank_scope="worker")  # runs grouped per worker
   @torch_env.task
   async def train_distributed_separate_runs_per_worker():
       run = get_wandb_run()
       run.log({"rank_metric": value})
       return run.id
   ```

Decorator order: `@wandb_init` or `@wandb_sweep` must be the outermost decorator:

```python
@wandb_init
@env.task
async def my_task():
    ...
```
## Directory

### Classes

| Class | Description |
|-|-|
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb > Wandb** | Generates a Weights & Biases run link. |
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb > WandbSweep** | Generates a Weights & Biases Sweep link. |

### Methods

| Method | Description |
|-|-|
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb > Methods > download_wandb_run_dir()** | Download wandb run data from wandb cloud. |
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb > Methods > download_wandb_run_logs()** | Traced function to download wandb run logs after task completion. |
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb > Methods > download_wandb_sweep_dirs()** | Download all run data for a wandb sweep. |
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb > Methods > download_wandb_sweep_logs()** | Traced function to download wandb sweep logs after task completion. |
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb > Methods > get_distributed_info()** | Get distributed training info if running in a distributed context. |
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb > Methods > get_wandb_context()** | Get wandb config from current Flyte context. |
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb > Methods > get_wandb_run()** | Get the current wandb run if within a `@wandb_init` decorated task or trace. |
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb > Methods > get_wandb_run_dir()** | Get the local directory path for the current wandb run. |
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb > Methods > get_wandb_sweep_context()** | Get wandb sweep config from current Flyte context. |
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb > Methods > get_wandb_sweep_id()** | Get the current wandb `sweep_id` if within a `@wandb_sweep` decorated task. |
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb > Methods > wandb_config()** | Create wandb configuration. |
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb > Methods > wandb_init()** | Decorator to automatically initialize wandb for Flyte tasks and wandb sweep objectives. |
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb > Methods > wandb_sweep()** | Decorator to create a wandb sweep and make `sweep_id` available. |
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb > Methods > wandb_sweep_config()** | Create wandb sweep configuration for hyperparameter optimization. |

## Methods

#### download_wandb_run_dir()

```python
def download_wandb_run_dir(
    run_id: typing.Optional[str],
    path: typing.Optional[str],
    include_history: bool,
) -> str
```
Download wandb run data from wandb cloud.

Downloads all run files and optionally exports metrics history to JSON.
This enables access to wandb data from any task or after workflow completion.

Downloaded contents:

    - summary.json - final summary metrics (always exported)
    - metrics_history.json - step-by-step metrics (if include_history=True)
    - Plus any files synced by wandb (requirements.txt, wandb_metadata.json, etc.)

| Parameter | Type | Description |
|-|-|-|
| `run_id` | `typing.Optional[str]` | The wandb run ID to download. If `None`, uses the current run's ID from context (useful for shared runs across tasks). |
| `path` | `typing.Optional[str]` | Local directory to download files to. If `None`, downloads to `/tmp/wandb_runs/{run_id}`. |
| `include_history` | `bool` | If `True`, exports the step-by-step metrics history to `metrics_history.json`. Defaults to `True`. |

**Returns**

Local path where files were downloaded.

**Raises**

| Exception | Description |
|-|-|
| ``RuntimeError`` | If no `run_id` provided and no active run in context. |
| ``wandb.errors.CommError`` | If run not found in wandb cloud. |

> [!NOTE]
> There may be a brief delay between when files are written locally and
> when they're available in wandb cloud. For immediate local access
> within the same task, use `get_wandb_run_dir()` instead.

#### download_wandb_run_logs()

CODE11
Traced function to download wandb run logs after task completion.

This function is called automatically when `download_logs=True` is set
in `@wandb_init` or `wandb_config()`. The downloaded files appear as a
trace output in the Flyte UI.

| Parameter | Type | Description |
|-|-|-|
| `run_id` | `str` | The wandb run ID to download. |

**Returns**

Dir containing the downloaded wandb run files.

**Raises**

| Exception | Description |
|-|-|
| `RuntimeError` | If download fails (network error, run not found, auth failure, etc.) |

#### download_wandb_sweep_dirs()

CODE12
Download all run data for a wandb sweep.

Queries the wandb API for all runs in the sweep and downloads their files
and metrics history. This is useful for collecting results from all sweep
trials after completion.

| Parameter | Type | Description |
|-|-|-|
| `sweep_id` | `typing.Optional[str]` | The wandb sweep ID. If `None`, uses the current sweep's ID from context (set by `@wandb_sweep` decorator). |
| `base_path` | `typing.Optional[str]` | Base directory to download files to. Each run's files will be in a subdirectory named by run_id. If `None`, uses `/tmp/wandb_runs/`. |
| `include_history` | `bool` | If `True`, exports the step-by-step metrics history to metrics_history.json for each run. Defaults to `True`. |

**Returns**

List of local paths where run data was downloaded.

**Raises**

| Exception | Description |
|-|-|
| `RuntimeError` | If no sweep_id provided and no active sweep in context. |
| `wandb.errors.CommError` | If sweep not found in wandb cloud. |

#### download_wandb_sweep_logs()

CODE13
Traced function to download wandb sweep logs after task completion.

This function is called automatically when `download_logs=True` is set
in `@wandb_sweep` or `wandb_sweep_config()`. The downloaded files appear as a
trace output in the Flyte UI.

| Parameter | Type | Description |
|-|-|-|
| `sweep_id` | `str` | The wandb sweep ID to download. |

**Returns**

Dir containing the downloaded wandb sweep run files.

**Raises**

| Exception | Description |
|-|-|
| `RuntimeError` | If download fails (network error, sweep not found, auth failure, etc.) |

#### get_distributed_info()

CODE14
Get distributed training info if running in a distributed context.

This function auto-detects distributed training from environment variables
set by torchrun/torch.distributed.elastic.

**Returns**

dict | None: Dictionary with distributed info or None if not distributed.
    - rank: Global rank (0 to world_size-1)
    - local_rank: Rank within the node (0 to local_world_size-1)
    - world_size: Total number of processes
    - local_world_size: Processes per node
    - worker_index: Node/worker index (0 to num_workers-1)
    - num_workers: Total number of nodes/workers

#### get_wandb_context()

CODE15
Get wandb config from current Flyte context.

#### get_wandb_run()

CODE16
Get the current wandb run if within a `@wandb_init` decorated task or trace.

The run is initialized when the `@wandb_init` context manager is entered.
Returns None if not within a `wandb_init` context.

**Returns:** `wandb.sdk.wandb_run.Run` | `None`: The current wandb run object or None.

#### get_wandb_run_dir()

CODE17
Get the local directory path for the current wandb run.

Use this for accessing files written by the current task without any
network calls. For accessing files from other tasks (or after a task
completes), use `download_wandb_run_dir()` instead.

**Returns**

Local path to wandb run directory (`wandb.run.dir`) or `None` if no
active run.

#### get_wandb_sweep_context()

CODE18
Get wandb sweep config from current Flyte context.

#### get_wandb_sweep_id()

CODE19
Get the current wandb `sweep_id` if within a `@wandb_sweep` decorated task.

Returns `None` if not within a `wandb_sweep` context.

**Returns:** `str` | `None`: The sweep ID or None.

#### wandb_config()

CODE20
Create wandb configuration.

This function works in two contexts:
1. With `flyte.with_runcontext()` - sets global wandb config
2. As a context manager - overrides config for specific tasks

| Parameter | Type | Description |
|-|-|-|
| `project` | `typing.Optional[str]` | W&B project name |
| `entity` | `typing.Optional[str]` | W&B entity (team or username) |
| `host` | `typing.Optional[str]` | Base W&B host URL (e.g., "https://wandb.ai" or a self-hosted instance) |
| `id` | `typing.Optional[str]` | Unique run id (auto-generated if not provided) |
| `name` | `typing.Optional[str]` | Human-readable run name |
| `tags` | `typing.Optional[list[str]]` | List of tags for organizing runs |
| `config` | `typing.Optional[dict[str, typing.Any]]` | Dictionary of hyperparameters |
| `mode` | `typing.Optional[str]` | "online", "offline" or "disabled" |
| `group` | `typing.Optional[str]` | Group name for related runs |
| `run_mode` | `typing.Literal['auto', 'new', 'shared']` | "auto", "new" or "shared". Controls whether tasks create new W&B runs or share existing ones. - "auto" (default): Creates new run if no parent run exists, otherwise shares parent's run - "new": Always creates a new wandb run with a unique ID - "shared": Always shares the parent's run ID In distributed training context (single-node): - "auto" (default): Only rank 0 logs. - "shared": All ranks log to a single shared W&B run. - "new": Each rank gets its own W&B run (grouped in W&B UI). Multi-node: behavior depends on `rank_scope`. |
| `rank_scope` | `typing.Literal['global', 'worker']` | "global" or "worker". Controls which ranks log in distributed training. run_mode="auto": - "global" (default): Only global rank 0 logs (1 run total). - "worker": Local rank 0 of each worker logs (1 run per worker). run_mode="shared": - "global": All ranks log to a single shared W&B run. - "worker": Ranks per worker log to a single shared W&B run (1 run per worker). run_mode="new": - "global": Each rank gets its own W&B run (1 run total). - "worker": Each rank gets its own W&B run grouped per worker -&gt; N runs. |
| `download_logs` | `bool` | If `True`, downloads wandb run files after task completes and shows them as a trace output in the Flyte UI |
| `kwargs` | `**kwargs` | |

#### wandb_init()

CODE21
Decorator to automatically initialize wandb for Flyte tasks and wandb sweep objectives.

Decorator Order:
    For tasks, @wandb_init must be the outermost decorator:
    @wandb_init
    @env.task
    async def my_task():
        ...

This decorator:
1. Initializes wandb when the context manager is entered
2. Auto-generates unique run ID from Flyte action context if not provided
3. Makes the run available via get_wandb_run()
4. Automatically adds a W&B link to the task in the Flyte UI
5. Automatically finishes the run after completion
6. Optionally downloads run logs as a trace output (if download_logs=True)

| Parameter | Type | Description |
|-|-|-|
| `_func` | `typing.Optional[~F]` | |
| `run_mode` | `typing.Optional[typing.Literal['auto', 'new', 'shared']]` | Controls whether to create a new W&B run or share an existing one: - "auto" (default): Creates new run if no parent run exists, otherwise shares parent's run - "new": Always creates a new wandb run with a unique ID - "shared": Always shares the parent's run ID (useful for child tasks) In distributed training context (single-node): - "auto" (default): Only rank 0 logs. - "shared": All ranks log to a single shared W&B run. - "new": Each rank gets its own W&B run (grouped in W&B UI). Multi-node: behavior depends on `rank_scope`. |
| `rank_scope` | `typing.Optional[typing.Literal['global', 'worker']]` | Flyte-specific rank scope - "global" or "worker". Controls which ranks log in distributed training. run_mode="auto": - "global" (default): Only global rank 0 logs (1 run total). - "worker": Local rank 0 of each worker logs (1 run per worker). run_mode="shared": - "global": All ranks log to a single shared W&B run. - "worker": Ranks per worker log to a single shared W&B run (1 run per worker). run_mode="new": - "global": Each rank gets its own W&B run (1 run total). - "worker": Each rank gets its own W&B run grouped per worker -&gt; N runs. |
| `download_logs` | `typing.Optional[bool]` | If `True`, downloads wandb run files after task completes and shows them as a trace output in the Flyte UI. If None, uses the value from `wandb_config()` context if set. |
| `project` | `typing.Optional[str]` | W&B project name (overrides context config if provided) |
| `entity` | `typing.Optional[str]` | W&B entity/team name (overrides context config if provided) |
| `kwargs` | `**kwargs` | |

#### wandb_sweep()

CODE22
Decorator to create a wandb sweep and make `sweep_id` available.

This decorator:
1. Creates a wandb sweep using config from context
2. Makes `sweep_id` available via `get_wandb_sweep_id()`
3. Automatically adds a W&B sweep link to the task
4. Optionally downloads all sweep run logs as a trace output (if `download_logs=True`)

Decorator Order:
    For tasks, @wandb_sweep must be the outermost decorator:
    @wandb_sweep
    @env.task
    async def my_task():
        ...

| Parameter | Type | Description |
|-|-|-|
| `_func` | `typing.Optional[~F]` | |
| `project` | `typing.Optional[str]` | W&B project name (overrides context config if provided) |
| `entity` | `typing.Optional[str]` | W&B entity/team name (overrides context config if provided) |
| `download_logs` | `typing.Optional[bool]` | if `True`, downloads all sweep run files after task completes and shows them as a trace output in the Flyte UI. If None, uses the value from wandb_sweep_config() context if set. |
| `kwargs` | `**kwargs` | |

#### wandb_sweep_config()

CODE23
Create wandb sweep configuration for hyperparameter optimization.

See: https://docs.wandb.ai/models/sweeps/sweep-config-keys

| Parameter | Type | Description |
|-|-|-|
| `method` | `typing.Optional[str]` | Sweep method (e.g., "random", "grid", "bayes") |
| `metric` | `typing.Optional[dict[str, typing.Any]]` | Metric to optimize (e.g., {"name": "loss", "goal": "minimize"}) |
| `parameters` | `typing.Optional[dict[str, typing.Any]]` | Parameter definitions for the sweep |
| `project` | `typing.Optional[str]` | W&B project for the sweep |
| `entity` | `typing.Optional[str]` | W&B entity for the sweep |
| `prior_runs` | `typing.Optional[list[str]]` | List of prior run IDs to include in the sweep analysis |
| `name` | `typing.Optional[str]` | Sweep name (auto-generated as `{run_name}-{action_name}` if not provided) |
| `download_logs` | `bool` | If `True`, downloads all sweep run files after task completes and shows them as a trace output in the Flyte UI |
| `kwargs` | `**kwargs` | |

## Subpages
- **Integrations > Weights & Biases > Packages > flyteplugins.wandb > Wandb**
- **Integrations > Weights & Biases > Packages > flyteplugins.wandb > WandbSweep**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/wandb/packages/flyteplugins.wandb/wandb ===

# Wandb

**Package:** `flyteplugins.wandb`

Generates a Weights & Biases run link.

## Parameters

```python
class Wandb(
    host: str,
    project: typing.Optional[str],
    entity: typing.Optional[str],
    run_mode: typing.Literal['auto', 'new', 'shared'],
    rank_scope: typing.Literal['global', 'worker'],
    id: typing.Optional[str],
    name: str,
    _is_distributed: bool,
    _worker_index: typing.Optional[int],
)
```
| Parameter | Type | Description |
|-|-|-|
| `host` | `str` | Base W&B host URL |
| `project` | `typing.Optional[str]` | W&B project name (overrides context config if provided) |
| `entity` | `typing.Optional[str]` | W&B entity/team name (overrides context config if provided) |
| `run_mode` | `typing.Literal['auto', 'new', 'shared']` | Determines the link behavior: - "auto" (default): Use parent's run if available, otherwise create new - "new": Always creates a new wandb run with a unique ID - "shared": Always shares the parent's run ID In distributed training context (single-node): - "auto" (default): Only rank 0 logs. - "shared": All ranks log to a single shared W&B run. - "new": Each rank gets its own W&B run (grouped in W&B UI). Multi-node: behavior depends on `rank_scope`. |
| `rank_scope` | `typing.Literal['global', 'worker']` | Flyte-specific rank scope - "global" or "worker". Controls which ranks log in distributed training. run_mode="auto": - "global" (default): Only global rank 0 logs (1 run total). - "worker": Local rank 0 of each worker logs (1 run per worker). run_mode="shared": - "global": All ranks log to a single shared W&B run. - "worker": Ranks per worker log to a single shared W&B run (1 run per worker). run_mode="new": - "global": Each rank gets its own W&B run (1 run total). - "worker": Each rank gets its own W&B run grouped per worker -&gt; N runs. |
| `id` | `typing.Optional[str]` | Optional W&B run ID (overrides context config if provided) |
| `name` | `str` | Link name in the Flyte UI |
| `_is_distributed` | `bool` | |
| `_worker_index` | `typing.Optional[int]` | |

## Methods

| Method | Description |
|-|-|
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb > Wandb > Methods > get_link()** | Returns a task log link given the action. |

### get_link()

```python
def get_link(
    run_name: str,
    project: str,
    domain: str,
    context: typing.Dict[str, str],
    parent_action_name: str,
    action_name: str,
    pod_name: str,
    kwargs,
) -> str
```
Returns a task log link given the action.
Link can have template variables that are replaced by the backend.

| Parameter | Type | Description |
|-|-|-|
| `run_name` | `str` | The name of the run. |
| `project` | `str` | The project name. |
| `domain` | `str` | The domain name. |
| `context` | `typing.Dict[str, str]` | Additional context for generating the link. |
| `parent_action_name` | `str` | The name of the parent action. |
| `action_name` | `str` | The name of the action. |
| `pod_name` | `str` | The name of the pod. |
| `kwargs` | `**kwargs` | Additional keyword arguments. |

**Returns:** The generated link.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/integrations/wandb/packages/flyteplugins.wandb/wandbsweep ===

# WandbSweep

**Package:** `flyteplugins.wandb`

Generates a Weights & Biases Sweep link.

## Parameters

```python
class WandbSweep(
    host: str,
    project: typing.Optional[str],
    entity: typing.Optional[str],
    id: typing.Optional[str],
    name: str,
)
```
| Parameter | Type | Description |
|-|-|-|
| `host` | `str` | Base W&B host URL |
| `project` | `typing.Optional[str]` | W&B project name (overrides context config if provided) |
| `entity` | `typing.Optional[str]` | W&B entity/team name (overrides context config if provided) |
| `id` | `typing.Optional[str]` | Optional W&B sweep ID (overrides context config if provided) |
| `name` | `str` | Link name in the Flyte UI |

## Methods

| Method | Description |
|-|-|
| **Integrations > Weights & Biases > Packages > flyteplugins.wandb > WandbSweep > Methods > get_link()** | Returns a task log link given the action. |

### get_link()

```python
def get_link(
    run_name: str,
    project: str,
    domain: str,
    context: typing.Dict[str, str],
    parent_action_name: str,
    action_name: str,
    pod_name: str,
    kwargs,
) -> str
```
Returns a task log link given the action.
Link can have template variables that are replaced by the backend.

| Parameter | Type | Description |
|-|-|-|
| `run_name` | `str` | The name of the run. |
| `project` | `str` | The project name. |
| `domain` | `str` | The domain name. |
| `context` | `typing.Dict[str, str]` | Additional context for generating the link. |
| `parent_action_name` | `str` | The name of the parent action. |
| `action_name` | `str` | The name of the action. |
| `pod_name` | `str` | The name of the pod. |
| `kwargs` | `**kwargs` | Additional keyword arguments. |

**Returns:** The generated link.


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli ===

# Uctl CLI

The `uctl` CLI provides functionality for Union administrators to manage Union-specific entities like users, roles, and Union configuration.

It also includes much of the functionality of the `union` CLI, but since it is a compiled binary (written in Go), it is faster and more efficient than the Python-based `union` CLI and more suitable for situations like running in a CI/CD environment where you might want to avoid the overhead of large Python dependencies.

> [!NOTE]
> If you are not a Union administrator, or if you will be interacting with Union in an environment where
> Python is installed, you should use the `union` CLI instead.

## Installation

### macOS

To install `uctl` on a Mac, use [Homebrew](https://brew.sh/), `curl`, or manually download the binary.

**Homebrew**

```shell
$ brew tap unionai/homebrew-tap
$ brew install uctl
```

**curl**

To use `curl`, set `BINDIR` to the install location (it defaults to `./bin`) and run the following command:

```shell
$ curl -sL https://raw.githubusercontent.com/unionai/uctl/main/install.sh | bash
```

**Manual download**

To download the binary manually, see the [`uctl` releases page](https://github.com/unionai/uctl/releases).

### Linux

To install `uctl` on Linux, use `curl` or manually download the binary.

**curl**

To use `curl`, set `BINDIR` to the install location (it defaults to `./bin`) and run the following command:

```shell
$ curl -sL https://raw.githubusercontent.com/unionai/uctl/main/install.sh | bash
```

**Manual download**

To download the binary manually, see the [`uctl` releases page](https://github.com/unionai/uctl/releases).

### Windows

To install `uctl` on Windows, use `curl` or manually download the binary.

**curl**

To use `curl`, in a Linux shell (such as [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)), set `BINDIR` to the install location (it defaults to `./bin`) and run the following command:

```shell
$ curl -sL https://raw.githubusercontent.com/unionai/uctl/main/install.sh | bash
```

**Manual download**

To download the binary manually, see the [`uctl` releases page](https://github.com/unionai/uctl/releases).

## Configuration

To create a configuration file that contains your Union connection information, run the following command, replacing `<union-host-url>` with the URL of your Union instance:

```shell
$ uctl config init --host <union-host-url>
```

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

```yaml
admin:
  endpoint: dns:///<union-host-url>
  insecure: false
  authType: Pkce
```

> [!NOTE]
> PKCE is the default authentication type. To specify a different authentication type in the configuration file,
> see the authentication documentation.

### Configuration file location hierarchy

By default, the `uctl` CLI will use the configuration file at `~/.union/config.yaml` to connect to your Union instance unless you override it. `uctl` searches for configuration files in the following order:

* `--config <path-to-config>` flag
* `UNION_CONFIG` environment variable
* `UCTL_CONFIG` environment variable
* `~/.union/config.yaml` file
* `~/.uctl/config.yaml` file

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultServiceConfig` | string  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string  | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `-c`, `--config` | string | config file (default is $HOME/.flyte/config.yaml) |
| `--console.endpoint` | string | Endpoint of console, if different than flyte admin |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount` |
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization.
| `-h`, `--help` | | help for uctl |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "TABLE") |
| `-p`, `--project` | string | Specifies the Flyte project.
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |

## Commands

* `uctl apply {uctl-apply/index}` is used for updating various Union/Flyte resources, including cluster configs.
* `uctl config {uctl-config/index}` runs various config commands.

* `uctl create {uctl-create/index}` creates various Flyte resources such as tasks, workflows, launch plans, executions, and projects.
* `uctl delete {uctl-delete/index}` terminates/deletes various Flyte resources, such as executions and resource attributes.
* `uctl demo {uctl-demo/index}` provides commands for starting and interacting with a standalone minimal
                                local environment for running Flyte.
* `uctl get {uctl-get/index}` fetches various Flyte resources such as tasks, workflows, launch plans, executions, and projects.
* `uctl register {uctl-register/index}` registers tasks, workflows, and launch plans from a list of generated serialized files.
* `uctl update {uctl-update/index}` update Flyte resources e.g., projects.
* `uctl version {uctl-version>` fetches `uctl` version.

## Entities

| Entity | Commands |
|--------|----------|
| Cluster resource attribute | **Uctl CLI > uctl get > uctl get cluster-resource-attribute**
**Uctl CLI > uctl update > uctl update cluster-resource-attribute**
**Uctl CLI > uctl delete > uctl delete cluster-resource-attribute** |
| Config | **Uctl CLI > uctl config > uctl config init**
**Uctl CLI > uctl config > uctl config discover**
**Uctl CLI > uctl config > uctl config docs**
**Uctl CLI > uctl config > uctl config validate** |
| Demo | **Uctl CLI > uctl demo > uctl demo start**
**Uctl CLI > uctl demo > uctl demo status**
**Uctl CLI > uctl demo > uctl demo exec**
**Uctl CLI > uctl demo > uctl demo reload**
**Uctl CLI > uctl demo > uctl demo teardown** |
| Execution | **Uctl CLI > uctl create > uctl create execution**
**Uctl CLI > uctl get > uctl get execution**
**Uctl CLI > uctl update > uctl update execution**
**Uctl CLI > uctl delete > uctl delete execution** |
| Execution cluster label | **Uctl CLI > uctl get > uctl get execution-cluster-label**
**Uctl CLI > uctl update > uctl update execution-cluster-label**
**Uctl CLI > uctl delete > uctl delete execution-cluster-label** |
| Execution queue attribute | **Uctl CLI > uctl get > uctl get execution-queue-attribute**
**Uctl CLI > uctl update > uctl update execution-queue-attribute**
**Uctl CLI > uctl delete > uctl delete execution-queue-attribute** |
| Files |  **Uctl CLI > uctl register > uctl register files** |
| Launch plan | **Uctl CLI > uctl get > uctl get launchplan**
**Uctl CLI > uctl update > uctl update launchplan**
**Uctl CLI > uctl update > uctl update launchplan-meta** |
| Plugin override | **Uctl CLI > uctl get > uctl get plugin-override**
**Uctl CLI > uctl update > uctl update plugin-override**
**Uctl CLI > uctl delete > uctl delete plugin-override** |
| Project | **Uctl CLI > uctl create > uctl create project**
**Uctl CLI > uctl get > uctl get project**
**Uctl CLI > uctl update > uctl update project** |
| Task | **Uctl CLI > uctl get > uctl get task**
**Uctl CLI > uctl update > uctl update task-meta** |
| Task resource attribute | **Uctl CLI > uctl get > uctl get task-resource-attribute**
**Uctl CLI > uctl update > uctl update task-resource-attribute**
**Uctl CLI > uctl delete > uctl delete task-resource-attribute** |
| Workflow | **Uctl CLI > uctl get > uctl get workflow**
**Uctl CLI > uctl update > uctl update workflow-meta** |
| Workflow execution config | **Uctl CLI > uctl get > uctl get workflow-execution-config**
**Uctl CLI > uctl update > uctl update workflow-execution-config**
**Uctl CLI > uctl delete > uctl delete workflow-execution-config** |

## Subpages
- **Uctl CLI > uctl**
- **Uctl CLI > uctl version**
- **Uctl CLI > uctl append**
- **Uctl CLI > uctl apply**
- **Uctl CLI > uctl config**
- **Uctl CLI > uctl create**
- **Uctl CLI > uctl delete**
- **Uctl CLI > uctl demo**
- **Uctl CLI > uctl get**
- **Uctl CLI > uctl register**
- **Uctl CLI > uctl update**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl ===

# uctl

uctl is used to interact with Union.ai Cloud

## Synopsis

uctl is used to interact with Union.ai Cloud

Lets you manage Flyte entities (Projects, Domains, Workflows, Tasks, and
Launch plans), Users, Roles, and Union.ai Cloud configuration.

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount` |
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `-h`, `--help` | help for uctl |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-version ===

# uctl version

Fetches uctl version

## Synopsis

Fetch uctl version:

```shell
$ uctl version

$ uctl version [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for version |

## Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount` |
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-append ===

# uctl append

Used for updating various Union resources including
tasks/workflows/launchplans/executions/project.

# Synopsis

Used for updating various union/flyte resources including
tasks/workflows/launchplans/executions/project.

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for append |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount` |
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |

## Subpages
- **Uctl CLI > uctl append > uctl append identityassignments**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-append/uctl-append-identityassignments ===

# uctl append identityassignments

Assigns a role to a specific user or application

## Synopsis

Assigns a policy to a specific user or application.

A policy must already exist within your organization.
Default policies include

* `viewer`: Permissions to view Flyte entities:
* `contributor`: Permissions to create workflows, tasks, launch plans, and executions, plus all `viewer` permissions.
* `admin`: Permissions to manage users and view usage dashboards, plus all `contributor`permissions.

To append to a user's identity assignments, specify them by their email
and run:

```shell
$ uctl append identityassignments --user bob@contoso.com --policy contributor
```

To append a policy assignment to an application, specify the application
by its unique client id and run:

```shell
$ uctl append identityassignments --application "contoso-operator" --policy admin
```

Hint: you can fetch an application's ID by listing apps:

```shell
$ uctl get apps
```

You can list the existing policies in your org with:

```shell
$ uctl get policies
```

You can list existing policy assignments with:

```shell
$ uctl get identityassignments --user bob@contoso.com

$ uctl get identityassignments --application "contoso-operator"

$ uctl append identityassignments [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--application` | string | Application id to fetch identity assignments for |
| `-h`, `--help` | help for identityassignments |
| `--policy` | string | Policy name with which to update the identity assignment |
| `--user` | string | Human user email to fetch identity assignments for |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-apply ===

# uctl apply

Used for updating various union/flyte resources including
tasks/workflows/launchplans/executions/project.

## Synopsis

Eg: Update Union.ai resources of app for a tenant:

```shell
$ uctl apply app --appSpecFile Tenant-AppSpec.yaml
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for apply |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |

## Subpages
- **Uctl CLI > uctl apply > uctl apply app**
- **Uctl CLI > uctl apply > uctl apply clusterconfig**
- **Uctl CLI > uctl apply > uctl apply clusterconfigid**
- **Uctl CLI > uctl apply > uctl apply clusterpoolconfig**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-apply/uctl-apply-app ===

# uctl apply app

Updates apps config in configured OAuthProvider

## Synopsis

Updates apps config in configured OAuthProvider:

```shell
$ uctl apply app [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--appSpecFile` | string | app spec file to be used for updating app. |
| `--dryRun` | | execute command without making any modifications. |
| `-h`, `--help` | help for app |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-apply/uctl-apply-clusterconfig ===

# uctl apply clusterconfig

Updates cluster config

## Synopsis

Updates cluster config:

```shell
$ uctl apply clusterconfig [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--dryRun` | | execute command without making any modifications. |
| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for clusterconfig |
| `--specFile` | string | spec file to be used to update cluster config. |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-apply/uctl-apply-clusterconfigid ===

# uctl apply clusterconfigid

Assign cluster config

## Synopsis

Assign cluster config:

```shell
$ uctl apply clusterconfigid [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--clusterName` | string | Specifies cluster name which config to update |
| `--configID` | string | Specifies config ID to assign to the cluster |
| `--dryRun` | | execute command without making any modifications. |
| `-h`, `--help` | help for clusterconfigid |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-apply/uctl-apply-clusterpoolconfig ===

# uctl apply clusterpoolconfig

Updates cluster pool config

## Synopsis

Updates cluster pool config:

```shell
$ uctl apply clusterpoolconfig [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--clusterPoolSpecFile` | string | cluster pool spec file to be used for updating cluster pool. |
| `--dryRun` | | execute command without making any modifications. |
| `-h`, `--help` | help for clusterpoolconfig |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-config ===

# uctl config

Runs various config commands, look at the help of this command to get a
list of available commands..

## Synopsis

Runs various config commands, look at the help of this command to get a
list of available commands..

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--file` | stringArray | Passes the config file to load. |
                         If empty, it'll first search for the config file path then, if found, will load config from there.
| `--force` | | Force to overwrite the default config file without confirmation |
| `-h`, `--help` | help for config |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |

## Subpages
- **Uctl CLI > uctl config > uctl config discover**
- **Uctl CLI > uctl config > uctl config docs**
- **Uctl CLI > uctl config > uctl config init**
- **Uctl CLI > uctl config > uctl config validate**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-config/uctl-config-discover ===

# uctl config discover

Searches for a config in one of the default search paths.

## Synopsis

Searches for a config in one of the default search paths.

```shell
$ uctl config discover [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for discover |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--file` | stringArray | Passes the config file to load. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-config/uctl-config-docs ===

# uctl config docs

Generate configuration documentation in rst format

## Synopsis

Generate configuration documentation in rst format

```shell
$ uctl config docs [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for docs |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--file` | stringArray | Passes the config file to load. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-config/uctl-config-init ===

# uctl config init

Generates a Flytectl config file in the user's home directory.

## Synopsis

Creates a Flytectl config file in Flyte directory i.e `~/.flyte`.

Generate Sandbox config:

```shell
$ uctl config init
```

Flyte Sandbox is a fully standalone minimal environment for running
Flyte.

Generate remote cluster config:

```shell
$ uctl config init --host=flyte.myexample.com
```

By default, the connection is secure.

Generate remote cluster config with insecure connection:

```shell
$ uctl config init --host=flyte.myexample.com --insecure
```

Generate remote cluster config with separate console endpoint:

```shell
$ uctl config init --host=flyte.myexample.com --console=console.myexample.com
```

Generate Flytectl config with a storage provider:

```shell
$ uctl config init --host=flyte.myexample.com --storage
```

```shell
$ uctl config init [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--console` | string | Endpoint of console,  if different than flyte admin |
| `--force` | | Force to overwrite the default config file without confirmation |
| `-h`, `--help` | help for init |
| `--host` | string | Endpoint of flyte admin |
| `--insecure` | | Enable insecure mode |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--file` | stringArray | Passes the config file to load. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-config/uctl-config-validate ===

# uctl config validate

Validates the loaded config.

## Synopsis

Validates the loaded config.

```shell
$ uctl config validate [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for validate |
| `--strict` | | Validates that all keys in loaded config |
                   map to already registered sections.

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--file` | stringArray | Passes the config file to load. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-create ===

# uctl create

Used for creating various union/flyte resources including apps, cluster
pools, cluster configs

## Synopsis

Create Flyte resource; if a project:

```shell
$ uctl create project --file project.yaml
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for create |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |

## Subpages
- **Uctl CLI > uctl create > uctl create app**
- **Uctl CLI > uctl create > uctl create clusterpool**
- **Uctl CLI > uctl create > uctl create clusterpoolassignment**
- **Uctl CLI > uctl create > uctl create execution**
- **Uctl CLI > uctl create > uctl create policy**
- **Uctl CLI > uctl create > uctl create project**
- **Uctl CLI > uctl create > uctl create role**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-create/uctl-create-app ===

# uctl create app

Create apps

## Synopsis

Create apps

```shell
$ uctl create app [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--appSpecFile` | string | app spec file to be used for creating app. |
| `--dryRun` | | execute command without making any modifications. |
| `--gen` | | generates an empty app config file with conformance to the api format. |
| `-h`, `--help` | help for app |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-create/uctl-create-clusterpool ===

# uctl create clusterpool

Create cluster pools

## Synopsis

Create cluster pools

```shell
$ uctl create clusterpool [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--clusterPoolSpecFile` | string | cluster pool spec file to be used for creating cluster pool. |
| `--dryRun` | | execute command without making any modifications. |
| `--genSkeleton` | | generates a skeleton cluster pool config file with templatized values in full conformance with the api format. |
| `-h`, `--help` | help for clusterpool |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-create/uctl-create-clusterpoolassignment ===

# uctl create clusterpoolassignment

Create cluster pool assignments

## Synopsis

Create cluster pool assignments

```shell
$ uctl create clusterpoolassignment [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--clusterName` | string | Assign cluster with this name |
| `-h`, `--help` | help for clusterpoolassignment |
| `--poolName` | string | Assign cluster to this pool |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-create/uctl-create-execution ===

# uctl create execution

Creates execution resources.

## Synopsis

Create execution resources for a given workflow or task in a project and
domain.

There are three steps to generate an execution, as outlined below:

1. Generate the execution spec file using the
`get task` command:

```shell
uctl get tasks -d development -p flytesnacks core.control_flow.merge_sort.merge --version v2 --execFile execution_spec.yaml
```
The generated file would look similar to the following:

``` yaml
iamRoleARN: ""
inputs:
sorted_list1:
- 0
sorted_list2:
- 0
kubeServiceAcct: ""
targetDomain: ""
targetProject: ""
task: core.control_flow.merge_sort.merge
version: "v2"
```

2. [Optional] Update the inputs for the execution, if needed. The
generated spec file can be modified to change the input values, as shown
below:

``` yaml
iamRoleARN: 'arn:aws:iam::12345678:role/defaultrole'
inputs:
sorted_list1:
- 2
- 4
- 6
sorted_list2:
- 1
- 3
- 5
kubeServiceAcct: ""
targetDomain: ""
targetProject: ""
task: core.control_flow.merge_sort.merge
version: "v2"
```

3. [Optional] Update the envs for the execution, if needed. The
generated spec file can be modified to change the envs values, as shown
below:

``` yaml
iamRoleARN: ""
inputs:
sorted_list1:
- 0
sorted_list2:
- 0
envs:
  foo: bar
kubeServiceAcct: ""
targetDomain: ""
targetProject: ""
task: core.control_flow.merge_sort.merge
version: "v2"
```

1. Run the execution by passing the generated YAML file. The file can
then be passed through the command line. It is worth noting that the
source's and target's project and domain can be different:

```shell
$ uctl create execution --execFile execution_spec.yaml -p flytesnacks -d staging --targetProject flytesnacks
```

1.  To relaunch an execution, pass the current execution ID as follows:

```shell
$ uctl create execution --relaunch ffb31066a0f8b4d52b77 -p flytesnacks -d development
```

6.  To recover an execution, i.e., recreate it from the last known
    failure point for previously-run workflow execution, run:

```shell
$ uctl create execution --recover ffb31066a0f8b4d52b77 -p flytesnacks -d development
```

1. You can create executions idempotently by naming them. This is also
a way to *name* an execution for discovery. Note, an execution id has to
be unique within a project domain. So if the *name* matches an existing
execution an already exists exceptioj will be raised.

```shell
$ uctl create execution --recover ffb31066a0f8b4d52b77 -p flytesnacks -d development custom_name
```

1. Generic/Struct/Dataclass/JSON types are supported for execution in a
similar manner. The following is an example of how generic data can be
specified while creating the execution.

```shell
$ uctl get task -d development -p flytesnacks  core.type_system.custom_objects.add --execFile adddatanum.yaml
```

The generated file would look similar to this. Here, empty values have
been dumped for generic data types `x` and `y`:

```yaml
iamRoleARN: ""
inputs:
  "x": {}
  "y": {}
kubeServiceAcct: ""
targetDomain: ""
targetProject: ""
task: core.type_system.custom_objects.add
version: v3
```

9.  Modified file with struct data populated for 'x' and 'y'
    parameters for the task "core.type_system.custom_objects.add":

```yaml
iamRoleARN: "arn:aws:iam::123456789:role/dummy"
inputs:
  "x":
    "x": 2
    "y": ydatafory
    "z":
      1: "foo"
      2: "bar"
  "y":
    "x": 3
    "y": ydataforx
    "z":
      3: "buzz"
      4: "lightyear"
kubeServiceAcct: ""
targetDomain: ""
targetProject: ""
task: core.type_system.custom_objects.add
version: v3
```

1.  If you have configured a plugin that implements `WorkflowExecutor`
that supports cluster pools, then when creating a new execution, you
can assign it to a specific cluster pool:

```shell
$ uctl create execution --execFile execution_spec.yaml -p flytesnacks -d development --clusterPool my-gpu-cluster
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--clusterPool` | string | specify which cluster pool to assign execution to. |
| `--dryRun` | | execute command without making any modifications. |
| `--execFile` | string | file for the execution params. If not specified defaults to {<workflow/task>_name}.execution_spec.yaml |
| `-h`, `--help` | help for execution |
| `--iamRoleARN` | string | iam role ARN AuthRole for launching execution. |
| `--kubeServiceAcct` | string | kubernetes service account AuthRole for launching execution. |
| `--overwriteCache` | | skip cached results when performing execution, causing all outputs to be re-calculated and stored data to be overwritten. Does not work for recovered executions. |
| `--recover` | string | execution id to be recreated from the last known failure point. |
| `--relaunch` | string | execution id to be relaunched. |
| `--targetDomain` | string | project where execution needs to be created. If not specified configured domain would be used. |
| `--targetProject` | string | project where execution needs to be created. If not specified configured project would be used. |
| `--task` | string |  |
| `--version` | string | specify version of execution workflow/task. |
| `--workflow` | string |  |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-create/uctl-create-policy ===

# uctl create policy

Create a policy which binds a role to one or more resources

## Synopsis

Creates a policy which binds roles to specific resources (your whole
organization, a domain, a project + domain)

Use a policy.yaml file to define your policy. You can generate a
template file using

::

:   bin/uctl create policy --genFile --policyFile policy.yaml

When defining a policy, you can re-use existing roles within your
organization or define custom roles using

::

:   bin/uctl create role --help

The existing roles in your organization include: - admin - contributor -
viewer

Please refer to the existing documentation for what each predefined role
has permissions to do.

To create a policy for every project and domain within your
organization, create a policy.yaml like so:

    name: MyOrgWideExamplePolicy
    bindings:
      - role: MyExampleRole

To create a policy for a specific domain within your organization,
create a policy.yaml like so:

    name: MyOrgWideExamplePolicy
    bindings:
      - role: MyExampleRole
        resource:
          domain: development

To create a policy for a specific project within your organization,
create a policy.yaml like so:

    name: MyExamplePolicy
    bindings:
      - role: MyExampleRole
        resource:
          domain: development
          project: flytesnacks
      - role: MyExampleRole
        resource:
          domain: staging
          project: flytesnacks
      - role: MyExampleRole
        resource:
          domain: production
          project: flytesnacks

A policy can mix and match roles and resources. For example, to grant
admin privileges to the flytesnacks development domain and custom role
privileges in flytesnacks production, define a policy.yaml like so:

    name: MyExamplePolicy
    bindings:
      - role: admin
        resource:
          domain: development
          project: flytesnacks
      - role: MyExampleRole
        resource:
          domain: production
          project: flytesnacks

```shell
$ uctl create policy [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--genFile` | | Optional,  if you want to create a policy using a file as a specification,  this will generate a template example |
| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for policy |
| `--name` | string | Name to assign to the policy. Must be unique |
| `--policyFile` | string | Optional,  use a file for defining more complicated policies (default "policy.yaml") |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-create/uctl-create-project ===

# uctl create project

Creates project resources.

## Synopsis

Create a project given its name and id.

```shell
$ uctl create project --name flytesnacks --id flytesnacks --description "flytesnacks description" --labels app=flyte
```

> [!NOTE]
> The terms project/projects are interchangeable in these commands.

Create a project by definition file.

```shell
$ uctl create project --file project.yaml
```

``` yaml
id: "project-unique-id"
name: "Name"
labels:
   values:
     app: flyte
description: "Some description for the project."
```

> [!NOTE]
> The project name shouldn't contain any whitespace characters.

```shell
$ uctl create project [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--activate` | | Activates the project specified as argument. Only used in update |
| Option | Type | Description |
|--------|------|-------------|
| `--activateProject` | | (Deprecated) Activates the project specified as argument. Only used in update |
| Option | Type | Description |
|--------|------|-------------|
| `--archive` | | Archives the project specified as argument. Only used in update |
| Option | Type | Description |
|--------|------|-------------|
| `--archiveProject` | | (Deprecated) Archives the project specified as argument. Only used in update |
| Option | Type | Description |
|--------|------|-------------|
| `--description` | string | description for the project specified as argument. |
| `--dryRun` | | execute command without making any modifications. |
| `--file` | string | file for the project definition. |
| `--force` | | Skips asking for an acknowledgement during an update operation. Only used in update |
| `-h`, `--help` | help for project |
| `--id` | string | id for the project specified as argument. |
| `--labels` | stringToString | labels for the project specified as argument. (default []) |
| `--name` | string | name for the project specified as argument. |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-create/uctl-create-role ===

# uctl create role

Create a role, which defines a set of allowable actions on a resource

## Synopsis

Create a role which defines a set of permitted actions.

For example, create a new role to view and register flyte inventory:

    bin/uctl create role --name "Registration Role" --actions view_flyte_inventory,view_flyte_executions,register_flyte_inventory

You can also define roles using a template file

Define a role.yaml like so:

    name: Registration Role
    actions:
    - view_flyte_inventory
    - view_flyte_executions
    - register_flyte_inventory

And pass this into create role

```shell
$ uctl/bin create role --roleFile role.yaml
```

You can optionally generate a skeleton file to fill out with your custom
permissions like so:

```shell
$ uctl/bin create role --genFile --roleFile role.yaml
```

And pass this into create role

```shell
$ uctl/bin create role --roleFile role.yaml
```

All available actions are:

:   -   administer_account
    -   administer_project
    -   create_flyte_executions
    -   edit_cluster_related_attributes
    -   edit_execution_related_attributes
    -   edit_unused_attributes
    -   manage_cluster
    -   manage_permissions
    -   register_flyte_inventory
    -   view_flyte_executions
    -   view_flyte_inventory

Please refer to the official documentation for what these do.

You can define policies which apply already-created roles to specific
resources using

```shell
$ uctl/bin create policy --help
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--actions` | strings | Actions permitted by holders of the role |
| `--genFile` | | Optional,  if you want to create a role using a file as a specification,  this will generate a template example |
| `-h`, `--help` | help for role |
| `--name` | string | Name to assign to the role. Must be unique |
| `--roleFile` | string | Optional,  use a file for defining more complicated roles (default "role.yaml") |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-delete ===

# uctl delete

Used for terminating/deleting various union/flyte resources including
tasks/workflows/launchplans/executions/project

## Synopsis

Delete a resource; if an execution:

```shell
$ uctl delete execution kxd1i72850  -d development  -p flytesnacks
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for delete |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |

## Subpages
- **Uctl CLI > uctl delete > uctl delete app**
- **Uctl CLI > uctl delete > uctl delete cluster**
- **Uctl CLI > uctl delete > uctl delete cluster-pool-attributes**
- **Uctl CLI > uctl delete > uctl delete cluster-resource-attribute**
- **Uctl CLI > uctl delete > uctl delete clusterconfig**
- **Uctl CLI > uctl delete > uctl delete clusterpool**
- **Uctl CLI > uctl delete > uctl delete clusterpoolassignment**
- **Uctl CLI > uctl delete > uctl delete execution**
- **Uctl CLI > uctl delete > uctl delete execution-cluster-label**
- **Uctl CLI > uctl delete > uctl delete execution-queue-attribute**
- **Uctl CLI > uctl delete > uctl delete identityassignments**
- **Uctl CLI > uctl delete > uctl delete plugin-override**
- **Uctl CLI > uctl delete > uctl delete policy**
- **Uctl CLI > uctl delete > uctl delete role**
- **Uctl CLI > uctl delete > uctl delete task-resource-attribute**
- **Uctl CLI > uctl delete > uctl delete workflow-execution-config**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-delete/uctl-delete-app ===

# uctl delete app

Delete application

## Synopsis

Delete application

```shell
$ uctl delete app [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--dryRun` | | execute command without making any modifications. |
| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for app |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-delete/uctl-delete-cluster ===

# uctl delete cluster

Delete clusters

## Synopsis

Delete clusters

```shell
$ uctl delete cluster [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--dryRun` | | execute command without making any modifications. |
| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for cluster |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-delete/uctl-delete-cluster-pool-attributes ===

# uctl delete cluster-pool-attributes

Deletes matchable resources of cluster pool attribute

## Synopsis

Delete project and domain cluster pool attributes:

```shell
$ uctl delete cluster-pool-attributes -p flytesnacks -d staging
```

Delete workflow cluster pool attributes:

```shell
$ uctl delete cluster-pool-attributes -p flytesnacks -d staging --workflow my_wf
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for cluster-pool-attributes |
| `--workflow` | string | optional,  workflow name for the matchable attributes to delete |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-delete/uctl-delete-cluster-resource-attribute ===

# uctl delete cluster-resource-attribute

Deletes matchable resources of cluster attributes.

## Synopsis

Delete cluster resource attributes for the given project and domain, in
combination with the workflow name.

For project flytesnacks and development domain, run:

```shell
$ uctl delete cluster-resource-attribute -p flytesnacks -d development
```

To delete cluster resource attribute using the config file that was used
to create it, run:

```shell
$ uctl delete cluster-resource-attribute --attrFile cra.yaml
```

For example, here's the config file cra.yaml:

``` yaml
domain: development
project: flytesnacks
attributes:
  foo: "bar"
  buzz: "lightyear"
```

Attributes are optional in the file, which are unread during the
`delete` command but can be retained since the same file can be used
for `get`, `update` and `delete` commands.

To delete cluster resource attribute for the workflow
`core.control_flow.merge_sort.merge_sort`, run:

```shell
$ uctl delete cluster-resource-attribute -p flytesnacks -d development core.control_flow.merge_sort.merge_sort
```

Usage:

```shell
$ uctl delete cluster-resource-attribute [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--attrFile` | string | attribute file name to be used for delete attribute for the resource type. |
| `--dryRun` | | execute command without making any modifications. |
| `-h`, `--help` | help for cluster-resource-attribute |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-delete/uctl-delete-clusterconfig ===

# uctl delete clusterconfig

Delete cluster config

## Synopsis

Delete cluster config

```shell
$ uctl delete clusterconfig [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--dryRun` | | execute command without making any modifications. |
| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for clusterconfig |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-delete/uctl-delete-clusterpool ===

# uctl delete clusterpool

Delete cluster pool

## Synopsis

Delete cluster pool

```shell
$ uctl delete clusterpool [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--dryRun` | | execute command without making any modifications. |
| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for clusterpool |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-delete/uctl-delete-clusterpoolassignment ===

# uctl delete clusterpoolassignment

Delete cluster pool assignment

## Synopsis

Delete cluster pool assignment

```shell
$ uctl delete clusterpoolassignment [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--clusterName` | string | Assign cluster with this name |
| `-h`, `--help` | help for clusterpoolassignment |
| `--poolName` | string | Assign cluster to this pool |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-delete/uctl-delete-execution ===

# uctl delete execution

Terminates/deletes execution resources.

## Synopsis

Task executions can be aborted only if they are in non-terminal state.
If they are FAILED, ABORTED, or SUCCEEDED, calling terminate on them has
no effect. Terminate a single execution with its name:

```shell
$ uctl delete execution c6a51x2l9e  -d development  -p flytesnacks
```

> [!NOTE]
> The terms execution/executions are interchangeable in these commands.

Get an execution to check its state:

```shell
$ uctl get execution  -d development  -p flytesnacks
```

| NAME       | WORKFLOW NAME                  | TYPE     | PHASE   | STARTED                        | ELAPSED TIME  |
|------------|--------------------------------|----------|---------|--------------------------------|---------------|
| c6a51x2l9e | recipes.core.basic.lp.go_greet | WORKFLOW | ABORTED | 2021-02-17T08:13:04.680476300Z | 15.540361300s |

Terminate multiple executions with their names:

```shell
$ uctl delete execution eeam9s8sny p4wv4hwgc4  -d development  -p flytesnacks
```

Get an execution to find the state of previously terminated executions:

```shell
$ uctl get execution  -d development  -p flytesnacks
```

| NAME       | WORKFLOW NAME                  | TYPE     | PHASE   | STARTED                        | ELAPSED TIME  |
|------------|--------------------------------|----------|---------|--------------------------------|---------------|
| c6a51x2l9e | recipes.core.basic.lp.go_greet | WORKFLOW | ABORTED | 2021-02-17T08:13:04.680476300Z | 15.540361300s |
| eeam9s8sny | recipes.core.basic.lp.go_greet | WORKFLOW | ABORTED | 2021-02-17T08:14:04.803084100Z | 42.306385500s |
| p4wv4hwgc4 | recipes.core.basic.lp.go_greet | WORKFLOW | ABORTED | 2021-02-17T08:14:27.476307400Z | 19.727504400s |

Usage:

```shell
$ uctl delete execution [flags]
```

## Options

| `--dryRun` | | execute command without making any modifications. |
| `-h`, `--help` | help for execution |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-delete/uctl-delete-execution-cluster-label ===

# uctl delete execution-cluster-label

Deletes matchable resources of execution cluster label.

## Synopsis

Delete execution cluster label for a given project and domain, in
combination with the workflow name.

For project flytesnacks and development domain, run:

```shell
$ uctl delete execution-cluster-label -p flytesnacks -d development
```

To delete execution cluster label using the config file that was used to
create it, run:

```shell
$ uctl delete execution-cluster-label --attrFile ecl.yaml
```

For example, here's the config file ecl.yaml:

``` yaml
domain: development
project: flytesnacks
value: foo
```

Value is optional in the file as it is unread during the delete command,
but it can be retained since the same file can be used for `get`,
`update` and `delete` commands.

To delete the execution cluster label of the workflow
`core.control_flow.merge_sort.merge_sort`, run the following:

```shell
$ uctl delete execution-cluster-label -p flytesnacks -d development core.control_flow.merge_sort.merge_sort
```

Usage:

```shell
$ uctl delete execution-cluster-label [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--attrFile` | string | attribute file name to be used for delete attribute for the resource type. |
| `--dryRun` | | execute command without making any modifications. |
| `-h`, `--help` | help for execution-cluster-label |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-delete/uctl-delete-execution-queue-attribute ===

# uctl delete execution-queue-attribute

Deletes matchable resources of execution queue attributes.

## Synopsis

Delete execution queue attributes for the given project and domain, in
combination with the workflow name.

For project flytesnacks and development domain, run:

```shell
$ uctl delete execution-queue-attribute -p flytesnacks -d development
```

Delete execution queue attribute using the config file which was used to
create it.

```shell
$ uctl delete execution-queue-attribute --attrFile era.yaml
```

For example, here's the config file era.yaml:

``` yaml
domain: development
project: flytesnacks
tags:
  - foo
  - bar
  - buzz
  - lightyear
```

Value is optional in the file as it is unread during the delete command
but it can be retained since the same file can be used for get, update
and delete commands.

To delete the execution queue attribute for the workflow
`core.control_flow.merge_sort.merge_sort`, run the following command:

```shell
$ uctl delete execution-queue-attribute -p flytesnacks -d development core.control_flow.merge_sort.merge_sort
```

Usage:

```shell
$ uctl delete execution-queue-attribute [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--attrFile` | string | attribute file name to be used for delete attribute for the resource type. |
| `--dryRun` | | execute command without making any modifications. |
| `-h`, `--help` | help for execution-queue-attribute |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-delete/uctl-delete-identityassignments ===

# uctl delete identityassignments

Removes a role assignment from a user or application

## Synopsis

Assigns a policy to a specific user or application.

To update a user, specify them by their email and run:

```shell
$ uctl delete identityassignments --user.email bob@contoso.com --policy contributor
```

This removes their contributor policy assignment.

To update an application, specify the application by its unique client
id and run:

```shell
$ uctl delete identityassignments --application.id "contoso-operator" --policy admin
```

This removes the application's admin policy assignment.

Hint: you can fetch an application's ID by listing apps:

```shell
$ uctl get apps
```

You can list existing policy assignments with:

```shell
$ uctl get identityassignments --user bob@contoso.com
$ uctl get identityassignments --application "contoso-operator"
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--application` | string | Application id to fetch identity assignments for |
| `-h`, `--help` | help for identityassignments |
| `--policy` | string | Policy name with which to update the identity assignment |
| `--user` | string | Human user email to fetch identity assignments for |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-delete/uctl-delete-plugin-override ===

# uctl delete plugin-override

Deletes matchable resources of plugin overrides.

## Synopsis

Delete plugin override for the given project and domain, in combination
with the workflow name.

For project flytesnacks and development domain, run:

```shell
$ uctl delete plugin-override -p flytesnacks -d development
```

To delete plugin override using the config file which was used to create
it, run:

```shell
$ uctl delete plugin-override --attrFile po.yaml
```

For example, here's the config file po.yaml:

``` yaml
domain: development
project: flytesnacks
overrides:
   - task_type: python_task # Task type for which to apply plugin implementation overrides
     plugin_id:             # Plugin id(s) to be used in place of the default for the task type.
       - plugin_override1
       - plugin_override2
     missing_plugin_behavior: 1 # Behavior when no specified plugin_id has an associated handler. 0: FAIL , 1: DEFAULT
```

Overrides are optional in the file as they are unread during the delete
command but can be retained since the same file can be used for get,
update and delete commands.

To delete plugin override for the workflow
`core.control_flow.merge_sort.merge_sort`, run the following command:

```shell
$ uctl delete plugin-override -p flytesnacks -d development core.control_flow.merge_sort.merge_sort
```

Usage:

```shell
$ uctl delete plugin-override [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--attrFile` | string | attribute file name to be used for delete attribute for the resource type. |
| `--dryRun` | | execute command without making any modifications. |
| `-h`, `--help` | help for plugin-override |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-delete/uctl-delete-policy ===

# uctl delete policy

Delete a policy

## Synopsis

Delete a policy

```shell
$ uctl delete policy [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for policy |
| `--name` | string | Name of the policy to remove |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-delete/uctl-delete-role ===

# uctl delete role

Delete a role

## Synopsis

Delete a role

```shell
$ uctl delete role [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for role |
| `--name` | string | Name of the role to remove |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-delete/uctl-delete-task-resource-attribute ===

# uctl delete task-resource-attribute

Deletes matchable resources of task attributes.

## Synopsis

Delete task resource attributes for the given project and domain, in
combination with the workflow name.

For project flytesnacks and development domain, run:

```shell
$ uctl delete task-resource-attribute -p flytesnacks -d development
```

To delete task resource attribute using the config file which was used
to create it, run:

```shell
$ uctl delete task-resource-attribute --attrFile tra.yaml
```

For example, here's the config file tra.yaml:

``` yaml
domain: development
project: flytesnacks
defaults:
  cpu: "1"
  memory: "150Mi"
limits:
  cpu: "2"
  memory: "450Mi"
```

The defaults/limits are optional in the file as they are unread during
the delete command, but can be retained since the same file can be used
for `get`, `update` and `delete` commands.

To delete task resource attribute for the workflow
`core.control_flow.merge_sort.merge_sort`, run the following command:

```shell
$ uctl delete task-resource-attribute -p flytesnacks -d development core.control_flow.merge_sort.merge_sort
```

Usage:

```shell
$ uctl delete task-resource-attribute [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--attrFile` | string | attribute file name to be used for delete attribute for the resource type. |
| `--dryRun` | | execute command without making any modifications. |
| `-h`, `--help` | help for task-resource-attribute |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-delete/uctl-delete-workflow-execution-config ===

# uctl delete workflow-execution-config

Deletes matchable resources of workflow execution config.

## Synopsis

Delete workflow execution config for the given project and domain
combination or additionally the workflow name.

For project flytesnacks and development domain, run:

```shell
$ uctl delete workflow-execution-config -p flytesnacks -d development
```

To delete workflow execution config using the config file which was used
to create it, run:

```shell
$ uctl delete workflow-execution-config --attrFile wec.yaml
```

For example, here's the config file wec.yaml:

``` yaml
domain: development
project: flytesnacks
max_parallelism: 5
security_context:
  run_as:
    k8s_service_account: demo
```

Max_parallelism is optional in the file as it is unread during the
delete command but can be retained since the same file can be used for
get, update and delete commands.

To delete workflow execution config for the workflow
`core.control_flow.merge_sort.merge_sort`, run:

```shell
$ uctl delete workflow-execution-config -p flytesnacks -d development core.control_flow.merge_sort.merge_sort
```

Usage:

```shell
$ uctl delete workflow-execution-config [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--attrFile` | string | attribute file name to be used for delete attribute for the resource type. |
| `--dryRun` | | execute command without making any modifications. |
| `-h`, `--help` | help for workflow-execution-config |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-demo ===

# uctl demo

Helps with demo interactions like start, teardown, status, and exec.

## Synopsis

Uctl Flyte Demo is a fully standalone minimal environment for running
Flyte. It provides a simplified way of running Flyte demo as a single
Docker container locally.

To create a demo cluster:

```shell
$ uctl demo start
```

To remove a demo cluster:

```shell
$ uctl demo teardown
```

To check the status of the demo container:

```shell
$ uctl demo status
```
To execute commands inside the demo container:

```shell
$ uctl demo exec -- pwd
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for demo |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |

## Subpages
- **Uctl CLI > uctl demo > uctl demo exec**
- **Uctl CLI > uctl demo > uctl demo reload**
- **Uctl CLI > uctl demo > uctl demo start**
- **Uctl CLI > uctl demo > uctl demo status**
- **Uctl CLI > uctl demo > uctl demo teardown**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-demo/uctl-demo-exec ===

# uctl demo exec

Executes non-interactive command inside the demo container

## Synopsis

Run non-interactive commands inside the demo container and immediately
return the output. By default, "uctl exec" is present in the /root
directory inside the demo container.

```shell
$ uctl demo exec -- ls -al
```

Usage:

```shell
$ uctl demo exec [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for exec |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-demo/uctl-demo-reload ===

# uctl demo reload

Power cycle the Flyte executable pod, effectively picking up an updated
config.

## Synopsis

If you've changed the `~/.flyte/state/flyte.yaml` file, run this command
to restart the Flyte binary pod, effectively picking up the new
settings:

Usage:

```shell
$ uctl demo reload
```

```shell
$ uctl demo reload [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--dev` | | Optional. Only start minio and postgres in the sandbox. |
| Option | Type | Description |
|--------|------|-------------|
| `--disable-agent` | | Optional. Disable the agent service. |
| Option | Type | Description |
|--------|------|-------------|
| `--dryRun` | | Optional. Only print the docker commands to bring up flyte sandbox/demo container.This will still call github api's to get the latest flyte release to use' |
| Option | Type | Description |
|--------|------|-------------|
| `--env` | strings | Optional. Provide Env variable in key=value format which can be passed to sandbox container. |
| `--force` | | Optional. Forcefully delete existing sandbox cluster if it exists. |
| `-h`, `--help` | help for reload |
| `--image` | string | Optional. Provide a fully qualified path to a Flyte compliant docker image. |
| `--imagePullOptions.platform` | string | Forces a specific platform's image to be pulled.' |
| `--imagePullOptions.registryAuth` | string | The base64 encoded credentials for the registry. |
| `--imagePullPolicy` | ImagePullPolicy | Optional. Defines the image pull behavior [Always/IfNotPresent/Never] (default Always) |
| `--pre` | | Optional. Pre release Version of flyte will be used for sandbox. |
| `--source` | string | deprecated,  path of your source code,  please build images with local daemon |
| `--version` | string | Version of flyte. Only supports flyte releases greater than v0.10.0 |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-demo/uctl-demo-start ===

# uctl demo start

Starts the Flyte demo cluster.

## Synopsis

Flyte demo is a fully standalone minimal environment for running Flyte.
It provides a simplified way of running Flyte demo as a single Docker
container locally.

Starts the demo cluster without any source code:

```shell
$ uctl demo start
```

Runs a dev cluster, which only has minio and postgres pod:

```shell
$ uctl demo start --dev
```

Mounts your source code repository inside the demo cluster:

```shell
$ uctl demo start --source=$HOME/flyteorg/flytesnacks
```

Specify a Flyte demo compliant image with the registry. This is useful
in case you want to use an image from your registry:

```shell
$ uctl demo start --image docker.io/my-override:latest
```

Note: If image flag is passed then Flytectl will ignore version and pre
flags.

Specify a Flyte demo image pull policy. Possible pull policy values are
Always, IfNotPresent, or Never:

```shell
$ uctl demo start --image docker.io/my-override:latest --imagePullPolicy Always
```

Runs a specific version of Flyte. Flytectl demo only supports Flyte
version available in the Github release,
{https://github.com/flyteorg/flyte/tags}:

```shell
$ uctl demo start --version=v0.14.0
```

> [!NOTE]
> Flytectl demo is only supported for Flyte versions >= v1.0.0

Runs the latest pre release of Flyte:

```shell
$ uctl demo start --pre
```

Start demo cluster passing environment variables. This can be used to
pass docker specific env variables or flyte specific env variables. eg:
for passing timeout value in secs for the demo container use the
following:

```shell
$ uctl demo start --env FLYTE_TIMEOUT=700
```

The DURATION can be a positive integer or a floating-point number,
followed by an optional unit suffix:: s - seconds (default) m - minutes
h - hours d - days When no unit is used, it defaults to seconds. If the
duration is set to zero, the associated timeout is disabled.

For passing multiple environment variables:

```shell
$ uctl demo start --env USER=foo --env PASSWORD=bar
```

For just printing the docker commands for bringing up the demo container:

```shell
$ uctl demo start --dryRun
```

Usage:

```shell
$ uctl demo start [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--dev` | | Optional. Only start minio and postgres in the sandbox. |
| Option | Type | Description |
|--------|------|-------------|
| `--disable-agent` | | Optional. Disable the agent service. |
| Option | Type | Description |
|--------|------|-------------|
| `--dryRun` | | Optional. Only print the docker commands to bring up flyte sandbox/demo container.This will still call github api's to get the latest flyte release to use' |
| Option | Type | Description |
|--------|------|-------------|
| `--env` | strings | Optional. Provide Env variable in key=value format which can be passed to sandbox container. |
| `--force` | | Optional. Forcefully delete existing sandbox cluster if it exists. |
| `-h`, `--help` | help for start |
| `--image` | string | Optional. Provide a fully qualified path to a Flyte compliant docker image. |
| `--imagePullOptions.platform` | string | Forces a specific platform's image to be pulled.' |
| `--imagePullOptions.registryAuth` | string | The base64 encoded credentials for the registry. |
| `--imagePullPolicy` | ImagePullPolicy | Optional. Defines the image pull behavior [Always/IfNotPresent/Never] (default Always) |
| `--pre` | | Optional. Pre release Version of flyte will be used for sandbox. |
| `--source` | string | deprecated,  path of your source code,  please build images with local daemon |
| `--version` | string | Version of flyte. Only supports flyte releases greater than v0.10.0 |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-demo/uctl-demo-status ===

# uctl demo status

Gets the status of the demo environment.

## Synopsis

Retrieves the status of the demo environment. Currently, Flyte demo runs
as a local Docker container.

Usage:

```shell
$ uctl demo status
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for status |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-demo/uctl-demo-teardown ===

# uctl demo teardown

Cleans up the demo environment

## Synopsis

Removes the demo cluster and all the Flyte config created by `demo
start`:

```shell
$ uctl demo teardown
```

Usage:

```shell
$ uctl demo teardown [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for teardown |
| `-v`, `--volume` | Optional. | Clean up Docker volume. This will result in a permanent loss of all data within the database and object store. Use with caution! |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get ===

# uctl get

Used for fetching various union/flyte resources including
tasks/workflows/launchplans/executions/project.

## Synopsis

To fetch a project, use the following command:

```shell
$ uctl get project
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for get |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |

## Subpages
- **Uctl CLI > uctl get > uctl get app**
- **Uctl CLI > uctl get > uctl get cluster**
- **Uctl CLI > uctl get > uctl get cluster-pool-attributes**
- **Uctl CLI > uctl get > uctl get cluster-resource-attribute**
- **Uctl CLI > uctl get > uctl get clusterconfig**
- **Uctl CLI > uctl get > uctl get clusterconfigs**
- **Uctl CLI > uctl get > uctl get clusterpool**
- **Uctl CLI > uctl get > uctl get clusterpoolconfig**
- **Uctl CLI > uctl get > uctl get clusterswithconfig**
- **Uctl CLI > uctl get > uctl get echo**
- **Uctl CLI > uctl get > uctl get execution**
- **Uctl CLI > uctl get > uctl get execution-cluster-label**
- **Uctl CLI > uctl get > uctl get execution-queue-attribute**
- **Uctl CLI > uctl get > uctl get executionoperation**
- **Uctl CLI > uctl get > uctl get identityassignment**
- **Uctl CLI > uctl get > uctl get launchplan**
- **Uctl CLI > uctl get > uctl get plugin-override**
- **Uctl CLI > uctl get > uctl get policy**
- **Uctl CLI > uctl get > uctl get project**
- **Uctl CLI > uctl get > uctl get role**
- **Uctl CLI > uctl get > uctl get task**
- **Uctl CLI > uctl get > uctl get task-resource-attribute**
- **Uctl CLI > uctl get > uctl get workflow**
- **Uctl CLI > uctl get > uctl get workflow-execution-config**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-app ===

# uctl get app

Retrieves apps registered in the tenant

## Synopsis

Retrieves apps registered in the tenant

```shell
$ uctl get app [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--appSpecFile` | string | generates an app spec file with conformance to the api format with current values.This can only be used while fetching single app |
| `--filter.asc` | | Specifies the sorting order. By default sorts result in descending order |
| `--filter.fieldSelector` | string | Allows for filtering resources based on a specific value for a field name using operations =, !=, >, {, }=, <=, in, contains.Multiple selectors can be added separated by commas |
| `--filter.limit` | int32 | Specifies the number of results to return (default 100) |
| `--filter.sortBy` | string | Specifies which field to sort results  (default "created_at") |
| `--filter.token` | string | Specifies the server provided token to use for fetching next page in case of multi page result |
| `-h`, `--help` | help for app |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-cluster ===

# uctl get cluster

Retrieves clusters

## Synopsis

Retrieves clusters

```shell
$ uctl get cluster [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--dryRun` | | execute command without making any modifications. |
| Option | Type | Description |
|--------|------|-------------|
| `--filter.asc` | | Specifies the sorting order. By default sorts result in descending order |
| Option | Type | Description |
|--------|------|-------------|
| `--filter.fieldSelector` | string | Allows for filtering resources based on a specific value for a field name using operations =, !=, >, {, }=, <=, in, contains.Multiple selectors can be added separated by commas |
| `--filter.limit` | int32 | Specifies the number of results to return (default 100) |
| `--filter.sortBy` | string | Specifies which field to sort results  (default "created_at") |
| `--filter.token` | string | Specifies the server provided token to use for fetching next page in case of multi page result |
| `-h`, `--help` | help for cluster |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-cluster-pool-attributes ===

# uctl get cluster-pool-attributes

Retrieves project and domain specific attributes

## Synopsis

To fetch cluster pool attributes for all domains:

```shell
$ uctl get cluster-pool-attributes
```

To fetch domain cluster pool attributes:

```shell
$ uctl get cluster-pool-attributes -d staging
```

To fetch cluster pool project and domain attributes:

```shell
$ uctl get cluster-pool-attributes -p flytesnacks -d staging
```

To fetch cluster pool workflow attributes:

```shell
$ uctl get cluster-pool-attributes -p flytesnacks -d staging --workflow my_wf
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for cluster-pool-attributes |
| `--workflow` | string | optional,  workflow name for the matchable attributes to fetch |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-cluster-resource-attribute ===

# uctl get cluster-resource-attribute

Gets matchable resources of cluster resource attributes.

## Synopsis

Retrieve cluster resource attributes for the given project and domain.
For project flytesnacks and development domain:

```shell
$ uctl get cluster-resource-attribute -p flytesnacks -d development
```

Example: output from the command:

``` json
{"project":"flytesnacks","domain":"development","attributes":{"buzz":"lightyear","foo":"bar"}}
```

Retrieve cluster resource attributes for the given project, domain, and
workflow. For project flytesnacks, development domain, and workflow
`core.control_flow.merge_sort.merge_sort`:

```shell
$ uctl get cluster-resource-attribute -p flytesnacks -d development core.control_flow.merge_sort.merge_sort
```

Example: output from the command:

``` json
{"project":"flytesnacks","domain":"development","workflow":"core.control_flow.merge_sort.merge_sort","attributes":{"buzz":"lightyear","foo":"bar"}}
```

Write the cluster resource attributes to a file. If there are no cluster
resource attributes, the command throws an error. The config file is
written to cra.yaml file. Example: content of cra.yaml:

```shell
$ uctl get task-resource-attribute --attrFile cra.yaml
```

``` yaml
domain: development
project: flytesnacks
attributes:
  foo: "bar"
  buzz: "lightyear"
```

Usage:

```shell
$ uctl get cluster-resource-attribute [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--attrFile` | string | attribute file name to be used for generating attribute for the resource type. |
| `-h`, `--help` | help for cluster-resource-attribute |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-clusterconfig ===

# uctl get clusterconfig

Retrieves cluster config

## Synopsis

To fetch default cluster config template:

```shell
$ uctl get clusterconfig --configID default
```

To fetch cluster config template:

```shell
$ uctl get clusterconfig --clusterName mycluster123
```

To fetch cluster config template and save to file:

```shell
$ uctl get clusterconfig --clusterName mycluster123 --outputFile spec.yaml
```

To fetch compiled cluster config:

```shell
$ uctl get clusterconfig --clusterName mycluster123 --compiled
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--clusterName` | string | Fetch config of cluster with given name |
| `--compiled` | | fetch compiled config for given cluster |
| `--configID` | string | Fetch cluster config with given id |
| `-h`, `--help` | help for clusterconfig |
| `--outputFile` | string | optional output file |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-clusterconfigs ===

# uctl get clusterconfigs

Retrieves list of cluster configs

## Synopsis

To fetch list of cluster configs of organization configured in `.uctl`
config:

```shell
$ uctl get clusterconfigs
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for clusterconfigs |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-clusterpool ===

# uctl get clusterpool

Retrieves cluster pools

## Synopsis

To fetch all available cluster pools:

```shell
$ uctl get clusterpools
```

To fetch one cluster pool:

```shell
$ uctl get clusterpool {pool_name}
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--clusterPoolSpecFile` | string | generates an clusterPool spec file with conformance to the api format with current values.This can only be used while fetching single cluster pool |
| `--filter.asc` | | Specifies the sorting order. By default sorts result in descending order |
| `--filter.fieldSelector` | string | Allows for filtering resources based on a specific value for a field name using operations =, !=, >, {, }=, <=, in, contains.Multiple selectors can be added separated by commas |
| `--filter.limit` | int32 | Specifies the number of results to return (default 100) |
| `--filter.sortBy` | string | Specifies which field to sort results  (default "created_at") |
| `--filter.token` | string | Specifies the server provided token to use for fetching next page in case of multi page result |
| `-h`, `--help` | help for clusterpool |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-clusterpoolconfig ===

# uctl get clusterpoolconfig

Retrieves cluster pools config

## Synopsis

Retrieves cluster pools config

```shell
$ uctl get clusterpoolconfig [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--clusterPoolSpecFile` | string | generates an clusterPool spec file with conformance to the api format with current values.This can only be used while fetching single cluster pool |
| `--filter.asc` | | Specifies the sorting order. By default sorts result in descending order |
| `--filter.fieldSelector` | string | Allows for filtering resources based on a specific value for a field name using operations =, !=, >, {, }=, <=, in, contains.Multiple selectors can be added separated by commas |
| `--filter.limit` | int32 | Specifies the number of results to return (default 100) |
| `--filter.sortBy` | string | Specifies which field to sort results  (default "created_at") |
| `--filter.token` | string | Specifies the server provided token to use for fetching next page in case of multi page result |
| `-h`, `--help` | help for clusterpoolconfig |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-clusterswithconfig ===

# uctl get clusterswithconfig

Retrieves list of cluster names with assigned config id

## Synopsis

To fetch list of clusters with assigned config:

```shell
$ uctl get clusterswithconfig {configID}
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for clusterswithconfig |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-echo ===

# uctl get echo

## Synopsis

```shell
$ uctl get echo [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for echo |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-execution ===

# uctl get execution

Gets execution resources.

## Synopsis

Retrieve all executions within the project and domain:

```shell
$ uctl get execution -p flytesnacks -d development
```

> [!NOTE]
> The terms execution/executions are interchangeable in these commands.

Retrieve executions by name within the project and domain:

```shell
$ uctl get execution -p flytesnacks -d development oeh94k9r2r
```

Retrieve all the executions with filters:

```shell
$ uctl get execution -p flytesnacks -d development --filter.fieldSelector="execution.phase in (FAILED;SUCCEEDED),execution.duration<200"
```

Retrieve executions as per the specified limit and sorting parameters:

```shell
$ uctl get execution -p flytesnacks -d development --filter.sortBy=created_at --filter.limit=1 --filter.asc
```

Retrieve executions present in other pages by specifying the limit and
page number.

```shell
$ uctl get -p flytesnacks -d development execution --filter.limit=10 --filter.page=2
```

Retrieve executions within the project and domain in YAML format.

```shell
$ uctl get execution -p flytesnacks -d development -o yaml
```

Retrieve executions within the project and domain in JSON format.

```shell
$ uctl get execution -p flytesnacks -d development -o json
```

Get more details of the execution using the --details flag, which shows
node and task executions. The default view is a tree view, and the TABLE
view format is not supported on this view.

```shell
$ uctl get execution -p flytesnacks -d development oeh94k9r2r --details
```

Fetch execution details in YAML format. In this view, only node details
are available. For task, pass the --nodeID flag:

```shell
$ uctl get execution -p flytesnacks -d development oeh94k9r2r --details -o yaml
```

Fetch task executions on a specific node using the --nodeID flag. Use
the nodeID attribute given by the node details view.

```shell
$ uctl get execution -p flytesnacks -d development oeh94k9r2r --nodeID n0
```

Task execution view is available in YAML/JSON format too. The following
example showcases YAML, where the output contains input and output data
of each node.

```shell
$ uctl get execution -p flytesnacks -d development oeh94k9r2r --nodeID n0 -o yaml
```

Usage:

```shell
$ uctl get execution [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--details` | | gets node execution details. Only applicable for single execution name i.e get execution name `--details` |
| Option | Type | Description |
|--------|------|-------------|
| `--filter.asc` | | Specifies the sorting order. By default uctl sort result in descending order |
| Option | Type | Description |
|--------|------|-------------|
| `--filter.fieldSelector` | string | Specifies the Field selector |
| `--filter.limit` | int32 | Specifies the limit (default 100) |
| `--filter.page` | int32 | Specifies the page number,  in case there are multiple pages of results (default 1) |
| `--filter.sortBy` | string | Specifies which field to sort results  (default "created_at") |
| `-h`, `--help` | help for execution |
| `--nodeID` | string | get task executions for given node name. |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-execution-cluster-label ===

# uctl get execution-cluster-label

Gets matchable resources of execution cluster label.

## Synopsis

Retrieve the execution cluster label for a given project and domain, in
combination with the workflow name.

For project flytesnacks and development domain, run:

```shell
$ uctl get execution-cluster-label -p flytesnacks -d development
```

The output would look like:

``` json
{"project":"flytesnacks","domain":"development","value":"foo"}
```

Retrieve the execution cluster label for the given project, domain, and
workflow. For project flytesnacks, development domain, and workflow
`core.control_flow.merge_sort.merge_sort`:

```shell
$ uctl get execution-cluster-label -p flytesnacks -d development core.control_flow.merge_sort.merge_sort
```

Example: output from the command:

``` json
{"project":"flytesnacks","domain":"development","workflow":"core.control_flow.merge_sort.merge_sort","value":"foo"}
```

Write the execution cluster label to a file. If there is no execution
cluster label, the command throws an error. The config file is written
to ecl.yaml file. Example: content of ecl.yaml:

```shell
$ uctl get execution-cluster-label --attrFile ecl.yaml
```

``` yaml
domain: development
project: flytesnacks
value: foo
```

Usage:

```shell
$ uctl get execution-cluster-label [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--attrFile` | string | attribute file name to be used for generating attribute for the resource type. |
| `-h`, `--help` | help for execution-cluster-label |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-execution-queue-attribute ===

# uctl get execution-queue-attribute

Gets matchable resources of execution queue attributes.

## Synopsis

Retrieve the execution queue attribute for the given project and domain.
For project flytesnacks and development domain:

```shell
$ uctl get execution-queue-attribute -p flytesnacks -d development
```

Example: output from the command:

``` json
{"project":"flytesnacks","domain":"development","tags":["foo", "bar"]}
```

Retrieve the execution queue attribute for the given project, domain,
and workflow. For project flytesnacks, development domain, and workflow
`core.control_flow.merge_sort.merge_sort`:

```shell
$ uctl get execution-queue-attribute -p flytesnacks -d development core.control_flow.merge_sort.merge_sort
```

Example: output from the command:

``` json
{"project":"flytesnacks","domain":"development","workflow":"core.control_flow.merge_sort.merge_sort","tags":["foo", "bar"]}
```

Write the execution queue attribute to a file. If there are no execution
queue attributes, the command throws an error. The config file is
written to era.yaml file. Example: content of era.yaml:

```shell
$ uctl get execution-queue-attribute --attrFile era.yaml
```

``` yaml
domain: development
project: flytesnacks
tags:
  - foo
  - bar
  - buzz
  - lightyear
```

Usage:

```shell
$ uctl get execution-queue-attribute [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--attrFile` | string | attribute file name to be used for generating attribute for the resource type. |
| `-h`, `--help` | help for execution-queue-attribute |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-executionoperation ===

# uctl get executionoperation

Peak at executions without acknowledging

## Synopsis

Retrieves executions from executions service without acknowledging the
executions. They will eventually show up again on the queue.

```shell
$ uctl get executionoperation [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for executionoperation |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-identityassignment ===

# uctl get identityassignment

## Synopsis

Fetch the policies assigned to a user, by email:

```shell
$ uctl get identityassignments --user bob@contoso.com
```

Fetch the specific policies assigned to an application, by id:

```shell
$ uctl get identityassignments --application "contoso-operator"
```

Hint: you can fetch an application's ID by listing apps:

```shell
$ uctl get apps
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--application` | string | Application id to fetch identity assignments for |
| `-h`, `--help` | help for identityassignment |
| `--user` | string | Human user email to fetch identity assignments for |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-launchplan ===

# uctl get launchplan

Gets the launch plan resources.

## Synopsis

Retrieve all launch plans within the project and domain:

```shell
$ uctl get launchplan -p flytesnacks -d development
```

> [!NOTE]
> The terms launchplan/launchplans are interchangeable in these commands.

Retrieve a launch plan by name within the project and domain:

```shell
$ uctl get launchplan -p flytesnacks -d development core.basic.lp.go_greet
```

Retrieve the latest version of the task by name within the project and
domain:

```shell
$ uctl get launchplan -p flytesnacks -d development  core.basic.lp.go_greet --latest
```

Retrieve a particular version of the launch plan by name within the
project and domain:

```shell
$ uctl get launchplan -p flytesnacks -d development  core.basic.lp.go_greet --version v2
```

Retrieve all launch plans for a given workflow name:

```shell
$ uctl get launchplan -p flytesnacks -d development --workflow core.flyte_basics.lp.go_greet
```

Retrieve all the launch plans with filters:

```shell
$ uctl get launchplan -p flytesnacks -d development --filter.fieldSelector="name=core.basic.lp.go_greet"
```

Retrieve all active launch plans:

```shell
$ uctl get launchplan -p flytesnacks -d development -o yaml  --filter.fieldSelector "state=1"
```

Retrieve all archived launch plans:

```shell
$ uctl get launchplan -p flytesnacks -d development -o yaml  --filter.fieldSelector "state=0"
```

Retrieve launch plans entity search across all versions with filters:

```shell
$ uctl get launchplan -p flytesnacks -d development k8s_spark.dataframe_passing.my_smart_schema --filter.fieldSelector="version=v1"
```

Retrieve all the launch plans with limit and sorting:

```shell
$ uctl get launchplan -p flytesnacks -d development --filter.sortBy=created_at --filter.limit=1 --filter.asc
```

Retrieve launch plans present in other pages by specifying the limit and
page number:

```shell
$ uctl get -p flytesnacks -d development launchplan --filter.limit=10 --filter.page=2
```

Retrieve all launch plans within the project and domain in YAML format:

```shell
$ uctl get launchplan -p flytesnacks -d development -o yaml
```

Retrieve all launch plans the within the project and domain in JSON
format:

```shell
$ uctl get launchplan -p flytesnacks -d development -o json
```

Retrieve a launch plan within the project and domain as per a version
and generates the execution spec file; the file can be used to launch
the execution using the `create execution` command:

```shell
$ uctl get launchplan -d development -p flytesnacks core.control_flow.merge_sort.merge_sort --execFile execution_spec.yaml
```

The generated file would look similar to this:

``` yaml
iamRoleARN: ""
inputs:
  numbers:
  - 0
  numbers_count: 0
  run_local_at_count: 10
kubeServiceAcct: ""
targetDomain: ""
targetProject: ""
version: v3
workflow: core.control_flow.merge_sort.merge_sort
```

Usage:

```shell
$ uctl get launchplan [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--execFile` | string | execution file name to be used for generating execution spec of a single launchplan. |
| `--filter.asc` | | Specifies the sorting order. By default uctl sort result in descending order |
| `--filter.fieldSelector` | string | Specifies the Field selector |
| `--filter.limit` | int32 | Specifies the limit (default 100) |
| `--filter.page` | int32 | Specifies the page number,  in case there are multiple pages of results (default 1) |
| `--filter.sortBy` | string | Specifies which field to sort results  (default "created_at") |
| `-h`, `--help` | help for launchplan |
| `--latest` | | flag to indicate to fetch the latest version,  version flag will be ignored in this case |
| `--version` | string | version of the launchplan to be fetched. |
| `--workflow` | string | name of the workflow for which the launchplans need to be fetched. |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-plugin-override ===

# uctl get plugin-override

Gets matchable resources of plugin override.

## Synopsis

Retrieve the plugin override for the given project and domain. For
project flytesnacks and development domain:

```shell
$ uctl get plugin-override -p flytesnacks -d development
```

Example: output from the command

``` json
{
   "project": "flytesnacks",
   "domain": "development",
   "overrides": [{
       "task_type": "python_task",
       "plugin_id": ["pluginoverride1", "pluginoverride2"],
       "missing_plugin_behavior": 0
   }]
}
```

Retrieve the plugin override for the given project, domain, and
workflow. For project flytesnacks, development domain and workflow
`core.control_flow.merge_sort.merge_sort`:

```shell
$ uctl get plugin-override -p flytesnacks -d development core.control_flow.merge_sort.merge_sort
```

Example: output from the command:

``` json
{
   "project": "flytesnacks",
   "domain": "development",
   "workflow": "core.control_flow.merge_sort.merge_sort"
   "overrides": [{
       "task_type": "python_task",
       "plugin_id": ["pluginoverride1", "pluginoverride2"],
       "missing_plugin_behavior": 0
   }]
}
```

Write plugin overrides to a file. If there are no plugin overrides, the
command throws an error. The config file is written to po.yaml file.
Example: content of po.yaml:

```shell
$ uctl get plugin-override --attrFile po.yaml
```

``` yaml
domain: development
project: flytesnacks
overrides:
   - task_type: python_task # Task type for which to apply plugin implementation overrides
     plugin_id:             # Plugin id(s) to be used in place of the default for the task type.
       - plugin_override1
       - plugin_override2
     missing_plugin_behavior: 1 # Behavior when no specified plugin_id has an associated handler. 0: FAIL , 1: DEFAULT
```

Usage:

```shell
$ uctl get plugin-override [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--attrFile` | string | attribute file name to be used for generating attribute for the resource type. |
| `-h`, `--help` | help for plugin-override |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-policy ===

# uctl get policy

Returns all policies or a single policy for your entire organization

## Synopsis

Fetch the entire set of policies defined in your organization:

```shell
$ uctl get policies
```

Fetch an individual policy:

```shell
$ uctl get policy --name MyPolicy
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for policy |
| `--name` | string | Optional,  specific name of the policy to fetch |
| `--outputFile` | string | writes API response to this file. |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-project ===

# uctl get project

Gets project resources

## Synopsis

Retrieve all the projects:

```shell
$ uctl get project
```

> [!NOTE]
> The terms project/projects are interchangeable in these commands.

Retrieve project by name:

```shell
$ uctl get project flytesnacks
```

Retrieve all the projects with filters:

```shell
$ uctl get project --filter.fieldSelector="project.name=flytesnacks"
```

Retrieve all the projects with limit and sorting:

```shell
$ uctl get project --filter.sortBy=created_at --filter.limit=1 --filter.asc
```

Retrieve projects present in other pages by specifying the limit and
page number:

```shell
$ uctl get project --filter.limit=10 --filter.page=2
```

Retrieve all the projects in yaml format:

```shell
$ uctl get project -o yaml
```

Retrieve all the projects in json format:

```shell
$ uctl get project -o json
```

Usage:

```shell
$ uctl get project [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--filter.asc` | | Specifies the sorting order. By default uctl sort result in descending order |
| Option | Type | Description |
|--------|------|-------------|
| `--filter.fieldSelector` | string | Specifies the Field selector |
| `--filter.limit` | int32 | Specifies the limit (default 100) |
| `--filter.page` | int32 | Specifies the page number,  in case there are multiple pages of results (default 1) |
| `--filter.sortBy` | string | Specifies which field to sort results  (default "created_at") |
| `-h`, `--help` | help for project |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-role ===

# uctl get role

Returns roles for your entire organization or assigned to a specific
identity (user or application)

## Synopsis

Fetch the entire set of roles defined in your organization:

```shell
$ uctl get roles
```

Fetch an individual role:

```shell
$ uctl get role MyExampleRole
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for role |
| `--name` | string | Optional,  specific name of the role to fetch |
| `--outputFile` | string | writes API response to this file. |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-task ===

# uctl get task

Gets task resources

## Synopsis

Retrieve all the tasks within project and domain:

```shell
$ uctl get task -p flytesnacks -d development
```

> [!NOTE]
> The terms task/tasks are interchangeable in these commands.

Retrieve task by name within project and domain:

```shell
$ uctl task -p flytesnacks -d development core.basic.lp.greet
```

Retrieve latest version of task by name within project and domain:

```shell
$ uctl get task -p flytesnacks -d development  core.basic.lp.greet --latest
```

Retrieve particular version of task by name within project and domain:

```shell
$ uctl get task -p flytesnacks -d development  core.basic.lp.greet --version v2
```

Retrieve all the tasks with filters:

```shell
$ uctl get task -p flytesnacks -d development --filter.fieldSelector="task.name=k8s_spark.pyspark_pi.print_every_time,task.version=v1"
```

Retrieve a specific task with filters:

```shell
$ uctl get task -p flytesnacks -d development k8s_spark.pyspark_pi.print_every_time --filter.fieldSelector="task.version=v1,created_at>=2021-05-24T21:43:12.325335Z"
```

Retrieve all the tasks with limit and sorting:

```shell
$ uctl get -p flytesnacks -d development task  --filter.sortBy=created_at --filter.limit=1 --filter.asc
```

Retrieve tasks present in other pages by specifying the limit and page
number:

```shell
$ uctl get -p flytesnacks -d development task --filter.limit=10 --filter.page=2
```

Retrieve all the tasks within project and domain in yaml format:

```shell
$ uctl get task -p flytesnacks -d development -o yaml
```

Retrieve all the tasks within project and domain in json format:

```shell
$ uctl get task -p flytesnacks -d development -o json
```

Retrieve tasks within project and domain for a version and generate the
execution spec file for it to be used for launching the execution using
create execution:

```shell
$ uctl get tasks -d development -p flytesnacks core.control_flow.merge_sort.merge --execFile execution_spec.yaml --version v2
```

The generated file would look similar to this:

``` yaml
iamRoleARN: ""
inputs:
  sorted_list1:
  - 0
  sorted_list2:
  - 0
kubeServiceAcct: ""
targetDomain: ""
targetProject: ""
task: core.control_flow.merge_sort.merge
version: v2
```

Check the create execution section on how to launch one using the
generated file.

Usage:

```shell
$ uctl get task [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--execFile` | string | execution file name to be used for generating execution spec of a single task. |
| `--filter.asc` | | Specifies the sorting order. By default uctl sort result in descending order |
| `--filter.fieldSelector` | string | Specifies the Field selector |
| `--filter.limit` | int32 | Specifies the limit (default 100) |
| `--filter.page` | int32 | Specifies the page number,  in case there are multiple pages of results (default 1) |
| `--filter.sortBy` | string | Specifies which field to sort results  (default "created_at") |
| `-h`, `--help` | help for task |
| `--latest` | | flag to indicate to fetch the latest version,  version flag will be ignored in this case |
| `--version` | string | version of the task to be fetched. |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-task-resource-attribute ===

# uctl get task-resource-attribute

Gets matchable resources of task attributes.

## Synopsis

Retrieve task resource attributes for the given project and domain. For
project flytesnacks and development domain:

```shell
$ uctl get task-resource-attribute -p flytesnacks -d development
```

Example: output from the command:

``` json
{"project":"flytesnacks","domain":"development","workflow":"","defaults":{"cpu":"1","memory":"150Mi"},"limits":{"cpu":"2","memory":"450Mi"}}
```

Retrieve task resource attributes for the given project, domain, and
workflow. For project flytesnacks, development domain, and workflow
`core.control_flow.merge_sort.merge_sort`:

```shell
$ uctl get task-resource-attribute -p flytesnacks -d development core.control_flow.merge_sort.merge_sort
```

Example: output from the command:

``` json
{"project":"flytesnacks","domain":"development","workflow":"core.control_flow.merge_sort.merge_sort","defaults":{"cpu":"1","memory":"150Mi"},"limits":{"cpu":"2","memory":"450Mi"}}
```

Write the task resource attributes to a file. If there are no task
resource attributes, a file would be populated with the basic data. The
config file is written to tra.yaml file. Example: content of tra.yaml:

```shell
$ uctl get -p flytesnacks -d development task-resource-attribute --attrFile tra.yaml
```

``` yaml
domain: development
project: flytesnacks
defaults:
  cpu: "1"
  memory: "150Mi"
limits:
  cpu: "2"
  memory: "450Mi"
```

Usage:

```shell
$ uctl get task-resource-attribute [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--attrFile` | string | attribute file name to be used for generating attribute for the resource type. |
| `-h`, `--help` | help for task-resource-attribute |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-workflow ===

# uctl get workflow

Gets workflow resources

## Synopsis

Retrieve all the workflows within project and domain (workflow/workflows
can be used interchangeably in these commands):

```shell
$ uctl get workflow -p flytesnacks -d development
```

Retrieve all versions of a workflow by name within project and domain:

```shell
$ uctl get workflow -p flytesnacks -d development  core.basic.lp.go_greet
```

Retrieve latest version of workflow by name within project and domain:

```shell
$ uctl get workflow -p flytesnacks -d development  core.basic.lp.go_greet --latest
```

Retrieve particular version of workflow by name within project and
domain:

```shell
$ uctl get workflow -p flytesnacks -d development  core.basic.lp.go_greet --version v2
```

Retrieve all the workflows with filters:

```shell
$ uctl get workflow -p flytesnacks -d development  --filter.fieldSelector="workflow.name=k8s_spark.dataframe_passing.my_smart_schema"
```

Retrieve specific workflow with filters:

```shell
$ uctl get workflow -p flytesnacks -d development k8s_spark.dataframe_passing.my_smart_schema --filter.fieldSelector="workflow.version=v1"
```

Retrieve all the workflows with limit and sorting:

```shell
$ uctl get -p flytesnacks -d development workflow  --filter.sortBy=created_at --filter.limit=1 --filter.asc
```

Retrieve workflows present in other pages by specifying the limit and
page number:

```shell
$ uctl get -p flytesnacks -d development workflow --filter.limit=10 --filter.page 2
```

Retrieve all the workflows within project and domain in yaml format:

```shell
$ uctl get workflow -p flytesnacks -d development -o yaml
```

Retrieve all the workflow within project and domain in json format:

```shell
$ uctl get workflow -p flytesnacks -d development -o json
```

Visualize the graph for a workflow within project and domain in dot
format:

```shell
$ uctl get workflow -p flytesnacks -d development  core.flyte_basics.basic_workflow.my_wf --latest -o dot
```

Visualize the graph for a workflow within project and domain in a dot
content render:

```shell
$ uctl get workflow -p flytesnacks -d development  core.flyte_basics.basic_workflow.my_wf --latest -o doturl
```

Usage:

```shell
$ uctl get workflow [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--filter.asc` | | Specifies the sorting order. By default uctl sort result in descending order |
| Option | Type | Description |
|--------|------|-------------|
| `--filter.fieldSelector` | string | Specifies the Field selector |
| `--filter.limit` | int32 | Specifies the limit (default 100) |
| `--filter.page` | int32 | Specifies the page number,  in case there are multiple pages of results (default 1) |
| `--filter.sortBy` | string | Specifies which field to sort results |
| `-h`, `--help` | help for workflow |
| `--latest` | | flag to indicate to fetch the latest version,  version flag will be ignored in this case |
| `--version` | string | version of the workflow to be fetched. |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-get/uctl-get-workflow-execution-config ===

# uctl get workflow-execution-config

Gets matchable resources of workflow execution config.

## Synopsis

Retrieve workflow execution config for the given project and domain, in
combination with the workflow name.

For project flytesnacks and development domain:

```shell
$ uctl get workflow-execution-config -p flytesnacks -d development
```

Example: output from the command:

``` json
{
   "project": "flytesnacks",
   "domain": "development",
   "max_parallelism": 5
}
```

Retrieve workflow execution config for the project, domain, and
workflow. For project flytesnacks, development domain and workflow
`core.control_flow.merge_sort.merge_sort`:

```shell
$ uctl get workflow-execution-config -p flytesnacks -d development core.control_flow.merge_sort.merge_sort
```

Example: output from the command:

``` json
{
   "project": "flytesnacks",
   "domain": "development",
   "workflow": "core.control_flow.merge_sort.merge_sort"
   "max_parallelism": 5
}
```

Write the workflow execution config to a file. If there are no workflow
execution config, the command throws an error. The config file is
written to wec.yaml file. Example: content of wec.yaml:

```shell
$ uctl get workflow-execution-config -p flytesnacks -d development --attrFile wec.yaml
```

``` yaml
domain: development
project: flytesnacks
max_parallelism: 5
```

Generate a sample workflow execution config file to be used for creating
a new workflow execution config at project domain

::

:   uctl get workflow-execution-config -p flytesnacks -d development
    --attrFile wec.yaml --gen

``` yaml
annotations:
  values:
    cliAnnotationKey: cliAnnotationValue
domain: development
labels:
  values:
    cliLabelKey: cliLabelValue
max_parallelism: 10
project: flytesnacks
raw_output_data_config:
  output_location_prefix: cliOutputLocationPrefix
security_context:
  run_as:
    k8s_service_account: default
```

Generate a sample workflow execution config file to be used for creating
a new workflow execution config at project domain workflow level

::

:   uctl get workflow-execution-config -p flytesnacks -d development
    --attrFile wec.yaml uctl get workflow-execution-config --gen

``` yaml
annotations:
  values:
    cliAnnotationKey: cliAnnotationValue
domain: development
labels:
  values:
    cliLabelKey: cliLabelValue
max_parallelism: 10
project: flytesnacks
workflow: k8s_spark.dataframe_passing.my_smart_structured_dataset
raw_output_data_config:
  output_location_prefix: cliOutputLocationPrefix
security_context:
  run_as:
    k8s_service_account: default
```

Usage:

```shell
$ uctl get workflow-execution-config [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--attrFile` | string | attribute file name to be used for generating attribute for the resource type. |
| `--gen` | | generates an empty workflow execution config file with conformance to the api format. |
| `-h`, `--help` | help for workflow-execution-config |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-register ===

# uctl register

Registers tasks, workflows, and launch plans from a list of generated
serialized files.

## Synopsis

Take input files as serialized versions of the
tasks/workflows/launchplans and register them with FlyteAdmin.
Currently, these input files are protobuf files generated as output from
Flytekit serialize. Project and Domain are mandatory fields to be passed
for registration and an optional version which defaults to v1. If the
entities are already registered with Flyte for the same version, the
registration would fail.

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for register |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |

## Subpages
- **Uctl CLI > uctl register > uctl register examples**
- **Uctl CLI > uctl register > uctl register files**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-register/uctl-register-examples ===

# uctl register examples

Registers Flytesnacks example.

## Synopsis

Register all the latest Flytesnacks examples:

```shell
$ uctl register examples  -d development  -p flytesnacks
```

Register specific release of Flytesnacks examples:

```shell
$ uctl register examples  -d development  -p flytesnacks --version v0.2.176
```

> [!NOTE]
> The register command automatically override the version with release version.

Usage:

```shell
$ uctl register examples [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--archive` | | Pass in archive file either an http link or local path. |
| Option | Type | Description |
|--------|------|-------------|
| `--assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--continueOnError` | | Continue on error when registering files. |
| `--destinationDirectory` | string | Location of source code in container. |
| `--dryRun` | | Execute command without making any modifications. |
| `--enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--force` | | Force use of version number on entities registered with flyte. |
| `-h`, `--help` | help for examples |
| `--k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-register/uctl-register-files ===

# uctl register files

Registers file resources.

## Synopsis

Registers all the serialized protobuf files including tasks, workflows
and launch plans with default v1 version.

If previously registered entities with v1 version are present, the
command will fail immediately on the first such encounter:

```shell
$ uctl register file  _pb_output/* -d development  -p flytesnacks
```

As per Flytectl, registration and fast registration mean the same!

In fast registration, the input provided by the user is fast serialized
proto generated by pyflyte. When the user runs pyflyte with --fast
flag, then pyflyte creates serialized proto and the source code archive
file in the same directory. Flytectl finds the input file by searching
for an archive file whose name starts with "fast" and has .tar.gz
extension. If Flytectl finds any source code in users' input, it
considers the registration as fast registration.

SourceUploadPath is an optional flag. By default, Flytectl will create
SourceUploadPath from your storage config. If s3, Flytectl will upload
the code base to
s3://{{DEFINE_BUCKET_IN_STORAGE_CONFIG}}/fast/{{VERSION}}-fast{{MD5_CREATED_BY_PYFLYTE}.tar.gz}.
:

```shell
$ uctl register file  _pb_output/* -d development  -p flytesnacks  --version v2
```

In case of fast registration, if the SourceUploadPath flag is defined,
Flytectl will not use the default directory to upload the source code.
Instead, it will override the destination path on the registration:

```shell
$ uctl register file  _pb_output/* -d development  -p flytesnacks  --version v2 --SourceUploadPath="s3://dummy/fast"
```

To register a .tgz or .tar file, use the --archive flag. They can be
local or remote files served through http/https.

```shell
$ uctl register files http://localhost:8080/_pb_output.tar -d development  -p flytesnacks --archive
```

Using local tgz file:

```shell
$ uctl register files  _pb_output.tgz -d development  -p flytesnacks --archive
```

If you wish to continue executing registration on other files by
ignoring the errors including the version conflicts, then send the
continueOnError flag:

```shell
$ uctl register file  _pb_output/* -d development  -p flytesnacks --continueOnError
```

Using short format of continueOnError flag:

```shell
$ uctl register file  _pb_output/* -d development  -p flytesnacks --continueOnError
```

Override the default version v1 using version string:

```shell
$ uctl register file  _pb_output/* -d development  -p flytesnacks --version v2
```

Changing the o/p format has no effect on the registration. The O/p is
currently available only in table format:

```shell
$ uctl register file  _pb_output/* -d development  -p flytesnacks --continueOnError -o yaml
```

Override IamRole during registration:

```shell
$ uctl register file  _pb_output/* -d development  -p flytesnacks --continueOnError --version v2 --assumableIamRole "arn:aws:iam::123456789:role/dummy"
```

Override Kubernetes service account during registration:

```shell
$ uctl register file  _pb_output/* -d development  -p flytesnacks --continueOnError --version v2 --k8sServiceAccount "kubernetes-service-account"
```

Override Output location prefix during registration:

```shell
$ uctl register file  _pb_output/* -d development  -p flytesnacks --continueOnError --version v2 --outputLocationPrefix "s3://dummy/prefix"
```

Override Destination dir of source code in container during
registration:

```shell
$ uctl register file  _pb_output/* -d development  -p flytesnacks --continueOnError --version v2 --destinationDirectory "/root"
```

Enable schedule for the launchplans part of the serialized protobuf
files:

```shell
$ uctl register file  _pb_output/* -d development  -p flytesnacks --version v2 --enableSchedule
```

Usage:

```shell
$ uctl register files [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--archive` | | Pass in archive file either an http link or local path. |
| Option | Type | Description |
|--------|------|-------------|
| `--assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--continueOnError` | | Continue on error when registering files. |
| `--destinationDirectory` | string | Location of source code in container. |
| `--dryRun` | | Execute command without making any modifications. |
| `--enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--force` | | Force use of version number on entities registered with flyte. |
| `-h`, `--help` | help for files |
| `--k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-update ===

# uctl update

Used for updating various union/flyte resources including apps, cluster
pools, cluster configs

## Synopsis

Provides subcommands to update Flyte resources, such as tasks,
workflows, launch plans, executions, and projects. Update Flyte
resource; e.g., to activate a project:

```shell
$ uctl update project -p flytesnacks --activate
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for update |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |

## Subpages
- **Uctl CLI > uctl update > uctl update cluster-pool-attributes**
- **Uctl CLI > uctl update > uctl update cluster-resource-attribute**
- **Uctl CLI > uctl update > uctl update execution**
- **Uctl CLI > uctl update > uctl update execution-cluster-label**
- **Uctl CLI > uctl update > uctl update execution-queue-attribute**
- **Uctl CLI > uctl update > uctl update launchplan**
- **Uctl CLI > uctl update > uctl update launchplan-meta**
- **Uctl CLI > uctl update > uctl update plugin-override**
- **Uctl CLI > uctl update > uctl update project**
- **Uctl CLI > uctl update > uctl update task-meta**
- **Uctl CLI > uctl update > uctl update task-resource-attribute**
- **Uctl CLI > uctl update > uctl update workflow-execution-config**
- **Uctl CLI > uctl update > uctl update workflow-meta**


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-update/uctl-update-cluster-pool-attributes ===

# uctl update cluster-pool-attributes

Update matchable resources for cluster pool assignment

## Synopsis

Update cluster pool assignment attributes for given project and domain
combination or additionally with workflow name.

Updating to the cluster pool attribute is only available from a
generated file. See the get section to generate this file. It takes
input for cluster resource attributes from the config file cpa.yaml,
Example: content of cpa.yaml:

``` yaml
domain: development
project: flytesnacks
clusterPoolName: my_cluster_pool
```

Update cluster pool assignment for project and domain and workflow
combination. This will take precedence over any other cluster pool
assignent defined at project domain level.

``` yaml
domain: development
project: flytesnacks
workflow: my_wf
clusterPoolName: my_cluster_pool
```

:

uctl update cluster-pool-attribute --attrFile cpa.yaml

To generate a skeleton cpa.yaml:

:

uctl update cluster-pool-attribute --genSkeleton --attrFile cpa.yaml

```shell
$ uctl update cluster-pool-attributes [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--attrFile` | string | cluster pool attribute file to be used for creating cluster pool matchable attribute. |
| `--force` | | do not ask for an acknowledgement during updates |
| `--genSkeleton` | | generates a skeleton cluster pool config attribute file with templatized values in full conformance with the api format. |
| `-h`, `--help` | help for cluster-pool-attributes |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-update/uctl-update-cluster-resource-attribute ===

# uctl update cluster-resource-attribute

Update matchable resources of cluster attributes

## Synopsis

Update cluster resource attributes for given project and domain
combination or additionally with workflow name.

Updating to the cluster resource attribute is only available from a
generated file. See the get section to generate this file. It takes
input for cluster resource attributes from the config file cra.yaml,
Example: content of cra.yaml:

``` yaml
domain: development
project: flytesnacks
attributes:
  foo: "bar"
  buzz: "lightyear"
```

```shell
$ uctl update cluster-resource-attribute --attrFile cra.yaml
```

Update cluster resource attribute for project and domain and workflow
combination. This will take precedence over any other resource attribute
defined at project domain level. This will completely overwrite any
existing custom project, domain and workflow combination attributes. It
is preferable to do get and generate an attribute file if there is an
existing attribute that is already set and then update it to have new
values. Refer to get cluster-resource-attribute section on how to
generate this file. For workflow
`core.control_flow.merge_sort.merge_sort` in flytesnacks project,
development domain, it is:

``` yaml
domain: development
project: flytesnacks
workflow: core.control_flow.merge_sort.merge_sort
attributes:
  foo: "bar"
  buzz: "lightyear"
```

```shell
$ uctl update cluster-resource-attribute --attrFile cra.yaml
```

Usage:

```shell
$ uctl update cluster-resource-attribute [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--attrFile` | string | attribute file name to be used for updating attribute for the resource type. |
| `--dryRun` | | execute command without making any modifications. |
| `--force` | | do not ask for an acknowledgement during updates. |
| `-h`, `--help` | help for cluster-resource-attribute |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-update/uctl-update-execution ===

# uctl update execution

Updates the execution status

## Synopsis

Activate an execution; and it shows up in the CLI and UI:

```shell
$ uctl update execution -p flytesnacks -d development  oeh94k9r2r --activate
```

Archive an execution; and it is hidden from the CLI and UI:

```shell
$ uctl update execution -p flytesnacks -d development  oeh94k9r2r --archive
```

Usage:

```shell
$ uctl update execution [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--activate` | | activate execution. |
| Option | Type | Description |
|--------|------|-------------|
| `--archive` | | archive execution. |
| Option | Type | Description |
|--------|------|-------------|
| `--dryRun` | | execute command without making any modifications. |
| Option | Type | Description |
|--------|------|-------------|
| `--force` | | do not ask for an acknowledgement during updates. |
| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for execution |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-update/uctl-update-execution-cluster-label ===

# uctl update execution-cluster-label

Update matchable resources of execution cluster label

## Synopsis

Update execution cluster label for the given project and domain
combination or additionally with workflow name.

Updating to the execution cluster label is only available from a
generated file. See the get section to generate this file. It takes
input for execution cluster label from the config file ecl.yaml Example:
content of ecl.yaml:

``` yaml
domain: development
project: flytesnacks
value: foo
```

```shell
$ uctl update execution-cluster-label --attrFile ecl.yaml
```

Update execution cluster label for project, domain, and workflow
combination. This will take precedence over any other execution cluster
label defined at project domain level. For workflow
`core.control_flow.merge_sort.merge_sort` in flytesnacks project,
development domain, it is:

``` yaml
domain: development
project: flytesnacks
workflow: core.control_flow.merge_sort.merge_sort
value: foo
```

```shell
$ uctl update execution-cluster-label --attrFile ecl.yaml
```

Usage:

```shell
$ uctl update execution-cluster-label [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--attrFile` | string | attribute file name to be used for updating attribute for the resource type. |
| `--dryRun` | | execute command without making any modifications. |
| `--force` | | do not ask for an acknowledgement during updates. |
| `-h`, `--help` | help for execution-cluster-label |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-update/uctl-update-execution-queue-attribute ===

# uctl update execution-queue-attribute

Update matchable resources of execution queue attributes

## Synopsis

Update execution queue attributes for the given project and domain
combination or additionally with workflow name.

Updating the execution queue attribute is only available from a
generated file. See the get section for generating this file. This will
completely overwrite any existing custom project, domain, and workflow
combination attributes. It is preferable to do get and generate an
attribute file if there is an existing attribute that is already set and
then update it to have new values. Refer to get
execution-queue-attribute section on how to generate this file It takes
input for execution queue attributes from the config file era.yaml,
Example: content of era.yaml:

``` yaml
domain: development
project: flytesnacks
tags:
  - foo
  - bar
  - buzz
  - lightyear
```

```shell
$ uctl update execution-queue-attribute --attrFile era.yaml
```

Update execution queue attribute for project, domain, and workflow
combination. This will take precedence over any other execution queue
attribute defined at project domain level. For workflow
`core.control_flow.merge_sort.merge_sort` in flytesnacks project,
development domain, it is:

``` yaml
domain: development
project: flytesnacks
workflow: core.control_flow.merge_sort.merge_sort
tags:
  - foo
  - bar
  - buzz
  - lightyear
```

```shell
$ uctl update execution-queue-attribute --attrFile era.yaml
```

Usage:

```shell
$ uctl update execution-queue-attribute [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--attrFile` | string | attribute file name to be used for updating attribute for the resource type. |
| `--dryRun` | | execute command without making any modifications. |
| `--force` | | do not ask for an acknowledgement during updates. |
| `-h`, `--help` | help for execution-queue-attribute |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-update/uctl-update-launchplan ===

# uctl update launchplan

Updates launch plan status

## Synopsis

Activates a [launch
plan](https://docs.flyte.org/en/latest/user_guide/productionizing/schedules.html#activating-a-schedule)
which activates the scheduled job associated with it:

```shell
$ uctl update launchplan -p flytesnacks -d development core.control_flow.merge_sort.merge_sort --version v1 --activate
```

Deactivates a [launch
plan](https://docs.flyte.org/en/latest/user_guide/productionizing/schedules.html#deactivating-a-schedule)
which deschedules any scheduled job associated with it:

```shell
$ uctl update launchplan -p flytesnacks -d development core.control_flow.merge_sort.merge_sort --version v1 --deactivate
```

Usage:

```shell
$ uctl update launchplan [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--activate` | | activate launchplan. |
| Option | Type | Description |
|--------|------|-------------|
| `--archive` | | (Deprecated) disable the launch plan schedule (if it has an active schedule associated with it). |
| Option | Type | Description |
|--------|------|-------------|
| `--deactivate` | | disable the launch plan schedule (if it has an active schedule associated with it). |
| Option | Type | Description |
|--------|------|-------------|
| `--dryRun` | | execute command without making any modifications. |
| Option | Type | Description |
|--------|------|-------------|
| `--force` | | do not ask for an acknowledgement during updates. |
| Option | Type | Description |
|--------|------|-------------|
| `-h`, `--help` | help for launchplan |
| `--version` | string | version of the launchplan to be fetched. |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-update/uctl-update-launchplan-meta ===

# uctl update launchplan-meta

Updates the launch plan metadata

## Synopsis

Update the description on the launch plan:

```shell
$ uctl update launchplan-meta -p flytesnacks -d development  core.advanced.merge_sort.merge_sort --description "Mergesort example"
```

Archiving launch plan named entity is not supported and would throw an
error:

```shell
$ uctl update launchplan-meta -p flytesnacks -d development  core.advanced.merge_sort.merge_sort --archive
```

Activating launch plan named entity would be a noop:

```shell
$ uctl update launchplan-meta -p flytesnacks -d development  core.advanced.merge_sort.merge_sort --activate
```

Usage:

```shell
$ uctl update launchplan-meta [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--activate` | | activate the named entity. |
| Option | Type | Description |
|--------|------|-------------|
| `--archive` | | archive named entity. |
| Option | Type | Description |
|--------|------|-------------|
| `--description` | string | description of the named entity. |
| `--dryRun` | | execute command without making any modifications. |
| `--force` | | do not ask for an acknowledgement during updates. |
| `-h`, `--help` | help for launchplan-meta |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-update/uctl-update-plugin-override ===

# uctl update plugin-override

Update matchable resources of plugin overrides

## Synopsis

Update plugin overrides for given project and domain combination or
additionally with workflow name.

Updating to the plugin override is only available from a generated file.
See the get section for generating this file. This will completely
overwrite any existing plugins overrides on custom project, domain, and
workflow combination. It is preferable to do get and generate a plugin
override file if there is an existing override already set and then
update it to have new values. Refer to get plugin-override section on
how to generate this file It takes input for plugin overrides from the
config file po.yaml, Example: content of po.yaml:

``` yaml
domain: development
project: flytesnacks
overrides:
   - task_type: python_task # Task type for which to apply plugin implementation overrides
     plugin_id:             # Plugin id(s) to be used in place of the default for the task type.
       - plugin_override1
       - plugin_override2
     missing_plugin_behavior: 1 # Behavior when no specified plugin_id has an associated handler. 0: FAIL , 1: DEFAULT
```

```shell
$ uctl update plugin-override --attrFile po.yaml
```

Update plugin override for project, domain, and workflow combination.
This will take precedence over any other plugin overrides defined at
project domain level. For workflow
`core.control_flow.merge_sort.merge_sort` in flytesnacks project,
development domain, it is:

``` yaml
domain: development
project: flytesnacks
workflow: core.control_flow.merge_sort.merge_sort
overrides:
   - task_type: python_task # Task type for which to apply plugin implementation overrides
     plugin_id:             # Plugin id(s) to be used in place of the default for the task type.
       - plugin_override1
       - plugin_override2
     missing_plugin_behavior: 1 # Behavior when no specified plugin_id has an associated handler. 0: FAIL , 1: DEFAULT
```

```shell
$ uctl update plugin-override --attrFile po.yaml
```

Usage:

```shell
$ uctl update plugin-override [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--attrFile` | string | attribute file name to be used for updating attribute for the resource type. |
| `--dryRun` | | execute command without making any modifications. |
| `--force` | | do not ask for an acknowledgement during updates. |
| `-h`, `--help` | help for plugin-override |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-update/uctl-update-project ===

# uctl update project

Update the characteristics of a project

## Synopsis

Allows you to update the characteristics of a project, including its
name, labels and description. Also allows you to archive or activate
(unarchive) a project.

To archive a project, specify its ID with the *p* flag and add the
*archive* flag:

```shell
$ uctl update project -p my-project-id --archive
```

To activate (unarchive) an archived project, specify its ID with the *p*
flag and add the *activate* flag:

```shell
$ uctl update project -p my-project-id --activate
```

To update the characteristics of a project using flags, specify the
project ID with the *p* flag and the flags corresponding to the
characteristics you want to update:

```shell
$ uctl update project -p my-project-id --description "A wonderful project"  --labels app=my-app
```

To update the characteristics of a project using a *yaml* file, define
the file with the project ID desired updates:

``` yaml
id: "my-project-id"
name: "my-project-name"
labels:
   values:
     app: my-app
description: "A wonderful project"
```

(Note: The name parameter must not contain whitespace)

Then, pass it in using the *file* flag:

```shell
$ uctl update project --file project.yaml
```

To archive or activate (unarchive) a project using a *yaml* file:

-   Add a state field, with a value of *0* for activated (unarchived) or
    *1* for archived, at the top level of the `yaml` file.
-   Add the *archive* flag to the command.

For example, to archive a project:

``` yaml
# update.yaml
id: "my-project-id"
state: 1
```

    $ uctl update project --file update.yaml --archive

And to activate (unarchive) the same project:

``` yaml
# update.yaml
id: "my-project-id"
state: 0
```

    $ uctl update project --file update.yaml --archive

Note that when using a *yaml* file, the *activate* flag is not used.
Instead, the *archive* flag is used for *both* archiving and activating
(unarchiving) with the difference being in the *state* field of the
*yaml* file. Furthermore, the *state* field only takes effect if the
*archive* flag is present in the command.

Usage:

```shell
$ uctl update project [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--activate` | | Activates the project specified as argument. Only used in update |
| Option | Type | Description |
|--------|------|-------------|
| `--activateProject` | | (Deprecated) Activates the project specified as argument. Only used in update |
| Option | Type | Description |
|--------|------|-------------|
| `--archive` | | Archives the project specified as argument. Only used in update |
| Option | Type | Description |
|--------|------|-------------|
| `--archiveProject` | | (Deprecated) Archives the project specified as argument. Only used in update |
| Option | Type | Description |
|--------|------|-------------|
| `--description` | string | description for the project specified as argument. |
| `--dryRun` | | execute command without making any modifications. |
| `--file` | string | file for the project definition. |
| `--force` | | Skips asking for an acknowledgement during an update operation. Only used in update |
| `-h`, `--help` | help for project |
| `--id` | string | id for the project specified as argument. |
| `--labels` | stringToString | labels for the project specified as argument. (default []) |
| `--name` | string | name for the project specified as argument. |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-update/uctl-update-task-meta ===

# uctl update task-meta

Update task metadata

## Synopsis

Update the description on the task:

```shell
$ uctl update task-meta  -d development -p flytesnacks core.control_flow.merge_sort.merge --description "Merge sort example"
```

Archiving task named entity is not supported and would throw an error:

```shell
$ uctl update task-meta -d development -p flytesnacks core.control_flow.merge_sort.merge --archive
```

Activating task named entity would be a noop since archiving is not
possible:

```shell
$ uctl update task-meta -d development -p flytesnacks core.control_flow.merge_sort.merge --activate
```

Usage:

```shell
$ uctl update task-meta [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--activate` | | activate the named entity. |
| Option | Type | Description |
|--------|------|-------------|
| `--archive` | | archive named entity. |
| Option | Type | Description |
|--------|------|-------------|
| `--description` | string | description of the named entity. |
| `--dryRun` | | execute command without making any modifications. |
| `--force` | | do not ask for an acknowledgement during updates. |
| `-h`, `--help` | help for task-meta |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-update/uctl-update-task-resource-attribute ===

# uctl update task-resource-attribute

Update matchable resources of task attributes

## Synopsis

Updates the task resource attributes for the given project and domain
combination or additionally with workflow name.

Updating the task resource attribute is only available from a generated
file. See the get section for generating this file. This will completely
overwrite any existing custom project, domain, and workflow combination
attributes. It is preferable to do get and generate an attribute file if
there is an existing attribute already set and then update it to have
new values. Refer to get task-resource-attribute section on how to
generate this file. It takes input for task resource attributes from the
config file tra.yaml, Example: content of tra.yaml:

``` yaml
domain: development
project: flytesnacks
defaults:
  cpu: "1"
  memory: "150Mi"
limits:
  cpu: "2"
  memory: "450Mi"
```

```shell
$ uctl update task-resource-attribute --attrFile tra.yaml
```

Update task resource attribute for project, domain, and workflow
combination. This will take precedence over any other resource attribute
defined at project domain level. For workflow
`core.control_flow.merge_sort.merge_sort` in flytesnacks project,
development domain, it is:

``` yaml
domain: development
project: flytesnacks
workflow: core.control_flow.merge_sort.merge_sort
defaults:
  cpu: "1"
  memory: "150Mi"
limits:
  cpu: "2"
  memory: "450Mi"
```

```shell
$ uctl update task-resource-attribute --attrFile tra.yaml
```

Usage:

```shell
$ uctl update task-resource-attribute [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--attrFile` | string | attribute file name to be used for updating attribute for the resource type. |
| `--dryRun` | | execute command without making any modifications. |
| `--force` | | do not ask for an acknowledgement during updates. |
| `-h`, `--help` | help for task-resource-attribute |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-update/uctl-update-workflow-execution-config ===

# uctl update workflow-execution-config

Updates matchable resources of workflow execution config

## Synopsis

Updates the workflow execution config for the given project and domain
combination or additionally with workflow name.

Updating the workflow execution config is only available from a
generated file. See the get section for generating this file. This will
completely overwrite any existing custom project and domain and workflow
combination execution config. It is preferable to do get and generate a
config file if there is an existing execution config already set and
then update it to have new values. Refer to get
workflow-execution-config section on how to generate this file. It takes
input for workflow execution config from the config file wec.yaml,
Example: content of wec.yaml:

``` yaml
domain: development
project: flytesnacks
max_parallelism: 5
security_context:
  run_as:
    k8s_service_account: demo
```

```shell
$ uctl update workflow-execution-config --attrFile wec.yaml
```

Update workflow execution config for project, domain, and workflow
combination. This will take precedence over any other execution config
defined at project domain level. For workflow
`core.control_flow.merge_sort.merge_sort` in flytesnacks project,
development domain, it is:

``` yaml
domain: development
project: flytesnacks
workflow: core.control_flow.merge_sort.merge_sort
max_parallelism: 5
security_context:
  run_as:
    k8s_service_account: mergesortsa
```

```shell
$ uctl update workflow-execution-config --attrFile wec.yaml
```

Usage:

```shell
$ uctl update workflow-execution-config [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--attrFile` | string | attribute file name to be used for updating attribute for the resource type. |
| `--dryRun` | | execute command without making any modifications. |
| `--force` | | do not ask for an acknowledgement during updates. |
| `-h`, `--help` | help for workflow-execution-config |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/api-reference/uctl-cli/uctl-update/uctl-update-workflow-meta ===

# uctl update workflow-meta

Update workflow metadata

## Synopsis

Update the description on the workflow:

```shell
$ uctl update workflow-meta -p flytesnacks -d development core.control_flow.merge_sort.merge_sort --description "Mergesort workflow example"
```

Archiving workflow named entity would cause this to disappear from
flyteconsole UI:

```shell
$ uctl update workflow-meta -p flytesnacks -d development core.control_flow.merge_sort.merge_sort --archive
```

Activate workflow named entity:

```shell
$ uctl update workflow-meta -p flytesnacks -d development core.control_flow.merge_sort.merge_sort --activate
```

Usage:

```shell
$ uctl update workflow-meta [flags]
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `--activate` | | activate the named entity. |
| Option | Type | Description |
|--------|------|-------------|
| `--archive` | | archive named entity. |
| Option | Type | Description |
|--------|------|-------------|
| `--description` | string | description of the named entity. |
| `--dryRun` | | execute command without making any modifications. |
| `--force` | | do not ask for an acknowledgement during updates. |
| `-h`, `--help` | help for workflow-meta |

### Options inherited from parent commands

| Option | Type | Description |
|--------|------|-------------|
| `--admin.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--admin.authType` | string | Type of OAuth2 flow used for communicating with admin.ClientSecret, Pkce, ExternalCommand are valid values (default "ClientSecret") |
| `--admin.authorizationHeader` | string | Custom metadata header to pass JWT |
| `--admin.authorizationServerUrl` | string | This is the URL to your IdP's authorization server. It'll default to Endpoint |
| `--admin.caCertFilePath` | string | Use specified certificate file to verify the admin server peer. |
| `--admin.clientId` | string | Client ID (default "flytepropeller") |
| `--admin.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--admin.clientSecretLocation` | string | File containing the client secret (default "/etc/secrets/client_secret") |
| `--admin.command` | strings | Command for external authentication token generation |
| `--admin.defaultOrg` | string | OPTIONAL: Default org to use to support non-org based cli's.'. |
| `--admin.defaultServiceConfig` | string |  |
| `--admin.deviceFlowConfig.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--admin.deviceFlowConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.deviceFlowConfig.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--admin.endpoint` | string | For admin types,  specify where the uri of the service is located. |
| `--admin.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--admin.insecure` | | Use insecure connection. |
| `--admin.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--admin.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--admin.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--admin.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--admin.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--admin.pkceConfig.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--admin.pkceConfig.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "2m0s") |
| `--admin.proxyCommand` | strings | Command for external proxy-authorization token generation |
| `--admin.scopes` | strings | List of scopes to request |
| `--admin.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "0s") |
| `--admin.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--admin.useAudienceFromAdmin` | | Use Audience configured from admins public endpoint config. |
| `--admin.useAuth` | | Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. |
| `--auth.appAuth.externalAuthServer.allowedAudience` | strings | Optional: A list of allowed audiences. If not provided,  the audience is expected to be the public Uri of the service. |
| `--auth.appAuth.externalAuthServer.baseUrl` | string | This should be the base url of the authorization server that you are trying to hit. With Okta for instance,  it will look something like https://company.okta.com/oauth2/abcdef123456789/ |
| `--auth.appAuth.externalAuthServer.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.appAuth.externalAuthServer.metadataUrl` | string | Optional: If the server doesn't support /.well-known/oauth-authorization-server,  you can set a custom metadata url here.' |
| `--auth.appAuth.externalAuthServer.retryAttempts` | int | Optional: The number of attempted retries on a transient failure to get the OAuth metadata (default 5) |
| `--auth.appAuth.externalAuthServer.retryDelay` | string | Optional,  Duration to wait between retries (default "1s") |
| `--auth.appAuth.selfAuthServer.accessTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "30m0s") |
| `--auth.appAuth.selfAuthServer.authorizationCodeLifespan` | string | Defines the lifespan of issued access tokens. (default "5m0s") |
| `--auth.appAuth.selfAuthServer.claimSymmetricEncryptionKeySecretName` | string | OPTIONAL: Secret name to use to encrypt claims in authcode token. (default "claim_symmetric_key") |
| `--auth.appAuth.selfAuthServer.issuer` | string | Defines the issuer to use when issuing and validating tokens. The default value is https://{requestUri.HostAndPort}/ |
| `--auth.appAuth.selfAuthServer.oldTokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve Old RSA Signing Key. This can be useful during key rotation to continue to accept older tokens. (default "token_rsa_key_old.pem") |
| `--auth.appAuth.selfAuthServer.refreshTokenLifespan` | string | Defines the lifespan of issued access tokens. (default "1h0m0s") |
| `--auth.appAuth.selfAuthServer.tokenSigningRSAKeySecretName` | string | OPTIONAL: Secret name to use to retrieve RSA Signing Key. (default "token_rsa_key.pem") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--auth.appAuth.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment (default "uctl") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment (default "http://localhost:53593/callback") |
| `--auth.appAuth.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. (default [all,offline]) |
| `--auth.disableForGrpc` | | Disables auth enforcement on Grpc Endpoints. |
| `--auth.disableForHttp` | | Disables auth enforcement on HTTP Endpoints. |
| `--auth.grpcAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpAuthorizationHeader` | string | (default "flyte-authorization") |
| `--auth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.tokenEndpointProxyPath` | string | The path used to proxy calls to the TokenURL |
| `--auth.userAuth.cookieBlockKeySecretName` | string | OPTIONAL: Secret name to use for cookie block key. (default "cookie_block_key") |
| `--auth.userAuth.cookieHashKeySecretName` | string | OPTIONAL: Secret name to use for cookie hash key. (default "cookie_hash_key") |
| `--auth.userAuth.cookieSetting.domain` | string | OPTIONAL: Allows you to set the domain attribute on the auth cookies. |
| `--auth.userAuth.cookieSetting.sameSitePolicy` | string | OPTIONAL: Allows you to declare if your cookie should be restricted to a first-party or same-site context.Wrapper around http.SameSite. (default "DefaultMode") |
| `--auth.userAuth.httpProxyURL` | string | OPTIONAL: HTTP Proxy to be used for OAuth requests. |
| `--auth.userAuth.idpQueryParameter` | string | idp query parameter used for selecting a particular IDP for doing user authentication. Eg: for Okta passing idp={IDP-ID} forces the authentication to happen with IDP-ID |
| `--auth.userAuth.openId.baseUrl` | string |  |
| `--auth.userAuth.openId.clientId` | string |  |
| `--auth.userAuth.openId.clientSecretFile` | string |  |
| `--auth.userAuth.openId.clientSecretName` | string | (default "oidc_client_secret") |
| `--auth.userAuth.openId.scopes` | strings | (default [openid,profile]) |
| `--auth.userAuth.redirectUrl` | string | (default "/console") |
| `--authorizer.internalCommunicationConfig.enabled` | | Enables authorization decisions for internal communication. (default true) |
| `--authorizer.internalCommunicationConfig.ingressIdentity` | string | IngressIdentity used in the cluster. Needed to exclude the communication coming from ingress. (default "ingress-nginx.ingress-nginx.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.tenantUrlPatternIdentity` | string | UrlPatternIdentity of the internal tenant service endpoint identities. (default "{{ service }}.{{ org }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.internalCommunicationConfig.urlPatternIdentity` | string | UrlPatternIdentity of the internal service endpoint identities. (default "{{ service }}-helmchart.{{ service }}.serviceaccount.identity.linkerd.cluster.local") |
| `--authorizer.mode` | string | (default "Active") |
| `--authorizer.organizationConfig.PolicyConfig.adminPolicyDescription` | string | description for the boilerplate admin policy (default "Contributor permissions and full admin permissions to manage users and view usage dashboards") |
| `--authorizer.organizationConfig.PolicyConfig.contributorPolicyDescription` | string | description for the boilerplate contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.defaultUserPolicyRoleType` | string | name of the role type to determine which default policy new users added to the organization should be assigned (default "Viewer") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessContributorPolicyDescription` | string | description for the boilerplate serverless contributor policy (default "Viewer permissions and permissions to create workflows, tasks, launch plans, and executions") |
| `--authorizer.organizationConfig.PolicyConfig.serverlessViewerPolicyDescription` | string | description for the boilerplate serverless viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.PolicyConfig.viewerPolicyDescription` | string | description for the boilerplate viewer policy (default "Permissions to view Flyte entities") |
| `--authorizer.organizationConfig.defaultPolicyCacheDuration` | string | Cache entry duration for the store of the default policy per organization (default "10m0s") |
| `--authorizer.syncRuleRefreshInterval` | string | (default "1m0s") |
| `--authorizer.type` | string | (default "UserClouds") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edgeTypes` | string | Specifies how long edge types remain in the cache.. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.edges` | string | Specifies how long edges remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objectTypes` | string | Specifies how long object types remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.redis.ttl.objects` | string | Specifies how long objects remain in the cache. (default "30m0s") |
| `--authorizer.userCloudsClient.cache.type` | string | Cache type to use. (default "none") |
| `--authorizer.userCloudsClient.clientID` | string | UserClouds client id |
| `--authorizer.userCloudsClient.clientSecretName` | string | UserCloud client secret name to read from the secret manager. (default "userclouds-client-secret") |
| `--authorizer.userCloudsClient.enableLogging` | | Enable userclouds client's internal logging. Calls to post logs take 250-350 ms and will impact p99 latency,  enable with caution. |
| `--authorizer.userCloudsClient.tenantID` | string | UserClouds tenant id. Should be a UUID. |
| `--authorizer.userCloudsClient.tenantUrl` | string | Something like https://{yourtenant}.tenant.userclouds.com |
| `--config` | string | config file (default is /Users/andrew/.union/config.yaml) |
| `--connection.environment` | string |  |
| `--connection.region` | string |  |
| `--connection.rootTenantURLPattern` | string | Pattern for tenant url. (default "dns:///{{ organization }}.cloud-staging.union.ai") |
| `--console.endpoint` | string | Endpoint of console,  if different than flyte admin |
| `--database.connMaxLifeTime` | string | sets the maximum amount of time a connection may be reused (default "1h0m0s") |
| `--database.enableForeignKeyConstraintWhenMigrating` | | Whether to enable gorm foreign keys when migrating the db |
| `--database.maxIdleConnections` | int | maxIdleConnections sets the maximum number of connections in the idle connection pool. (default 10) |
| `--database.maxOpenConnections` | int | maxOpenConnections sets the maximum number of open connections to the database. (default 100) |
| `--database.postgres.dbname` | string | The database name (default "postgres") |
| `--database.postgres.debug` | |  |
| `--database.postgres.host` | string | The host name of the database server (default "localhost") |
| `--database.postgres.options` | string | See http://gorm.io/docs/connecting_to_the_database.html for available options passed,  in addition to the above. (default "sslmode=disable") |
| `--database.postgres.password` | string | The database password. (default "postgres") |
| `--database.postgres.passwordPath` | string | Points to the file containing the database password. |
| `--database.postgres.port` | int | The port name of the database server (default 30001) |
| `--database.postgres.readReplicaHost` | string | The host name of the read replica database server (default "localhost") |
| `--database.postgres.username` | string | The database user who is connecting to the server. (default "postgres") |
| `--database.sqlite.file` | string | The path to the file (existing or new) where the DB should be created / stored. If existing,  then this will be re-used,  else a new will be created |
| `--db.connectionPool.maxConnectionLifetime` | string | (default "0s") |
| `--db.connectionPool.maxIdleConnections` | int |  |
| `--db.connectionPool.maxOpenConnections` | int |  |
| `--db.dbname` | string | (default "postgres") |
| `--db.debug` | |  |
| `--db.host` | string | (default "postgres") |
| `--db.log_level` | int | (default 4) |
| `--db.options` | string | (default "sslmode=disable") |
| `--db.password` | string |  |
| `--db.passwordPath` | string |  |
| `--db.port` | int | (default 5432) |
| `--db.username` | string | (default "postgres") |
| `-d`, `--domain` | string | Specifies the Flyte project's domain. |
| `--files.archive` | | Pass in archive file either an http link or local path. |
| `--files.assumableIamRole` | string | Custom assumable iam auth role to register launch plans with. |
| `--files.continueOnError` | | Continue on error when registering files. |
| `--files.destinationDirectory` | string | Location of source code in container. |
| `--files.dryRun` | | Execute command without making any modifications. |
| `--files.enableSchedule` | | Enable the schedule if the files contain schedulable launchplan. |
| `--files.force` | | Force use of version number on entities registered with flyte. |
| `--files.k8ServiceAccount` | string | Deprecated. Please use `--K8sServiceAccount`|
| `--files.k8sServiceAccount` | string | Custom kubernetes service account auth role to register launch plans with. |
| `--files.outputLocationPrefix` | string | Custom output location prefix for offloaded types (files/schemas). |
| `--files.sourceUploadPath` | string | Deprecated: Update flyte admin to avoid having to configure storage access from uctl. |
| `--files.version` | string | Version of the entity to be registered with flyte which are un-versioned after serialization. |
| `--logger.formatter.type` | string | Sets logging format type. (default "json") |
| `--logger.level` | int | Sets the minimum logging level. (default 3) |
| `--logger.mute` | | Mutes all logs regardless of severity. Intended for benchmarks/tests only. |
| `--logger.show-source` | | Includes source code location in logs. |
| `--org` | string | Organization to work on. If not set,  default to user's org. |
| `--otel.file.filename` | string | Filename to store exported telemetry traces (default "/tmp/trace.txt") |
| `--otel.jaeger.endpoint` | string | Endpoint for the jaeger telemetry trace ingestor (default "http://localhost:14268/api/traces") |
| `--otel.otlpgrpc.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4317") |
| `--otel.otlphttp.endpoint` | string | Endpoint for the OTLP telemetry trace collector (default "http://localhost:4318/v1/traces") |
| `--otel.sampler.parentSampler` | string | Sets the parent sampler to use for the tracer (default "always") |
| `--otel.type` | string | Sets the type of exporter to configure [noop/file/jaeger/otlpgrpc/otlphttp]. (default "noop") |
| `-o`, `--output` | string | Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "table") |
| `--plugins.catalogcache.reader.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.reader.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.reader.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `--plugins.catalogcache.writer.maxItems` | int | Maximum number of entries to keep in the index. (default 10000) |
| `--plugins.catalogcache.writer.maxRetries` | int | Maximum number of retries per item. (default 3) |
| `--plugins.catalogcache.writer.workers` | int | Number of concurrent workers to start processing the queue. (default 10) |
| `-p`, `--project` | string | Specifies the Flyte project. |
| `--rediscache.passwordSecretName` | string | Name of secret with Redis password. |
| `--rediscache.primaryEndpoint` | string | Primary endpoint for the redis cache that can be used for both reads and writes. |
| `--rediscache.replicaEndpoint` | string | Replica endpoint for the redis cache that can be used for reads. |
| `--secrets.env-prefix` | string | Prefix for environment variables (default "FLYTE_SECRET_") |
| `--secrets.secrets-prefix` | string | Prefix where to look for secrets file (default "/etc/secrets") |
| `--secrets.type` | string | Sets the type of storage to configure [local]. (default "local") |
| `--server.dataProxy.download.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.defaultFileNameLength` | int | Default length for the generated file name if not provided in the request. (default 20) |
| `--server.dataProxy.upload.maxExpiresIn` | string | Maximum allowed expiration duration. (default "1h0m0s") |
| `--server.dataProxy.upload.maxSize` | string | Maximum allowed upload size. (default "6Mi") |
| `--server.dataProxy.upload.storagePrefix` | string | Storage prefix to use for all upload requests. |
| `--server.grpc.enableGrpcLatencyMetrics` | | Enable grpc latency metrics. Note Histograms metrics can be expensive on Prometheus servers. |
| `--server.grpc.maxMessageSizeBytes` | int | The max size in bytes for incoming gRPC messages |
| `--server.grpc.port` | int | On which grpc port to serve admin (default 8089) |
| `--server.grpc.serverReflection` | | Enable GRPC Server Reflection (default true) |
| `--server.grpcPort` | int | deprecated |
| `--server.grpcServerReflection` | | deprecated |
| `--server.httpPort` | int | On which http port to serve admin (default 8088) |
| `--server.kube-config` | string | Path to kubernetes client config file,  default is empty,  useful for incluster config. |
| `--server.kubeClientConfig.burst` | int | Max burst rate for throttle. 0 defaults to 10 (default 25) |
| `--server.kubeClientConfig.qps` | int32 | Max QPS to the master for requests to KubeAPI. 0 defaults to 5. (default 100) |
| `--server.kubeClientConfig.timeout` | string | Max duration allowed for every request to KubeAPI before giving up. 0 implies no timeout. (default "30s") |
| `--server.master` | string | The address of the Kubernetes API server. |
| `--server.readHeaderTimeoutSeconds` | int | The amount of time allowed to read request headers. (default 32) |
| `--server.security.allowCors` | | (default true) |
| `--server.security.allowedHeaders` | strings | (default [Content-Type,flyte-authorization]) |
| `--server.security.allowedOrigins` | strings | (default [*]) |
| `--server.security.auditAccess` | |  |
| `--server.security.secure` | |  |
| `--server.security.ssl.certificateFile` | string |  |
| `--server.security.ssl.keyFile` | string |  |
| `--server.security.useAuth` | |  |
| `--server.thirdPartyConfig.flyteClient.audience` | string | Audience to use when initiating OAuth2 authorization requests. |
| `--server.thirdPartyConfig.flyteClient.clientId` | string | public identifier for the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.redirectUri` | string | This is the callback uri registered with the app which handles authorization for a Flyte deployment |
| `--server.thirdPartyConfig.flyteClient.scopes` | strings | Recommended scopes for the client to request. |
| `--server.watchService.maxActiveClusterConnections` | int | (default 5) |
| `--server.watchService.maxPageSize` | int | (default 50000) |
| `--server.watchService.nonTerminalStatusUpdatesInterval` | string | (default "1m0s") |
| `--server.watchService.pollInterval` | string | (default "1s") |
| `--sharedservice.connectPort` | string | On which connect port to serve admin (default "8080") |
| `--sharedservice.grpc.grpcMaxResponseStatusBytes` | int32 | specifies the maximum (uncompressed) size of header list that the client is prepared to accept on grpc calls (default 32000) |
| `--sharedservice.grpc.maxConcurrentStreams` | int | Limit on the number of concurrent streams to each ServerTransport. (default 100) |
| `--sharedservice.grpc.maxMessageSizeBytes` | int | Limit on the size of message that can be received on the server. (default 10485760) |
| `--sharedservice.grpcServerReflection` | | Enable GRPC Server Reflection (default true) |
| `--sharedservice.httpPort` | string | On which http port to serve admin (default "8089") |
| `--sharedservice.kubeConfig` | string | Path to kubernetes client config file. |
| `--sharedservice.master` | string | The address of the Kubernetes API server. |
| `--sharedservice.metrics.enableClientGrpcHistograms` | | Enable client grpc histograms (default true) |
| `--sharedservice.metrics.enableGrpcHistograms` | | Enable grpc histograms (default true) |
| `--sharedservice.metrics.scope` | string | Scope to emit metrics under (default "service:") |
| `--sharedservice.port` | string | On which grpc port to serve admin (default "8080") |
| `--sharedservice.profiler.enabled` | | Enable Profiler on server |
| `--sharedservice.profilerPort` | string | Profile port to start listen for pprof and metric handlers on. (default "10254") |
| `--sharedservice.security.allowCors` | |  |
| `--sharedservice.security.allowLocalhostAccess` | | Whether to permit localhost unauthenticated access to the server |
| `--sharedservice.security.allowedHeaders` | strings |  |
| `--sharedservice.security.allowedOrigins` | strings |  |
| `--sharedservice.security.auditAccess` | |  |
| `--sharedservice.security.orgOverride` | string | Override org in identity context if localhost access enabled |
| `--sharedservice.security.secure` | |  |
| `--sharedservice.security.ssl.certificateAuthorityFile` | string |  |
| `--sharedservice.security.ssl.certificateFile` | string |  |
| `--sharedservice.security.ssl.keyFile` | string |  |
| `--sharedservice.security.useAuth` | |  |
| `--sharedservice.sync.syncInterval` | string | Time interval to sync (default "5m0s") |
| `--storage.cache.max_size_mbs` | int | Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0,  cache is not used |
| `--storage.cache.target_gc_percent` | int | Sets the garbage collection target percentage. |
| `--storage.connection.access-key` | string | Access key to use. Only required when authtype is set to accesskey. |
| `--storage.connection.auth-type` | string | Auth Type to use [iam, accesskey]. (default "iam") |
| `--storage.connection.disable-ssl` | | Disables SSL connection. Should only be used for development. |
| `--storage.connection.endpoint` | string | URL for storage client to connect to. |
| `--storage.connection.region` | string | Region to connect to. (default "us-east-1") |
| `--storage.connection.secret-key` | string | Secret to use when accesskey is set. |
| `--storage.container` | string | Initial container (in s3 a bucket) to create -if it doesn't exist-.' |
| `--storage.defaultHttpClient.timeout` | string | Sets time out on the http client. (default "0s") |
| `--storage.enable-multicontainer` | | If this is true,  then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered |
| `--storage.limits.maxDownloadMBs` | int | Maximum allowed download size (in MBs) per call. (default 2) |
| `--storage.stow.config` | stringToString | Configuration for stow backend. Refer to github/flyteorg/stow (default []) |
| `--storage.stow.kind` | string | Kind of Stow backend to use. Refer to github/flyteorg/stow |
| `--storage.type` | string | Sets the type of storage to configure [s3/minio/local/mem/stow]. (default "s3") |
| `--union.auth.authorizationMetadataKey` | string | Authorization Header to use when passing Access Tokens to the server (default "flyte-authorization") |
| `--union.auth.clientId` | string | Client ID |
| `--union.auth.clientSecretEnvVar` | string | Environment variable containing the client secret |
| `--union.auth.clientSecretLocation` | string | File containing the client secret |
| `--union.auth.deviceFlow.pollInterval` | string | amount of time the device flow would poll the token endpoint if auth server doesn't return a polling interval. Okta and google IDP do return an interval' (default "5s") |
| `--union.auth.deviceFlow.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.deviceFlow.timeout` | string | amount of time the device flow should complete or else it will be cancelled. (default "10m0s") |
| `--union.auth.enable` | | Whether to enable an authenticated conenction when communicating with admin. (default true) |
| `--union.auth.externalAuth.command` | strings | Command for external authentication token generation |
| `--union.auth.pkce.refreshTime` | string | grace period from the token expiry after which it would refresh the token. (default "5m0s") |
| `--union.auth.pkce.timeout` | string | Amount of time the browser session would be active for authentication from client app. (default "15s") |
| `--union.auth.scopes` | strings | List of scopes to request |
| `--union.auth.tokenRefreshWindow` | string | Max duration between token refresh attempt and token expiry. (default "1h0m0s") |
| `--union.auth.tokenUrl` | string | OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. |
| `--union.auth.type` | string | Type of OAuth2 flow used for communicating with admin. (default "Pkce") |
| `--union.cache.maxItemsCount` | int | Maximum number of items to keep in the cache before evicting. (default 1000) |
| `--union.connection.host` | string | Host to connect to (default "dns:///utt-mgdp-stg-us-east-2.cloud-staging.union.ai") |
| `--union.connection.insecure` | | Whether to connect over insecure channel |
| `--union.connection.insecureSkipVerify` | | InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.Caution: shouldn't be use for production usecases' |
| `--union.connection.keepAliveConfig.permitWithoutStream` | | If true,  client sends keepalive pings even with no active RPCs. |
| `--union.connection.keepAliveConfig.time` | string | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default "20s") |
| `--union.connection.keepAliveConfig.timeout` | string | After having pinged for keepalive check,  the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default "2m0s") |
| `--union.connection.maxBackoffDelay` | string | Max delay for grpc backoff (default "8s") |
| `--union.connection.maxRecvMsgSize` | int | Maximum size of a message in bytes of a gRPC message (default 10485760) |
| `--union.connection.maxRetries` | int | Max number of gRPC retries (default 4) |
| `--union.connection.minConnectTimeout` | string | Minimum timeout for establishing a connection (default "20s") |
| `--union.connection.perRetryTimeout` | string | gRPC per retry timeout (default "15s") |
| `--union.connection.serviceConfig` | string | Defines gRPC experimental JSON Service Config (default "{"loadBalancingConfig": [{"round_robin":{}}]}") |
| `--union.connection.trustedIdentityClaims.enabled` | | Enables passing of trusted claims while making inter service calls |
| `--union.connection.trustedIdentityClaims.externalIdentityClaim` | string | External identity claim of the service which is authorized to make internal service call. These are verified against userclouds actions |
| `--union.connection.trustedIdentityClaims.externalIdentityTypeClaim` | string | External identity type claim of app or user to use for the current service identity. It should be an 'app' for inter service communication |
| `--union.internalConnectionConfig.-` | stringToString | (default []) |
| `--union.internalConnectionConfig.enabled` | | Enables internal service to service communication instead of going through ingress. |
| `--union.internalConnectionConfig.urlPattern` | string | UrlPattern of the internal service endpoints. (default "{{ service }}-helmchart.{{ service }}.svc.cluster.local:80") |
| `--webhook.awsSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "docker.io/amazon/aws-secrets-manager-secret-sidecar:v0.1.4") |
| `--webhook.certDir` | string | Certificate directory to use to write generated certs. Defaults to /etc/webhook/certs/ (default "/etc/webhook/certs") |
| `--webhook.embeddedSecretManagerConfig.awsConfig.region` | string | AWS region |
| `--webhook.embeddedSecretManagerConfig.fileMountInitContainer.image` | string | Specifies init container image to use for mounting secrets as files. (default "busybox:1.28") |
| `--webhook.embeddedSecretManagerConfig.gcpConfig.project` | string | GCP project to be used for secret manager |
| `--webhook.embeddedSecretManagerConfig.type` | string | (default "AWS") |
| `--webhook.gcpSecretManager.sidecarImage` | string | Specifies the sidecar docker image to use (default "gcr.io/google.com/cloudsdktool/cloud-sdk:alpine") |
| `--webhook.listenPort` | int | The port to use to listen to webhook calls. Defaults to 9443 (default 9443) |
| `--webhook.localCert` | | write certs locally. Defaults to false |
| `--webhook.metrics-prefix` | string | An optional prefix for all published metrics. (default "flyte:") |
| `--webhook.secretName` | string | Secret name to write generated certs to. (default "flyte-pod-webhook") |
| `--webhook.serviceName` | string | The name of the webhook service. (default "flyte-pod-webhook") |
| `--webhook.servicePort` | int32 | The port on the service that hosting webhook. (default 443) |
| `--webhook.vaultSecretManager.role` | string | Specifies the vault role to use (default "flyte") |


=== PAGE: https://www.union.ai/docs/v2/union/community ===

# Community

Union.ai is a commercial product built on top of the open source Flyte project.

Since the success of Flyte is essential to the success of Union.ai,
the company is dedicated to building and expanding the Flyte open source project and community.

For information on how to get involved and how to keep in touch, see the [Flyte variant of this page](/docs/v2/flyte//community).

## Contributing to documentation

Union AI maintains and hosts both Flyte and Union documentation at [www.union.ai/docs](/docs/v2/root/).
The two sets of documentation are deeply integrated, as the Union product is built on top of Flyte.
To better maintain both sets of docs, they are hosted in the same repository (but rendered so that you can choose to view one or the other).

Both the Flyte and Union documentation are open source.
Flyte community members and Union customers are both welcome to contribute to the documentation.

If you are interested, see [Contributing documentation and examples](./contributing-docs/_index).

## Subpages
- **Contributing docs and examples**


=== PAGE: https://www.union.ai/docs/v2/union/community/contributing-docs ===

# Contributing docs and examples

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

We welcome contributions to the docs and examples for both Flyte and Union.
This section will explain how the docs site works, how to author and build it locally, and how to publish your changes.

## The combined Flyte and Union docs site

As the primary maintainer and contributor of the open-source Flyte project, Union AI is responsible for hosting the Flyte documentation.

Additionally, Union AI is also the company behind the commercial Union.ai product, which is based on Flyte.

Since Flyte and Union.ai share a lot of common functionality, much of the documentation content is common between the two.
However, there are some significant differences between not only Flyte and Union.ai but also among the different Union.ai product offering (Serverless, BYOC, and Self-managed).

To effectively and efficiently maintain the documentation for all of these variants, we employ a single-source-of-truth approach where:

* All content is stored in a single GitHub repository, [`unionai/unionai-docs`](https://github.com/unionai/unionai-docs)
* All content is published on a single website, [`www.union.ai/docs`](/docs/v2/root/).
* The website has a variant selector at the top of the page that lets you choose which variant you want to view:
    * Flyte OSS
    * Union Serverless
    * Union BYOC
    * Union Self-managed
* There is also version selector. Currently two versions are available:
    * v1 (the original docs for Flyte/Union 1.x)
    * v2 (the new docs for Flyte/Union 2.0, which is the one you are currently viewing)

## Versions

The two versions of the docs are stored in separate branches of the GitHub repository:

* [`v1` branch](https://github.com/unionai/unionai-docs/tree/v1) for the v1 docs.
* [`main` branch](https://github.com/unionai/unionai-docs) for the v2 docs.

See **Contributing docs and examples > Versions** for more details.

## Common build infrastructure

The build infrastructure for the docs site (Hugo configuration, layouts, themes, build scripts, and Python tools) is maintained in a separate repository, [`unionai/unionai-docs-infra`](https://github.com/unionai/unionai-docs-infra), which is imported as a [git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) at `unionai-docs-infra/` in the `unionai-docs` repository.

This means both the `main` (v2) and `v1` content branches share the same build infrastructure.
Changes to the build system are made once in `unionai-docs-infra` and are picked up by both branches, keeping them in sync without duplicating build logic.

## Variants

Within each branch the multiple variants are supported by using conditional rendering:

* Each page of content has a `variants` front matter field that specifies which variants the page is applicable to.
* Within each page, rendering logic can be used to include or exclude content based on the selected variant.

The result is that:
* Content that is common to all variants is authored and stored once.
  There is no need to keep multiple copies of the same content in-sync.
* Content specific to a variant is conditionally rendered based on the selected variant.

See **Contributing docs and examples > Variants** for more details.

## Both Flyte and Union docs are open source

Since the docs are now combined in one repository, and the Flyte docs are open source, the Union docs are also open source.
All the docs are available for anyone to contribute to: Flyte contributors, Union customers, and Union employees.

If you are a Flyte contributor, you will be contributing docs related to Flyte features and functionality, but in many cases these features and functionality will also be available in Union.
Because the docs site is a single source for all the documentation, when you make changes related to Flyte that are also valid for Union you do so in the same place.
This is by design and is a key feature of the docs site.

## Subpages
- **Contributing docs and examples > Quick start**
- **Contributing docs and examples > Variants**
- **Contributing docs and examples > Versions**
- **Contributing docs and examples > Authoring**
- **Contributing docs and examples > Shortcodes**
- **Contributing docs and examples > Redirects**
- **Contributing docs and examples > API docs**
- **Contributing docs and examples > LLM-optimized documentation**
- **Contributing docs and examples > Publishing**


=== PAGE: https://www.union.ai/docs/v2/union/community/contributing-docs/quick-start ===

# Quick start

## Prerequisites

The docs site is built using the [Hugo](https://gohugo.io/) static site generator.
You will need to install it to build the site locally.
See [Hugo Installation](https://gohugo.io/getting-started/installing/).

## Clone the repository

Clone the [`unionai/unionai-docs`](https://github.com/unionai/unionai-docs) repository to your local machine.

The content is located in the `content/` folder in the form of Markdown files.
The hierarchy of the files and folders under `content/` directly reflect the URL and navigation structure of the site.

## Live preview

Next, set up the live preview by going to the root of your local repository check-out and copy the sample configuration file to `hugo.local.toml`:

```bash
cp unionai-docs-infra/hugo.local.toml~sample hugo.local.toml
```

This file contains the configuration for the live preview:

By default, it is set to display the `flyte` variant of the docs site along with enabling the flags `show_inactive`, `highlight_active`, and `highlight_keys` (more about these below)

Now you can start the live preview server by running:

```bash
make dev
```

This will build the site and launch a local server at `http://localhost:1313`.
Go to that URL to the live preview. Leave the server running.
As you edit the content you will see the changes reflected in the live preview.

## Distribution build

To build the site for distribution, run:

```bash
make dist
```

This will build the site locally just  as it is built by the Cloudflare CI for production.

You can view the result of the build by running a local server:

```bash
make serve
```

This will start a local server at `http://localhost:9000` and serve the contents of the `dist/` folder. You can also specify a port number:

```bash
make serve PORT=<nnnnn>
```


=== PAGE: https://www.union.ai/docs/v2/union/community/contributing-docs/variants ===

# Variants

The docs site supports the ability to show or hide content based of the current variant selection.
There are separate mechanisms for:

* Including or excluding entire pages based on the selected variant.
* Conditional rendering of content within a page based on the selected variant using an if-then-like construct.
* Rendering keywords as variables that change based on the selected variant.

Currently, the docs site supports two variants:

- **Flyte OSS**: The open-source Flyte project.
- **Union**: The Union.ai commercial product, available as BYOC (Bring Your Own Cloud) or Self-managed.

Each variant is referenced in the page logic using its respective code name: `flyte` or `union`.

The available set of variants are defined in the `config.<code_name>.toml` files in the `unionai-docs-infra/` directory.

## Variants at the whole-page level

The docs site supports the ability to show or hide entire pages based of the selected variant.
Not all pages are available in all variants because features differ across the variants.

In the public website, if you are on page in one variant, and you change to a different variant, the page will change to the same page in the new variant *if it exists*.
If it does not exist, you will see a message indicating that the page is not available in the selected variant.

In the source Markdown, the presence or absence of a page in a given variant is governed by  `variants` field in the front matter parameter of the page.
For example, if you look at the Markdown source for [this page (the page you are currently viewing)](https://github.com/unionai/unionai-docs/blob/main/content/community/contributing-docs.md), you will see the following front matter:

```markdown
---
title: Platform overview
weight: 1
variants: +flyte +union
---
```

The `variants` field has the value:

`+flyte +union`

The `+` indicates that the page is available for the specified variant.
In this case, the page is available for both variants.
If you wanted to make the page available for only the `flyte` variant, you would change the `variants` field to:

`+flyte -union`

In [live preview mode](./authoring#live-preview) with the `show_inactive` flag enabled, you will see all pages in the navigation tree, with the ones unavailable for the current variant grayed out.

As you can see, the `variants` field expects a space-separated list of keywords:

* The code names for the current variants are `flyte` and `union`.
* All supported variants must be included explicitly in every `variants` field with a leading `+` or `-`. There is no default behavior.
* The supported variants are configured in the `unionai-docs-infra/` directory in the files named `config.<variant>.toml`.

## Conditional rendering within a page

Content can also differ *within a page* based on the selected variant.
This is done with conditional rendering using the `{{</* variant */>}}` and `{{</* key */>}}` [Hugo shortcodes](https://gohugo.io/content-management/shortcodes/).

### {{</* variant */>}}

The syntax for the `{{</* variant */>}}` shortcode is:

```markdown
{{</* variant <variant_codes> */>}}
...
{{</* /variant */>}}
```

Where `<variant_codes>` is a list the code name for the variants you want to show the content for.

Note that the variant construct can only directly contain other shortcode constructs, not plain Markdown.
In the most common case, you will want to use the `{{</* markdown */>}}` shortcode  (which can contain Markdown) inside the `{{</* variant */>}}` shortcode to render Markdown content, like this:

```markdown
{{</* variant union */>}}
{{</* markdown */>}}
This content is only visible in the `union` variant.
{{</* /markdown */>}}
{{</* button-link text="Contact Us" target="https://union.ai/contact" */>}}
{{</* /variant */>}}
```

For more details on the `{{</* variant */>}}` shortcode, see the [Shortcodes > `variant`](./shortcodes#variant).

### {{</* key */>}}

The syntax for the `{{</* key */>}}` shortcode is:

CODE2

Where `<key_name>` is the name of the key you want to render.
For example, if you want to render the product name keyword, you would use:

CODE3
The available key names are defined in the [params.key] section of the `hugo.site.toml` configuration file in the root of the repository.

For example the `product_name` used above is defined in that file as

CODE4

Meaning that in any content that appears in the `flyte` variant of the site `{{</* key product_name */>}}` shortcode will be replaced with `Flyte`, and in any content that appears in the `union` variant, it will be replaced with `Union.ai`.

For more details on the `{{</* key */>}}` shortcode, see the [Shortcodes > `key`](./shortcodes#key)

## Full example

Here is full example. If you look at the Markdown source for [this page (the page you are currently viewing)](https://github.com/unionai/unionai-docs/blob/main/content/community/contributing-docs/variants.md), you will see the following section:

```markdown
> **This text is visible in all variants.**
>
> {{</* variant flyte */>}}
> {{</* markdown */>}}
>
> **This text is only visible in the `flyte` variant.**
>
> {{</* /markdown */>}}
> {{</* /variant */>}}
> {{</* variant union */>}}
> {{</* markdown */>}}
>
> **This text is only visible in the `union` variant.**
>
> {{</* /markdown */>}}
> {{</* /variant */>}}
>
> **Below is a `{{</* key product_full_name */>}}` shortcode.
> It will be replaced with the current variant's full name:**
>
> **{{</* key product_full_name */>}}**
```

This Markdown source is rendered as:

> **This text is visible in all variants.**
>
> 
> > 
>
> **This text is only visible in the `union` variant.**
>
> 
>
>
> **Below is a `{{</* key product_full_name */>}}` shortcode.
> It will be replaced with the current variant's full name:**
>
> **Union.ai**

If you switch between variants with the variant selector at the top of the page, you will see the content change accordingly.

## Adding a new variant

A variant is a term we use to identify a product or major section of the site.
Such variant has a dedicated token that identifies it, and all resources are
tagged to be either included or excluded when the variant is built.

> Adding new variants is a rare event and must be reserved when new products
> or major developments.
>
> If you are thinking adding a new variant is the way
> to go, please double-check with the infra admin to confirm before doing all
> the work below and waste your time.

### Location

When deploying, the variant takes a folder in the root

`https://<your-site-domain>/<variant>/<content>`

For example, if we have a variant `acme`, then when built the content goes to:

`https://<your-site-domain>/acme/<content>`

### Creating a new variant

To create a new variant a few steps are required:

| File                                      | Changes                                                        |
| ----------------------------------------- | -------------------------------------------------------------- |
| `hugo.site.toml`                          | Add to `params.variant_weights` and all `params.key`           |
| `unionai-docs-infra/hugo.toml`            | Add to `params.search`                                         |
| `unionai-docs-infra/Makefile`             | Add a new `make variant` to `dist` target                      |
| `<content>.md`                            | Add either `+<variant>` or `-<variant>` to all content pages   |
| `unionai-docs-infra/config.<variant>.toml`| Create a new file and configure `baseURL` and `params.variant` |

### Testing the new variant

As you develop the new variant, it is recommended to have a `pre-release/<variant>` semi-stable
branch to confirm everything is working and the content looks good. It will also allow others
to collaborate by creating PRs against it (`base=pre-release/<variant>` instead of `main`)
without trampling on each other and allowing for parallel reviews.

Once the variant branch is correct, you merge that branch into main.

### Building (just) the variant

You can build the production version of the variant,
which will also trigger all the safety checks as well,
by invoking the variant build:

```bash
make variant VARIANT=<variant>
```

For example:

```bash
make variant VARIANT=union
```


=== PAGE: https://www.union.ai/docs/v2/union/community/contributing-docs/versions ===

# Versions

In addition to the product variants, the docs site also supports multiple versions of the documentation.
The version selector is located at the top of the page, next to the variant selector.
Versions and variants are independent of each other, with the version being "above" the variant in the URL hierarchy.

The URL for version `v2` of the current page (the one you are one right now) in the Flyte variant is:

`/docs/v2/flyte//community/contributing-docs/versions`

while the URL for version `v1` of the same page is:

`/docs/v1/flyte//community/contributing-docs/versions`

### Versions are branches

The versioning system is based on long-lived Git branches in the `unionai/unionai-docs` GitHub repository:

- The `main` branch contains the latest version of the documentation. Currently, `v2`.
- Other versions of the docs are contained in branches named `vX`, where `X` is the major version number. Currently, there is one other version, `v1`.

## How to create an archive version

An "archive version" is a static snapshot of the site at a given point in time.

It is meant to freeze a specific version of the site for historical purposes,
such as preserving the content and structure of the site at a specific point in time.

### How to create an archive version

1. Create a new branch from `main` named `vX`, e.g. `v3`.
2. Add the version to the `VERSION` field in the `makefile.inc` file, e.g. `VERSION := v3`.
3. Add the version to the `versions` field in the `hugo.ver.toml` file, e.g. `versions = [ "v1", "v2", "v3" ]`.

> [!NOTE]
> **Important:** You must update the `versions` field in **ALL** published and archived versions of the site.

### Publishing an archive version

> [!NOTE]
> This step can only be done by a Union employee.

1. Update the `docs_archive_versions` in the `docs_archive_locals.tf` Terraform file
2. Create a PR for the changes
3. Once the PR is merged, run the production pipeline to activate the new version


=== PAGE: https://www.union.ai/docs/v2/union/community/contributing-docs/authoring ===

# Authoring

## Getting started

Content is located in the `content` folder.

To create a new page, simply create a new Markdown file in the appropriate folder and start writing it!

## Target the right branch

Remember that there are two production branches in the docs: `main` and `v1`.

* **For Flyte or Union 1, create a branch off of `v1` and target your pull request to `v1`**
* **For Flyte or Union 2, create a branch off of `main` and target your pull request to `main`**

## Live preview

While editing, you can use Hugo's local live preview capabilities.
Simply execute

```bash
make dev
```

This will build the site and launch a local server at `http://localhost:1313`.
Go to that URL to the live preview. Leave the server running.
As you edit the preview will update automatically.

See [Publishing](./publishing) for how to set up your machine.

## Pull Requests + Site Preview

Pull requests will create a preview build of the site on CloudFlare.
Check the pull request for a dynamic link to the site changes within that PR.

## Page Visibility

This site uses variants, which means different "flavors" of the content.
For a given -age, its variant visibility is governed by the `variants:` field in the front matter of the page source.
For each variant you specify `+<variant>` to include or `-<variant>` to exclude it.
For example:

```markdown
---
title: My Page
variants: -flyte +union
---
```

In this example the page will be:

* Included in Serverless and BYOC.
* Excluded from Flyte and Self-managed.

> [!NOTE]
> All variants must be explicitly listed in the `variants` field.
> This helps avoid missing or extraneous pages.

## Page order

Pages are ordered by the value of `weight` field (an integer >= 0) in the frontmatter of the page,

1. The higher the weight the lower the page sits in navigation ordering among its peers in the same folder.
2. Pages with no weight field (or `weight = 0`) will be ordered last.
3. Pages of the same weight will be sorted alphabetically by their title.
4. Folders are ordered among their peers (other folders and pages at the same level of the hierarchy) by the weight of their `_index.md` page.

For example:

```markdown
---
title: My Page
weight: 3
---
```

## Page settings

| Setting            | Type | Description                                                                       |
| ------------------ | ---- | --------------------------------------------------------------------------------- |
| `top_menu`         | bool | If `true` the item becomes a tab at the top and its hierarchy goes to the sidebar |
| `sidebar_expanded` | bool | If `true` the section becomes expanded in the sidebar. Permanently.              |
| `site_root`        | bool | If `true` indicates that the page is the site landing page                        |
| `toc_max`          | int  | Maximum heading to incorporate in the right navigation table of contents.         |
| `llm_readable_bundle` | bool | If `true`, generates a `section.md` bundle for this section. Requires `{{</* llm-bundle-note */>}}` shortcode. See [LLM-optimized documentation](./llm-docs). |

## Conditional Content

The site has "flavors" of the documentation. We leverage the `{{</* variant */>}}` tag to control
which content is rendered on which flavor.

Refer to [**Variants**](./shortcodes#variants) for detailed explanation.

## Warnings and Notices

You can write regular Markdown and use the notation below to create information and warning boxes:

```markdown
> [!NOTE] This is the note title
> You write the note content here. It can be
> anything you want.
```

Or if you want a warning:

```markdown
> [!WARNING] This is the title of the warning
> And here you write what you want to warn about.
```

## Special Content Generation

There are various short codes to generate content or special components (tabs, dropdowns, etc.)

Refer to [**Content Generation**](./shortcodes) for more information.

## Python Generated Content

You can generate pages from markdown-commented Python files.

At the top of your `.md` file, add:

```markdown
---
layout: py_example
example_file: /path/to/your/file.py
run_command: union run --remote tutorials//path/to/your/file.py main
source_location: https://www.github.com/unionai/unionai-examples/tree/main/tutorials/path/to/your/file.py
---
```

Where the referenced file looks like this:

```python
# # Credit Default Prediction with XGBoost & NVIDIA RAPIDS
#
# In this tutorial, we will use NVIDIA RAPIDS `cudf` DataFrame library for preprocessing
# data and XGBoost, an optimized gradient boosting library, for credit default prediction.
# We'll learn how to declare NVIDIA  `A100` for our training function and `ImageSpec`
# for specifying our python dependencies.
# {{run-on-union}}
# ## Declaring workflow dependencies
#
# First, we start by importing all the dependencies that is required by this workflow:
import os
import gc
from pathlib import Path
from typing import Tuple
import fsspec
from flytekit import task, workflow, current_context, Resources, ImageSpec, Deck
from flytekit.types.file import FlyteFile
from flytekit.extras.accelerators import A100
```

Note that the text content is embedded in comments as Markdown, and the code is normal python code.

The generator will convert the markdown into normal page text content and the code into code blocks within that Markdown content.

### Run on Union Instructions

We can add the run on Union instructions anywhere in the content.
Annotate the location you want to include it with `{{run-on-union}}`. Like this:

CODE6

The resulting **Run on Union** section in the rendered docs will include the run command and source location,
specified as `run_command` and `source_location` in the front matter of the corresponding `.md` page.

## Jupyter Notebooks

You can also generate pages from Jupyter notebooks.

At the top of your.md file, add:

    ---
    jupyter_notebook: /path/to/your/notebook.ipynb
    ---

Jupyter notebook conversion is handled automatically as part of the production build:

CODE7

The conversion tool is located at `unionai-docs-infra/tools/jupyter_generator`.

**Committing the change:** When the PR is pushed, a CI check verifies consistency between the notebook and its generated content. Please ensure that if you change the notebook, you run `make dist` to update the generated page.

## Mapped Keys (`{{</* key */>}}`)

Key is a very special command that allows us to define mapped values to a variant.
For example, the product name changes if it is Flyte, Union BYOC, etc. For that,
we can define a single key `product_full_name` and map it to reflect automatically,
without the need to `if variant` around it.

Please refer to [{{</* key */>}} shortcode](./shortcodes#key) for more details.

## Mermaid Graphs

To embed Mermaid diagrams in a page, insert the code inside a block like this:

    CODE8

Also add `mermaid: true` to the top of your page to enable rendering.

> [!NOTE]
> You can use [Mermaid's playground](https://www.mermaidchart.com/play) to design diagrams and get the code


=== PAGE: https://www.union.ai/docs/v2/union/community/contributing-docs/shortcodes ===

# Shortcodes

This site has special blocks that can be used to generate code for Union.

> [!NOTE]
> You can see examples by running the dev server and visiting
> [`http://localhost:1313/__docs_builder__/shortcodes/`](`http://localhost:1313/__docs_builder__/shortcodes/`).
> Note that this page is only visible locally. It does not appear in the menus or in the production build.
>
> If you need instructions on how to create the local environment and get the
> `localhost:1313` server running, please refer to the [local development guide](./publishing).

## How to specify a "shortcode"

The shortcode is a string that is used to generate the HTML that is displayed.

You can specify parameters, when applicable, or have content inside it, if applicable.

> [!NOTE]
> If you specify content, you have to have a close tag.

Examples:

* A shortcode that just outputs something

```markdown
{{</* key product_name */>}}
```

* A shortcode that has content inside

```markdown
{{</* markdown */>}}
* You markdown
* goes here
{{</* /markdown */>}}
```

* A shortcode with parameters

```markdown
{{</* link-card target="union-sdk" icon="workflow" title="Union SDK" */>}}
The Union SDK provides the Python API for building Union workflows and apps.
{{</* /link-card */>}}
```

> [!NOTE]
> If you're wondering why we have a `{{</* markdown */>}}` when we can generate markdown at the top level, it is due to a quirk in Hugo:
> * At the top level of the page, Hugo can render markdown directly, interspersed with shortcodes.
> * However, *inside* a container shortcode, Hugo can only render *either* other shortcodes *or* Markdown.
> * The `{{</* markdown */>}}` shortcode is designed to contain only Markdown (not other shortcodes).
> * All other container shortcodes are designed to contain only other shortcodes.

## Variants

The big difference of this site, compared to other documentation sites, is that we generate multiple "flavors" of the documentation that are slightly different from each other. We are calling these "variants."

When you are writing your content, and you want a specific part of the content to be conditional to a flavor, say "BYOC", you surround that with `variant`.

>[!NOTE]
> `variant` is a container, so inside you will specify what you are wrapping.
> You can wrap any of the shortcodes listed in this document.

Example:

```markdown
{{</* variant byoc selfmanaged */>}}
{{</* markdown */>}}
**The quick brown fox signed up for Union!**
{{</* /markdown */>}}

{{</* button-link text="Contact Us" target="https://union.ai/contact" */>}}
{{</* /variant */>}}
```

## Component Library

### `{{</* audio */>}}`

Generates an audio media player.

<!-- TODO: document parameters -->

### `{{</* grid */>}}`

Creates a fixed column grid for lining up content.

<!-- TODO: document parameters -->

### `{{</* variant */>}}`

Filters content based on which flavor you're seeing.

<!-- TODO: document parameters -->

### `{{</* link-card */>}}`

A floating, clickable, navigable card.

<!--  TODO: document parameters -->

### `{{</* markdown */>}}`

Generates a markdown block, to be used inside containers such as `{{</* dropdown */>}}` or `{{</* variant */>}}`.

<!-- TODO: document parameters -->

### `{{</* multiline */>}}`

Generates a multiple line, single paragraph. Useful for making a multiline table cell.

<!-- TODO: document parameters -->

### `{{</* tabs */>}}` and `{{</* tab */>}}`

Generates a tab panel with content switching per tab.

<!-- TODO: document parameters -->

### `{{</* key */>}}`

Outputs one of the pre-defined keywords.
Enables inline text that differs per-variant without using the heavy-weight `{{</* variant>}}...{{</* /variant */>}}` construct.

Take, for example, the following:

```markdown
The {{</* key product_name */>}} platform is awesome.
```

In the Flyte variant of the site this will render as:

> The Flyte platform is awesome.

While, in the BYOC, Self-managed and Serverless variants of the site it will render as:

> The Union.ai platform is awesome.

You can add keywords and specify their value, per variant, in `hugo.site.toml`:

```toml
[params.key.product_full_name]
flyte = "Flyte"
byoc = "Union BYOC"
selfmanaged = "Union Self-managed"
```

#### List of available keys

| Key               | Description                           | Example Usage (Flyte → Union)                                          |
| ----------------- | ------------------------------------- | ---------------------------------------------------------------------- |
| default_project   | Default project name used in examples | `{{</* key default_project */>}}` → "flytesnacks" or "default"             |
| product_full_name | Full product name                     | `{{</* key product_full_name */>}}` → "Flyte OSS" or "Union.ai BYOC"       |
| product_name      | Short product name                    | `{{</* key product_name */>}}` → "Flyte" or "Union.ai"                     |
| product           | Lowercase product identifier          | `{{</* key product */>}}` → "flyte" or "union"                             |
| kit_name          | SDK name                              | `{{</* key kit_name */>}}` → "Flytekit" or "Union"                         |
| kit               | Lowercase SDK identifier              | `{{</* key kit */>}}` → "flytekit" or "union"                              |
| kit_as            | SDK import alias                      | `{{</* key kit_as */>}}` → "fl" or "union"                                 |
| kit_import        | SDK import statement                  | `{{</* key kit_import */>}}` → "flytekit as fl" or "union"                 |
| kit_remote        | Remote client class name              | `{{</* key kit_remote */>}}` → "FlyteRemote" or "UnionRemote"              |
| cli_name          | CLI tool name                         | `{{</* key cli_name */>}}` → "Pyflyte" or "Union"                          |
| cli               | Lowercase CLI tool identifier         | `{{</* key cli */>}}` → "pyflyte" or "union"                               |
| ctl_name          | Control tool name                     | `{{</* key ctl_name */>}}` → "Flytectl" or "Uctl"                          |
| ctl               | Lowercase control tool identifier     | `{{</* key ctl */>}}` → "flytectl" or "uctl"                               |
| config_env        | Configuration environment variable    | `{{</* key config_env */>}}` → "FLYTECTL_CONFIG" or "UNION_CONFIG"         |
| env_prefix        | Environment variable prefix           | `{{</* key env_prefix */>}}` → "FLYTE" or "UNION"                          |
| docs_home         | Documentation home URL                | `{{</* key docs_home */>}}` → "/docs/flyte" or "/docs/byoc"               |
| map_func          | Map function name                     | `{{</* key map_func */>}}` → "map_task" or "map"                           |
| logo              | Logo image filename                   | `{{</* key logo */>}}` → "flyte-logo.svg" or "union-logo.svg"              |
| favicon           | Favicon image filename                | `{{</* key favicon */>}}` → "flyte-favicon.ico" or "union-favicon.ico"     |

### `{{</* download */>}}`

Generates a download link.

Parameters:
- `url`: The URL to download from
- `filename`: The filename to save the file as
- `text`: The text to display for the download link

Example:

```markdown
{{</* download "/_static/public/public-key.txt" "public-key.txt" */>}}
```

### `{{</* docs_home */>}}`

Produces a link to the home page of the documentation for a specific variant.

Example:

```markdown
[See this in Flyte]({{</* docs_home flyte>}}/wherever/you/want/to/go/in/flyte/docs)
```

### `{{</* py_class_docsum */>}}`, `{{</* py_class_ref */>}}`, and `{{</* py_func_ref */>}}`

Helper functions to track Python classes in Flyte documentation, so we can link them to
the appropriate documentation.

Parameters:
- name of the class
- text to add to the link

Example:

```markdown
Please see {{</* py_class_ref flyte.core.Image */>}} for more details.
```

### `{{</* icon name */>}}`

Uses a named icon in the content.

Example:

```markdown
[Download {{</* icon download */>}}](/download)
```

### `{{</* code */>}}`

Includes a code snippet or file.

Parameters:
- `file`: The path to the file to include.
- `fragment`: The name of the fragment to include.
- `from`: The line number to start including from.
- `to`: The line number to stop including at.
- `lang`: The language of the code snippet.
- `show_fragments`: Whether to show the fragment names in the code block.
- `highlight`: Whether to highlight the code snippet.

The examples in this section uses this file as base:

```
def main():
    """
    A sample function
    """
    return 42

# {{docs-fragment entrypoint}}
if __name__ == "__main__":
    main()
# {{/docs-fragment entrypoint}}
```

*Source: /_static/__docs_builder__/sample.py*
Link to [/_static/__docs_builder__/sample.py](/_static/__docs_builder__/sample.py)

#### Including a section of a file: `{{docs-fragment}}`

```markdown
{{</* code file="/_static/__docs_builder__/sample.py" fragment=entrypoint lang=python */>}}
```

Effect:

```
def main():
    """
    A sample function
    """
    return 42

# {{docs-fragment entrypoint}}
if __name__ == "__main__":
    main()
# {{/docs-fragment entrypoint}}
```

*Source: /_static/__docs_builder__/sample.py*

#### Including a file with a specific line range: `from` and `to`

```markdown
{{</* code file="/_static/__docs_builder__/sample.py" from=2 to=4 lang=python */>}}
```

Effect:

```
def main():
    """
    A sample function
    """
    return 42

# {{docs-fragment entrypoint}}
if __name__ == "__main__":
    main()
# {{/docs-fragment entrypoint}}
```

*Source: /_static/__docs_builder__/sample.py*

#### Including a whole file

Simply specify no filters, just the `file` attribute:

```markdown
{{</* code file="/_static/__docs_builder__/sample.py" */>}}
```

> [!NOTE]
> Note that without `show_fragments=true` the fragment markers will not be shown.

Effect:

```
def main():
    """
    A sample function
    """
    return 42

# {{docs-fragment entrypoint}}
if __name__ == "__main__":
    main()
# {{/docs-fragment entrypoint}}
```

*Source: /_static/__docs_builder__/sample.py*


=== PAGE: https://www.union.ai/docs/v2/union/community/contributing-docs/redirects ===

# Redirects

We use Cloudflare's Bulk Redirect to map URLs that moved to their new location,
so the user does not get a 404 using the old link.

The direct files are in CSV format, with the following structure:

`<incoming_redirect>,<target_url>,302,TRUE,FALSE,TRUE,TRUE`

- `<incoming_redirect>`: the URL without `https://`
- `<target_url>`: the full URL (including `https://`) to send the user to

Redirects are recorded in the `unionai-docs-infra/redirects.csv` file.

To take effect, this file must be applied to the production environment on CloudFlare by a Union employee.

If you need to add a new redirect, please create a pull request with the change to `redirect.csv` and a note indicating that you would like to have it applied to production.

## `docs.union.ai` redirects

For redirects from the old `docs.union.ai` site to the new `www.union.ai/docs` site, we use the original request URL. For example:

|
|-|-|
| Request URL | `https://docs.union.ai/administration` |
| Target URL | `/docs/v1/union//user-guide/administration` |
| Redirect Entry | `docs.union.ai/administration,/docs/v1/union//user-guide/administration,302,TRUE,FALSE,TRUE,TRUE` |

## `docs.flyte.org` redirects

For directs from the old `docs.flyte.org` to the new `www.union.ai/docs`, we replace the `docs.flyte.org` in the request URL with the special prefix `www.union.ai/_r_/flyte`. For example:

|
|-|-|
| Request URL | `https://docs.flyte.org/projects/flytekit/en/latest/generated/flytekit.dynamic.html` |
| Converted request URL | `www.union.ai/_r_/flyte/projects/flytekit/en/latest/generated/flytekit.dynamic.html` |
| Target URL | `/docs/v1/flyte//api-reference/flytekit-sdk/packages/flytekit.core.dynamic_workflow_task/` |
| Redirect Entry | `www.union.ai/_r_/flyte/projects/flytekit/en/latest/generated/flytekit.dynamic.html,/docs/v1/flyte//api-reference/flytekit-sdk/packages/flytekit.core.dynamic_workflow_task/,302,TRUE,FALSE,TRUE,TRUE` |

The special prefix is used so that we can include both `docs.union.ai` and `docs.flyte.org` redirects in the same file and apply them on the same domain (`www.union.ai`).


=== PAGE: https://www.union.ai/docs/v2/union/community/contributing-docs/api-docs ===

# API docs

You can import Python APIs and host them on the site. To do that you will use
the `unionai-docs-infra/tools/api_generator` to parse and create the appropriate markdown.

Please refer to [`api_generator/README`](https://github.com/unionai/unionai-docs-infra/blob/main/tools/api_generator/README.md) for more details.

## API naming convention

All the buildable APIs are defined in Makefiles of the form:

`unionai-docs-infra/Makefile.api.<api_name>`

To build it, run `make -f unionai-docs-infra/Makefile.api.<your_api>` and observe the setup
requirements in the `README.md` file above. Alternatively, `make update-api-docs` will regenerate all API docs.

## Package Resource Resolution

When scanning the packages we need to know when to include or exclude an object
(class, function, variable) from the documentation. The parser will follow this
workflow to decide, in order, if the resource must be in or out:

1. `__all__: List[str]` package-level variable is present: Only resources
   listed will be exposed. All other resources are excluded.

   Example:

   ```python
   from http import HTTPStatus, HTTPMethod

   __all__ = ["HTTPStatus", "LocalThingy"]

   class LocalThingy:
      ...

   class AnotherLocalThingy:
      ...
   ```

   In this example only `HTTPStatus` and `LocalThingy` will show in the docs.
   Both `HTTPMethod` and `AnotherLocalThingy` are ignored.

2. If `__all__` is not present, these rules are observed:

    - All imported packages are ignored
    - All objects starting with `_` are ignored

   Example:

   ```python
   from http import HTTPStatus, HTTPMethod

   class _LocalThingy:
      ...

   class AnotherLocalThingy:
      ...

   def _a_func():
      ...

   def b_func():
      ...
   ```

   In this example only `AnotherLocalThingy` and `b_func` will show in the docs.
   Neither none of the imports nor `_LocalThingy` will show in the documentation.

## Tips and Tricks

1. If you either have no resources without a `_` nor an `__all__` to
   export blocked resources (imports or starting with `_`, the package will have no content and thus will not be generated.

2. If you want to export something you `from ___ import ____` you _must_
   use `__all__` to add the private import to the public list.

3. If all your methods follow the Python convention of everything private starts
   with `_` and everything you want public does not, you do not need to have a
   `__all__` allow list.

## Enabling auto-linking for plugins

When you generate API documentation for a plugin, the build process creates two data files that enable automatic linking from documentation to API references:

- `data/{name}.yaml` - Hugo data file for server-side code block linking
- `static/{name}-linkmap.json` - JSON file for client-side inline code linking

For plugins, use the `--short-names` flag when generating API docs (already enabled in `Makefile.api.plugins`). This generates both fully qualified names (`flyteplugins.wandb.wandb_init`) and short names (`wandb_init`) in the linkmap, allowing docs to reference APIs without the full package path.

To enable auto-linking for a new plugin, you need to register these files in two places:

### 1. Server-side code block linking

Edit `unionai-docs-infra/layouts/partials/autolink-python.html` and add your plugin's data file to the merge chain:

```go-html-template
{{- /* Load and merge all API data sources */ -}}
{{- $flyteapi := dict "identifiers" (dict) "methods" (dict) "packages" (dict) -}}
{{- with site.Data.flytesdk -}}
    {{- $flyteapi = merge $flyteapi (dict "identifiers" (.identifiers | default dict) "methods" (.methods | default dict) "packages" (.packages | default dict)) -}}
{{- end -}}
{{- with site.Data.wandb -}}
    {{- $flyteapi = merge $flyteapi (dict "identifiers" (merge $flyteapi.identifiers (.identifiers | default dict)) "methods" (merge $flyteapi.methods (.methods | default dict)) "packages" (merge $flyteapi.packages (.packages | default dict))) -}}
{{- end -}}
{{- /* Add your plugin here following the same pattern */ -}}
```

### 2. Client-side inline code linking

Edit `static/js/inline-code-linker.js` and add your plugin's linkmap file to the `linkmapFiles` array:

```javascript
const linkmapFiles = ['flytesdk-linkmap.json', 'wandb-linkmap.json'];
// Add your plugin's linkmap file here, e.g., 'myplugin-linkmap.json'
```

### How auto-linking works

Once configured, the following will be automatically linked:

- **Code blocks**: Python code in fenced code blocks will have API references linked. For example, `wandb_init()` in a Python code block will link to its API documentation.

- **Inline code**: Inline code like `` `wandb_init()` `` will be linked. The `@` prefix for decorators and `()` suffix for functions are automatically stripped for matching.

The linkmap files contain mappings from identifiers to their API documentation URLs. Both short names (e.g., `wandb_init`) and fully qualified names (e.g., `flyteplugins.wandb.wandb_init`) are supported if included in the linkmap.


=== PAGE: https://www.union.ai/docs/v2/union/community/contributing-docs/llm-docs ===

# LLM-optimized documentation

The build pipeline generates LLM-optimized versions of every page and several index files,
designed for use by AI coding agents and AI search engines.

## Output files

The `make dist` command (specifically the `make llm-docs` step) produces the following
in each variant's `dist/docs/v2/{variant}/` directory:

| File | Description |
|------|-------------|
| `page.md` | Per-page LLM-optimized Markdown, generated alongside every `index.html`. Links between pages use relative `page.md` references, then are converted to absolute URLs in a final pass. |
| `section.md` | A single-file bundle concatenating all pages in a section. Only generated for sections with `llm_readable_bundle: true` in frontmatter. Internal links become hierarchical bold references; external links become absolute URLs. |
| `llms.txt` | Page index listing every page grouped by section, with H2/H3 headings for discoverability. Sections with bundles are marked with a "Section bundle" link. |
| `llms-full.txt` | The entire documentation for one variant as a single file, with all internal links converted to hierarchical bold references (e.g. `**Configure tasks > Resources**`). |

### Discovery hierarchy

```
dist/docs/llms.txt                          # Root: lists versions
dist/docs/v2/llms.txt                       # Version: lists variants
dist/docs/v2/{variant}/llms.txt             # Variant: page index with headings
dist/docs/v2/{variant}/llms-full.txt        # Full consolidated doc
dist/docs/v2/{variant}/**/page.md           # Per-page Markdown
dist/docs/v2/{variant}/**/section.md        # Section bundles (where enabled)
```

## How `page.md` files are generated

1. Hugo builds the site into `dist/` and also outputs a Markdown format into `tmp-md/`.
2. `process_shortcodes.py` reads from `tmp-md/`, resolves all shortcodes (variants, code includes, tabs, notes, etc.), and writes the result as `page.md` alongside each `index.html`.
3. `fix_internal_links_post_processing()` converts all internal links in `page.md` files to point to other `page.md` files using relative paths.
4. `build_llm_docs.py` then enhances subpage listings with H2/H3 headings, generates section bundles, converts all relative links to absolute URLs, and creates the `llms.txt` and `llms-full.txt` index files.

## Enabling section bundles

To produce a `section.md` bundle for a documentation section:

1. Add `llm_readable_bundle: true` to the frontmatter of the section's `_index.md`:

   ```yaml
   ---
   title: Configure tasks
   weight: 8
   variants: +flyte +union
   llm_readable_bundle: true
   ---
   ```

2. Add the `{{</* llm-bundle-note */>}}` shortcode in the body of the same `_index.md`,
   right after the page title:

   ```markdown
   # Configure tasks

   {{</* llm-bundle-note */>}}

   As we saw in ...
   ```

   This renders a note on the HTML page pointing readers to the `section.md` file.

Both the frontmatter parameter and the shortcode are required.
A CI check (`check-llm-bundle-notes`) verifies they are always in sync.

## The `llms-full.txt` link conversion

In `llms-full.txt`, all internal `page.md` links are converted to hierarchical bold references:

* Cross-page: `[Resources](../resources/page.md)` becomes `**Configure tasks > Resources**`
* Same-page anchor: `[Image building](#image-building)` becomes `**Container images > Image building**`
* External links (`http`/`https`) are preserved unchanged.

This makes the file self-contained with no broken references.

## Regenerating

LLM documentation is regenerated automatically as part of `make dist`.
To regenerate only the LLM files without a full rebuild:

```
make llm-docs
```

New pages are included automatically if linked via `## Subpages` in their parent's Hugo output.


=== PAGE: https://www.union.ai/docs/v2/union/community/contributing-docs/publishing ===

# Publishing

## Requirements

1. Hugo (https://gohugo.io/)

```bash
brew install hugo
```

2. A preferences override file with your configuration

The tool is flexible and has multiple knobs. Please review `unionai-docs-infra/hugo.local.toml~sample`, and configure to meet your preferences.

```bash
cp unionai-docs-infra/hugo.local.toml~sample hugo.local.toml
```

3. Make sure you review `hugo.local.toml`.

## Managing the Tutorial Pages

The tutorials are maintained in the [unionai/unionai-examples](https://github.com/unionai/unionai-examples) repository and is imported as a git submodule in the `unionai-examples`
directory.

To initialize the submodule on a fresh clone of this repository, run:

```
$ make init-examples
```

To update the submodule to the latest `main` branch, run:

```
$ make update-examples
```

## Building and running locally

```
$ make dev
```

## Developer Experience

This will launch the site in development mode.
The changes are hot reloaded: just change in your favorite editor and it will refresh immediately on the browser.

### Controlling Development Environment

You can change how the development environment works by settings values in `hugo.local.toml`. The following settings are available:

* `variant`          - The current variant to display. Change this in 'hugo.local.toml', save, and the browser will refresh automatically
                       with the new variant.
* `show_inactive`    - If 'true', it will show all the content that did not match the variant.
                       This is useful when the page contains multiple sections that vary with the selected variant,
                       so you can see all at once.
* `highlight_active` - If 'true', it will also highlight the *current* content for the variant.
* `highlight_keys`   - If 'true'', it highlights replacement keys and their values

### Changing 'variants'

Variants are flavors of the site (that you can change at the top).
During development, you can render any variant by setting it in `hugo.local.toml`:

```
variant = "byoc"
```

We call this the "active" variant.

You can also render variant content from other variants at the same time as well as highlighting the content of your active variant:

To show the content from variants other than the currently active one set:

```
show_inactive = true
```

To highlight the content of the currently active variant (to distinguish it from common content that applies to all variants), set:

```
highlight_active = true
```

> You can create your own copy of `hugo.local.toml` by copying from `unionai-docs-infra/hugo.local.toml~sample` to get started.

## Troubleshootting

### Identifying Problems: Missing Content

Content may be hidden due to `{{</* variant */>}}` blocks. To see what's missing,
you can adjust the variant show/hide in development mode.

For a production-like look set:

    show_inactive = false
    highlight_active = false

For a full-developer experience, set:

    show_inactive = true
    highlight_active = true

### Identifying Problems: Page Visibility

The developer site will show you in red any pages missing from the variant.
For a page to exist in the variant (or be excluded, you have to pick one), it must be listed in the `variants:` at the top of the file.
Clicking on the red page will give you the path you must add to the appropriate variant in the YAML file and a link with guidance.

Please refer to [Authoring](./authoring) for more details.

## Building Production

```
$ make dist
```

This will build all the variants and place the result in the `dist` folder.

### Testing Production Build

You can run a local web server and serve the `dist/` folder. The site must behave correctly, as it would be in its official URL.

To start a server:

```
$ make serve [PORT=<nnnnn>]
```

If specified without parameters, defaults to PORT=9000.

Example:

```
$ make serve PORT=4444
```

Then you open the browser on `http://localhost:<port>` to see the content. In the example above, it would be `http://localhost:4444/`


=== PAGE: https://www.union.ai/docs/v2/union/release-notes ===

# Release notes

## March 2026

### :wrench: Extended Idle Timeout for Panel Apps

Panel apps now support longer idle times for websocket connections, with session token expiration increased to 3 hours. New parameters for managing unused session lifetimes improve stability of long-running applications.

### :wrench: Plugin Variants Documentation

The new `--plugin-variants` flag in `flyte gen docs` generates variant-scoped CLI documentation. Plugin-contributed CLI commands are wrapped in Hugo `{{</* variant */>}}` shortcodes, so core commands appear unconditionally while plugin commands are shown only in specified variants (e.g., `byoc`, `selfmanaged`).

### :rocket: Google Gemini Plugin Integration

You can now integrate Google's Gemini API with Flyte using the new `function_tool` decorator to automatically convert Flyte tasks into Gemini agent tools. Both synchronous and asynchronous operations are supported.

```python
import flyte
from flyteplugins.gemini import function_tool, run_agent

env = flyte.TaskEnvironment("gemini-agent")

@env.task
async def get_weather(city: str) -> str:
    return f"The weather in {city} is sunny."

# Run Gemini agent with a tool
async def agent_task(prompt: str):
    tools = [function_tool(get_weather)]
    return await run_agent(prompt=prompt, tools=tools, model="gemini-2.5-flash")
```

### :hammer: Forced Image Build Caching

You can now force a rebuild of images by setting `force=True`, which skips the existence check and rebuilds even if the image already exists. When using the remote image builder, this also sets `overwrite_cache=True`.

```python
import flyte

image = flyte.Image("your_image")
result = await flyte.build.aio(image, force=True)
```

### :computer: LLM-Powered Code Generation

The new `flyteplugins-codegen` plugin generates code from natural language prompts, runs tests, and iterates in isolated sandboxes using LLMs.

```python
from flyteplugins.codegen import AutoCoderAgent

agent = AutoCoderAgent(model="gpt-4.1", name="data-processor", resources=flyte.Resources(cpu=1, memory="1Gi"))

result = await agent.generate.aio(
    prompt="Process the CSV data to calculate total revenue and units.",
    samples={"sales": csv_file},
    outputs={"total_revenue": float, "total_units": int},
)
```

### :wrench: Updated AI Plugin Examples

Fixed and improved plugin examples for working with OpenAI and Anthropic in Flyte 2.0, using updated versions of `flyteplugins-openai` and `flyteplugins-anthropic`.

```python
from flyteplugins.openai.agents import function_tool

agent_env = flyte.TaskEnvironment(
    "openai-agent",
    resources=flyte.Resources(cpu=1),
    secrets=[flyte.Secret(key="openai_api_key", as_env_var="OPENAI_API_KEY")],
)

@function_tool
@agent_env.task
async def get_bread() -> str:
    await asyncio.sleep(1)
    return "bread"
```

### :wrench: Debug Mode Integration

The Flyte SDK now supports a `--debug` flag to initiate tasks in VS Code debug mode from the CLI or Python interface. Specify `debug=True` in `flyte.with_runcontext` to attach a VS Code debugger during task execution.

```python
import flyte

env = flyte.TaskEnvironment(name="debug_example")

@env.task
def say_hello(name: str) -> str:
    greeting = f"Hello, {name}!"
    print(greeting)
    return greeting

if __name__ == "__main__":
    flyte.init_from_config()
    run = flyte.with_runcontext(debug=True).run(say_hello, name="World")
    print(run.name)
    print("Run url", run.url)
    print("Waiting for debug url...")
    print("Debug url", run.get_debug_url())
```

### :sparkles: Improved CLI Enum Support

The Flyte CLI now supports `EnumParamType`, allowing you to pass enum names directly (e.g., `--color=GREEN`) instead of requiring internal values.

### :memo: Programmatic Log Access

You can now access logs programmatically using the `get_logs()` method on `remote.Run` and `remote.Action`. This returns an iterator over log lines with support for asynchronous processing via `.aio()`, filtering system-generated logs, and including timestamps.

### :zap: Simplified PyTorch Example Setup

PyTorch environment setup is simplified: specify `flyteplugins-pytorch` directly via `with_pip_packages` instead of the internal `PythonWheels` API.

### :chart_with_upwards_trend: Distributed Training Evaluation

Flyte now supports distributed training with callback-driven evaluation. `EvalOnCheckpointCallback` automatically triggers evaluation tasks after each training checkpoint, running evaluations in parallel with training and monitoring convergence. Upon convergence, a stop signal gracefully halts training.

### :zap: Improved Benchmark Flexibility

The benchmark script for large I/O operations has been refactored. CPU and memory allocations are now parameterizable, file and directory tests can be run independently, and HTML report generation handles missing data gracefully.

### :computer: CLI Project Management

You can now create, update, and manage Flyte projects directly from the CLI, including setting IDs, names, descriptions, labels, and archive status.

```bash
# Example usage
flyte create project --id my_project_id --name "My Project" --description "Project description" -l team=dev -l env=prod
flyte update project my_project_id --archive
flyte get project --archived
```

### :robot: Anthropic Claude Integration

You can now integrate Flyte tasks as tools for Anthropic Claude agents. Define tasks in Flyte and convert them into Claude tool definitions using the `function_tool` utility.

### :hourglass_flowing_sand: Panel App Enhancements

The Flyte SDK panel app now uses a threaded asynchronous execution model, so actions like code execution no longer block the interface. Reo.Dev tracking integration provides monitoring capabilities.

### :gear: AWS Config File Support

Flyte now supports S3 authentication via the `AWS_CONFIG_FILE` environment variable. When both `AWS_PROFILE` and `AWS_CONFIG_FILE` are set, Flyte uses a boto3-backed credential provider for profile-based authentication.

### :sparkles: Improved Task Execution Reliability

Flyte now automatically uses `task.aio()` for both synchronous and asynchronous tasks, ensuring consistent execution through the Flyte controller. The previous fallback to `asyncio.to_thread()` for synchronous tasks has been removed.

### :wrench: Enhanced Action Service Integration

You can now attach custom gRPC headers when interacting with the Actions service, enabling consistent request metadata for routing and integration in distributed environments.

### :rocket: Async Training with Early Stopping

A new ML pattern example runs asynchronous training with periodic evaluations using Flyte's durable task management. The training task saves checkpoints asynchronously while evaluation tasks assess convergence, gracefully stopping training when convergence is detected.

```python
async def train(checkpoint_dir: str, total_epochs: int, seconds_per_epoch: float) -> File:
    # Training logic
    pass

async def evaluate(checkpoint_file: File, eval_round: int, convergence_loss: float) -> bool:
    # Evaluation logic
    pass

async def main(total_epochs, seconds_per_epoch, convergence_loss, eval_interval_seconds, max_eval_rounds):
    # Orchestration logic
    pass
```

Use `flyte run examples/ml/async_train_eval.py` to execute this pattern locally.

### :wrench: Improved Include Path Handling

Flyte now correctly resolves include paths relative to the app directory during deployment. Previously, include paths that escaped the app script's directory caused deployment failures due to invalid tar entries.

### :zap: Enhanced Retry Management

Task retries during local runs now support exponential backoff and detailed tracking of retry attempts, allowing recovery from transient errors. Retry visibility is improved in both the controller logic and the terminal UI.

### :zap: Improved Module Loading

The Flyte SDK's module loading now respects `.gitignore` and standard ignore rules, excluding directories like `.venv` and `__pycache__`.

### :zap: Dynamic Batching for Improved GPU Utilization

New `DynamicBatcher` and `TokenBatcher` classes allow concurrent tasks to share a single GPU, improving throughput for use cases like large-scale inference. An example demonstrates `TokenBatcher` for inference tasks with reusable containers.

### :sparkles: Run Cache Disabling

You can now disable run-level task result caching. When caching is disabled for a specific run, no cache hits are reported and cache operations are bypassed. The TUI reflects this with a clear indication that caching is disabled.

### :computer: Vim Key Navigation for TUI

The TUI (`FlyteTUIApp` and `ExploreTUIApp`) now supports Vim keys `j` and `k` for cursor movement in the `ActionTreeWidget` and `RunsTable`.

### :sparkles: Clickable Image Build URLs

Image URIs in TaskMetadata are now clickable in the Union frontend, linking directly to the Flyte run that built the image.

### :sparkles: Enhanced Run Filters

You can now filter runs and actions by project, domain, and creation/update time ranges. The new `TimeFilter` class supports filtering by `created_at` and `updated_at` timestamps, and filters are available through both the SDK and the CLI.

```python
from flyte.remote import TimeFilter

# Example usage to fetch runs created after a specific date
runs = Run.listall(
    project="my-project",
    created_at=TimeFilter(after="2026-03-01")
)
```

### :wrench: Simplified Dependency Management

`UVProject`'s `dependencies_only` mode now copies only the `pyproject.toml` files of each editable dependency instead of the entire directory, reducing build context size and speeding up image builds.

### :robot: MLE Agent Enhancements

Two new agents — the MLE Orchestrator Agent and the MLE Tool Builder Agent — use LLMs to automatically generate orchestration and processing code. They create, execute, and iteratively optimize ML models in an isolated sandbox environment with configurable computing resources.

### :sparkles: Improved Task Command Initialization

The Flyte CLI now initializes configuration when listing or resolving task commands via `TaskPerFileGroup`, preventing failures for config-dependent operations.

```python
import flyte
from flyte.io import File

env = flyte.TaskEnvironment(name="example_env")

@env.task
async def test_file(project: str, input_file: File) -> str:
    return f"Got input {project=}, {input_file=}"
```

### :zap: New Example Applications & Bug Fixes

New example applications added:

- Distributed training using async tasks
- MNIST model handling with PyTorch
- Agent workflows with LangGraph & Gemini API

Also includes a bug fix for scaling metric serialization.

### :gear: Phase Transitions Tracking

You can now view phase transition details for actions, showing time spent in each phase (QUEUED, INITIALIZING, RUNNING, etc.). Use the `get_phase_transitions` method and properties like `queued_time` and `running_time` to identify bottlenecks programmatically.

```python
action = Action.get(run_name="my-run", name="my-action")
details = action.details()
transitions = details.get_phase_transitions()
for t in transitions:
    print(f"{t.phase}: {t.duration.total_seconds()}s")
```

### :wrench: Multiple Source Files Support

`with_source_file` now accepts a list of file paths, allowing multiple files in a single image layer. An error is raised if duplicate filenames target the same location.

```python
from flyte._image import Image
from pathlib import Path

# Example usage with two different files
img = Image.from_debian_base(name="my-image").with_source_file([Path("a.py"), Path("b.py")])
```

### :package: Simplified Code Bundling

The new `with_code_bundle()` method packages source code into Docker images. When `copy_style` is set to `"none"` in `with_runcontext()` or during `flyte deploy`, source code is automatically baked into the image. Use `"loaded_modules"` to include specific Python modules or `"all"` for entire directories.

### :wrench: Improved Error Messaging for Deployment

When using a `src/` layout, the "Duplicate environment name" error during deployment now hints at the `--root-dir` option to help resolve dual-import issues.

```python
# New deployment configuration example
flyte deploy --dry-run --recursive --root-dir src src/my_module
```

### :wrench: Improved Debugging for Reusable Tasks

Reusable tasks now automatically disable debugging. Previously, debugging was enabled by default, which could cause issues with reusable tasks.

### :sparkles: JSONL Plugin Support

The new JSONL plugin adds `JsonlFile` and `JsonlDir` types for Flyte workflows. It supports async and sync read/write operations with optional `zstd` compression, using `orjson` for fast serialization.

```python
from flyteplugins.jsonl import JsonlFile, JsonlDir

# Example usage of JsonlFile
@env.task
async def process_file(f: JsonlFile):
    async for record in f.iter_records():
        print(record)

# Example usage of JsonlDir for sharded directories
@env.task
async def process_dir(d: JsonlDir):
    async for record in d.iter_records():
        print(record)
```

## February 2026

### :sparkles: JSON Schema Enhancement

Flyte now accurately converts Python types to JSON Schemas by leveraging Flyte's internal type system. Previously, certain types like `Literal["C", "F"]` were incorrectly mapped. Now, input schemas for Flyte tasks reflect precise JSON Schemas, improving integrations with tools like Anthropic's Claude.

```python
# Example: Converting Literal to JSON Schema correctly
def my_func(unit: Literal["C", "F"]) -> str:
    return unit

schema = NativeInterface.from_callable(my_func).json_schema
assert schema["properties"]["unit"] == {"type": "string", "enum": ["C", "F"]}
```

### :calculator: Panel Calculator Example

A new example showcases a calculator app embedded in a Panel interface using Flyte's `AppEnvironment`, demonstrating how to build interactive web-based UIs with Flyte.

### :sparkles: Spark Plugin Update

The `flyteplugins-spark` dependency has been updated to `>=2.0.0`, moving away from pre-release versions.

### :lock: Secure Package Specification

Package version constraints like `apache-airflow<=3.0.0` are now automatically quoted in generated Dockerfiles. Previously, unquoted constraints could cause incorrect shell interpretation and build failures.

### :zap: Enum Name Acceptance in CLI

The Flyte CLI now accepts enum names as valid inputs. Previously, only enum values were accepted, so `--color=RED` would fail when the value was `"red"`. Both names and values are now accepted.

```python
import enum
import flyte

class Color(enum.Enum):
    RED = "red"
    GREEN = "green"
    BLUE = "blue"

@flyte.task
def example_task(color: Color):
    return f"Selected color is {color.name}"
```

### :wrench: Enhanced Pod Template Handling

Pod templates are now properly maintained across task overrides. Previously, overriding certain task attributes could inadvertently discard custom pod templates. Pod specifications, labels, and annotations now persist even after renaming tasks or modifying other properties.

### :zap: Stress Testing Example Added

A new stress testing example demonstrates a fan-out execution pattern, creating a dynamic tree of asynchronous tasks to simulate high concurrency. You can control the number of tasks spawned at each layer and introduce variability with a jitter parameter.

### :bug: Correct Serialization Field

Fixed a bug in the serialization of scaling metrics: the correct field `target_value` is now used instead of `val`. This ensures proper serialization for `Scaling.Concurrency` and `Scaling.RequestRate` metrics as expected by the protobuf definitions.

### :wrench: Improved Async Task Handling

Async Flyte tasks now route execution through `task.aio()`, ensuring consistent invocation through Flyte's controller and correct handling of nested async tasks.

### :wrench: Sync Alignment of File Upload Methods

`File.from_local_sync` and `File.from_local` now handle filenames consistently when uploading to remote storage. Previously, the sync and async methods could produce different filenames for the same upload.

```python
# Example of uploading a file with consistent naming:
import flyte

with tempfile.TemporaryDirectory() as temp_dir:
    local_path = os.path.join(temp_dir, "source.txt")
    remote_path = os.path.join(temp_dir, "destination.txt")

    # Ensure the file content
    with open(local_path, "w") as f:
        f.write("sample content")

    # Upload the local file to a remote location
    uploaded_file = File.from_local_sync(local_path, remote_path)

    print(f"Uploaded file path: {uploaded_file.path}")
```

### :hourglass: Request Timeout Configuration

You can now configure request timeouts for Flyte applications using the new `Timeouts` dataclass. Set a `request` timeout (as an integer or `timedelta`) to limit the maximum duration a request can take within an application environment.

### :wrench: Enhanced Bundling and Error Handling

Flyte now ignores `.git` directories in deployment code bundles, reducing artifact size and improving deployment speed. Additionally, explicit error handling for the `copy_style` parameter provides clear guidance when bundling is unnecessary.

### :wrench: Dynamic Pydantic Model Creation

The new `PydanticTransformer.guess_python_type` method dynamically creates Pydantic models from JSON schema metadata. This handles cases where the original Pydantic model class isn't available, enabling flexible deserialization of complex nested structures.

### :busts_in_silhouette: Human-in-the-Loop Plugin

The new Human-in-the-Loop (HITL) plugin enables workflows to pause and wait for human input via a web interface or programmatically. Create events that prompt for human interaction through an auto-served FastAPI app.

```python
import flyteplugins.hitl as hitl

# Create event and wait for human input
event = await hitl.new_event.aio(
    "input_event",
    data_type=int,
    scope="run",
    prompt="Enter a number"
)
value = await event.wait.aio()
```

### :rocket: Stateless Code Sandbox

Flyte now supports running arbitrary Python code and shell commands in an isolated, stateless Docker container with the `flyte.sandbox.create()` API. Three execution modes are available: Auto-IO, Verbatim, and Command, each handling inputs and outputs differently while running code in fresh, ephemeral containers.

### :wrench: Improved CLI Logging Initialization

The Flyte SDK now ensures a consistent logging setup when using the CLI. Previously, CLI commands would initialize configuration multiple times, leading to duplicated log entries. Now:

- Initialization occurs once per command execution.
- `RichHandler` is enabled from the start, so all logs display in rich format.
- The `hello.py` example script now has a default value, so it runs without arguments.

```python
@env.task
def main(x_list: list[int] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]) -> float:
    x_len = len(x_list)
    if x_len < 10:
        raise ValueError(f"x_list doesn't have a larger enough sample size, found: {x_len}")
    y_list = list(flyte.map(fn, x_list))
    y_mean = sum(y_list) / len(y_list)
    return y_mean
```

### :wrench: Enhanced Ignore Handling

Flyte SDK now skips processing of `.gitignore` and `.flyteignore` files inside commonly ignored directories such as `.venv` or `__pycache__`, avoiding redundant file processing.

### :whale: CI Image Builder

A new example script automates Docker image building and pushing from CI. Configure it with your source and target image details to integrate with continuous deployment pipelines.

### :wrench: TypedDict Compatibility Fix

The Flyte SDK now correctly handles `TypedDict` for Python versions earlier than 3.12 by using `typing_extensions.TypedDict`.

```python
# Importing TypedDict based on Python version
import sys
if sys.version_info >= (3, 12):
    from typing import TypedDict
else:
    from typing_extensions import TypedDict
```

### :globe_with_meridians: Cross-Platform Code Bundling

The Flyte SDK now uses POSIX-style paths for file hashing and tarball creation, ensuring consistent code bundling behavior across Windows and Unix systems.

### :wrench: Improved CLI JSON Formatting

The `flyte` CLI now uses the `to_dict()` method when available for JSON output, fixing `TypeError` failures that occurred with certain non-iterable object types.

### :wrench: Improved Pod Image Handling

Flyte now consistently merges container images when using a pod template. The primary container uses `app_env.image` if no explicit image is set, with correct handling of both `"auto"` and specific image values.

### :sparkles: Flyte Webhook Environment

A pre-built Flyte webhook environment makes it easier to integrate with FastAPI endpoints for common Flyte operations like running tasks, managing apps, and handling triggers. This update uses `httpx` for HTTP requests and expands endpoint exports for better customization.

### :repeat: Retry Interceptor for gRPC

A new retry interceptor for gRPC channels allows you to define how many times a gRPC call should be retried on transient failures. Specify the number of retry attempts using the `rpc_retries` option during channel creation.

### :sparkles: Orchestration Sandbox Feature

Flyte 2.0 now supports dynamic orchestration within a sandbox using `flyte.sandbox.orchestrator_from_str()`. Create reusable orchestration templates directly from Python code strings without defining decorated functions — useful when code is dynamically generated from UIs or language models.

### :wrench: Task Shortname Override Fix

You can now override the shortname for tasks in the UI by setting the `short_name` parameter in task overrides. Previously, overridden shortnames were not reflected in the Flyte UI.

### :sparkles: NVIDIA H100 GPU Support

Flyte now supports NVIDIA H100 GPUs with various MIG partitions for fine-grained resource allocation.

```python
from flyte import GPU, Resources

h100_mig_env = flyte.TaskEnvironment(
    name="h100_mig",
    resources=Resources(
        cpu="1",
        memory="4Gi",
        gpu=GPU(device="H100", quantity=1, partition="1g.10gb"),
    ),
)
```

### :zap: Enhanced Error Handling in PyTorch Elastic Jobs

Flyte's PyTorch integration now includes configurable NCCL timeout settings to better manage CUDA out-of-memory (OOM) situations. This prevents elastic jobs from hanging due to OOM by introducing faster failure detection and customizable restart policies. You can reduce timeout durations, enable asynchronous error handling, and activate built-in monitoring.

### :wrench: Reverse Path Priority Fix

The Flyte SDK's handling of `sys.path` when running tasks remotely now respects local path priority. Previously, the `entrypoint` directory could override top-level packages. This fix ensures consistent path prioritization between local development and remote execution.

### :globe_with_meridians: S3 Virtual Hosted-Style Support

You can now specify the addressing style for S3-compatible backends by setting the `FLYTE_AWS_S3_ADDRESSING_STYLE` environment variable to `virtual`. This constructs URLs in the format `https://<bucket>.<endpoint>/<key>`, enabling compatibility with more storage providers.

## November 2025

### :fast_forward: Grouped Runs
We redesigned the Runs page to better support large numbers of runs. Historically, large projects produced so many runs that flat listings became difficult to navigate. The new design groups Runs by their root task - leveraging the fact that while there may be millions of runs, there are typically only dozens or hundreds of deployed tasks. This grouped view, combined with enhanced filtering (by status, owner, duration, and more coming soon), makes it dramatically faster and easier to locate the exact runs users are looking for, even in the largest deployments.

![Grouped Runs View](https://raw.githubusercontent.com/unionai/unionai-docs-static/main/images/release-notes/2025-11_grouped_runs.gif)

### :globe_with_meridians: Apps (beta)

You can now deploy apps in Union 2.0. Apps let you host ML models, Streamlit dashboards, FastAPI services, and other interactive applications alongside your workflows. Simply define your app, deploy it, and Union will handle the infrastructure, routing, and lifecycle management. You can even call apps from your tasks to build end-to-end workflows that combine batch processing with real-time serving.

To create an app, import `flyte` and use either `FastAPIAppEnvironment` for FastAPI applications or the generic `AppEnvironment` for other frameworks. Here's a simple FastAPI example:

```python
from fastapi import FastAPI
import flyte
from flyte.app.extras import FastAPIAppEnvironment

app = FastAPI()
env = FastAPIAppEnvironment(
    name="my-api",
    app=app,
    image=flyte.Image.from_debian_base(python_version=(3, 12))
        .with_pip_packages("fastapi", "uvicorn"),
    resources=flyte.Resources(cpu=1, memory="512Mi"),
    requires_auth=False,
)

@env.app.get("/greeting/{name}")
async def greeting(name: str) -> str:
    return f"Hello, {name}!"

if __name__ == "__main__":
    flyte.init_from_config()
    flyte.deploy(env) # Deploy and serve your app
```

For Streamlit apps, use the generic `AppEnvironment` with a command:

```python
app_env = flyte.app.AppEnvironment(
    name="streamlit-hello-v2",
    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages("streamlit==1.41.1"),
    command="streamlit hello --server.port 8080",
    resources=flyte.Resources(cpu="1", memory="1Gi"),
)
```

You can call apps from tasks by using `depends_on` and making HTTP requests to the app's endpoint. Please refer to the example in the [SDK repo](https://github.com/flyteorg/flyte-sdk/blob/main/examples/apps/call_apps_in_tasks/app.py). Similarly, you can call apps from other apps (see this [example](https://github.com/flyteorg/flyte-sdk/blob/main/examples/apps/app_calling_app/app.py)).

### :label: Custom context

You can now pass configuration and metadata implicitly through your entire task execution hierarchy using custom context. This is ideal for cross-cutting concerns like tracing IDs, experiment metadata, environment information, or logging correlation keys—data that needs to be available everywhere but isn't logically part of your task's computation.

Custom context is a string key-value map that automatically flows from parent to child tasks without adding parameters to every function signature. Set it once at the run level with `with_runcontext()`, or override values within tasks using the `flyte.custom_context()` context manager:

```python
import flyte

env = flyte.TaskEnvironment("custom-context-example")

@env.task
async def leaf_task() -> str:
    # Reads run-level context
    print("leaf sees:", flyte.ctx().custom_context)
    return flyte.ctx().custom_context.get("trace_id")

@env.task
async def root() -> str:
    return await leaf_task()

if __name__ == "__main__":
    flyte.init_from_config()
    # Base context for the entire run
    run = flyte.with_runcontext(custom_context={"trace_id": "root-abc", "experiment": "v1"}).run(root)
    print(run.url)
```

### :lock: Secrets UI

Now you can view and create secrets directly from the UI. Secrets are stored securely in your configured secrets manager and injected into your task environments at runtime.

![Secrets Creation Flow](https://raw.githubusercontent.com/unionai/unionai-docs-static/main/images/release-notes/2025-11_secrets_creation.gif)

### Image builds now run in the same project-domain
The image build task is now executed within the same project and domain as the user task, rather than in system-production. This change improves isolation and is a key step toward supporting multi-dataplane clusters.

### Support for secret mounts in Poetry and UV projects
We added support for mounting secrets into both Poetry and UV-based projects. This enables secure access to private dependencies or credentials during image build.

```python
import pathlib

import flyte

env = flyte.TaskEnvironment(
    name="uv_project_lib",
    resources=flyte.Resources(memory="1000Mi"),
    image=(
        flyte.Image.from_debian_base().with_uv_project(
            pyproject_file=pathlib.Path(__file__).parent / "pyproject.toml",
            pre=True,
            secret_mounts="my_secret",
        )
    ),
)
```

## October 2025

### :infinity: Larger fanouts
You can now run up to 50,000 actions within a run and up to 1,000 actions concurrently.
To enable observability across so many actions, we added group and sub-actions UI views, which show summary statistics about the actions which were spawned within a group or action.
You can use these summary views (as well as the action status filter) to spot check long-running or failed actions.

![50k Fanout Visualization](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/release-notes/2025-10_50k_fanout.gif)

### :computer: Remote debugging for Ray head nodes
Rather than locally reproducing errors, sometimes you just want to zoom into the remote execution and see what's happening.
We directly enable this with the debug button.
When you click "Debug action" from an action in a run, we spin up that action's environment, code, and input data, and attach a live VS Code debugger.
Previously, this was only possible with vanilla Python tasks.
Now, you can debug multi-node distributed computations on Ray directly.

![Debugging Ray Head Node](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/release-notes/2025-10_ray_head_debug.gif)

### :zap: Triggers and audit history
**Configure tasks > Triggers** let you templatize and set schedules for your workflows, similar to Launch Plans in Flyte 1.0.

```python
@env.task(triggers=flyte.Trigger.hourly())  # Every hour
def example_task(trigger_time: datetime, x: int = 1) -> str:
    return f"Task executed at {trigger_time.isoformat()} with x={x}"
```

Once you deploy, it's possible to see all the triggers which are associated with a task:

![Triggers for a Task](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/release-notes/2025-10_triggers_for_task.png)

We also maintain an audit history of every deploy, activation, and deactivation event, so you can get a sense of who's touched an automation.

![Triggers Activity Log](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/release-notes/2025-10_trigger_activity_log.gif)

### :arrow_up: Deployed tasks and input passing

You can see the runs, task spec, and triggers associated with any deployed task, and launch it from the UI. We've converted the launch forms to a convenient JSON Schema syntax, so you can easily copy-paste the inputs from a previous run into a new run for any task.

![Deployed Tasks and Input Passing](https://raw.githubusercontent.com/unionai/unionai-docs-static/refs/heads/main/images/release-notes/2025-10_tasks_and_input_passing.gif)


=== PAGE: https://www.union.ai/docs/v2/union/deployment ===

# Platform deployment

The Union.ai platform uses a split-plane model with separate control and data planes.

In both BYOC and Self-managed deployments, your code, input and output data, container images and logs reside entirely on the **data plane**, which runs in your cloud account, while the **control plane** runs on Union.ai's cloud account, providing the workflow orchestration logic.

The **control plane** does not have access to the code, data, images, or logs in the **data plane**.

If you choose a **Self-managed deployment**, your data isolation is further enhanced by the fact that you manage your data plane entirely on your own, without providing any access to Union.ai customer support.

If you choose a **BYOC deployment**, Union.ai manages the Kubernetes cluster in your data plane for you. The data isolation of the control vs. data plane is still enforced - for example, Union.ai has no access to your object storage or logs. However, Union.ai customer support will have some access to your cluster, though strictly for upgrades, provisioning, and other actions related to maintaining cluster health.

## BYOC deployment

The BYOC deployment offers a fully "serverless in your cloud", turnkey solution where all infrastructure management is offloaded to Union.ai:

* The **data plane** resides in your cloud provider account but is managed by Union.ai, who will handle deployment, monitoring, Kubernetes upgrades, and all other operational aspects of the platform. BYOC deployment supports data planes on Amazon Web Services (AWS), Google Cloud Platform (GCP), and Microsoft Azure.

* The **control plane**, as with all Union.ai deployment options, resides in the Union.ai AWS account and is administered by Union.ai. However, as mentioned, data separation is maintained between the data plane and the control plane, with no control plane access to the code, input/output, images or logs in the data plane.

## Self-managed deployment

The Self-managed deployment allows you to manage the data plane yourself on cloud infrastructure that you control and maintain:

* The **data plane** resides in your cloud provider account and is managed by you. Your team will handle deployment, monitoring, Kubernetes upgrades, and all other operational aspects of the platform. You do not need to provide any permissions to the Union.ai system to create a data plane. Self-managed deployment supports data planes on Amazon Web Services (AWS), Google Cloud Platform (GCP), Microsoft Azure and Oracle Compute Infrastructure (OCI).

* The **control plane**, as with all Union.ai deployment options, resides in the Union.ai Amazon Web Services (AWS) account and is administered by Union.ai. However, as mentioned, data separation is maintained between the data plane and the control plane, with no control plane access to the code, input/output, images or logs in the data plane.

## Data plane

The data plane runs in your cloud account and VPC. It is composed of the required services to run and monitor workflows:

* Kubernetes cluster
* Object storage bucket
* Container image registry
* Secrets manager
* Logging solution
* IAM role with proper access

When you run your workflow:

1. Your code is sent to the object storage bucket
2. Container images are built on a builder node and pushed to the registry
3. Pods are created and assume the IAM role
4. Container images are pulled down from the registry for each pod as needed
5. Containers load their inputs from, and save their outputs to, the object store

All of this happens in the data plane, with the control plane aware only of the workflow execution state, and not the code, data, logs, secrets, or any other proprietary information. The data plane communicates with the control plane through an outgoing port through a zero trust proxy. There is no open incoming port to the data plane.

## Control plane

Union.ai operates the control plane in its own cloud infrastructure in Amazon Web Services (AWS).
The control plane has access to:

* Workflow execution state information
* Names of tasks and other deployed entities
* Pointers to object storage locations in the data plane (but not any user data)
* Union.ai IDP

## Subpages
- **BYOC deployment**
- **Self-managed deployment**
- **Managing Union with Terraform**


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc ===

# BYOC deployment

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

In a BYOC (Bring Your Own Cloud) deployment, Union.ai manages the data plane infrastructure in your cloud account.
You provide the cloud account and network configuration; Union.ai handles Kubernetes cluster operations, upgrades, and monitoring.

Your code, data, container images, and logs remain entirely in your data plane.
The Union.ai control plane orchestrates workflow execution but has no access to your proprietary data.

## Getting started

1. Review the **BYOC deployment > Platform architecture** to understand the control plane and data plane split.
2. Set up your data plane on your cloud provider:
   - **BYOC deployment > Data plane setup on AWS**
   - **BYOC deployment > Data plane setup on Azure**
   - **BYOC deployment > Data plane setup on GCP**
3. **BYOC deployment > Configuring your data plane** with your specific requirements (regions, node groups, networking).

## Cloud resource integration

Connect your data plane to cloud-native services:

- [AWS resources](./enabling-aws-resources/_index) (S3, ECR, Secrets Manager)
- [Azure resources](./enabling-azure-resources/_index) (Blob Storage, Container Registry, Key Vault)
- [GCP resources](./enabling-gcp-resources/_index) (Cloud Storage, Artifact Registry, BigQuery)

## Additional configuration

- [Single sign-on setup](./single-sign-on-setup/_index) for OAuth2/OIDC-based authentication
- **BYOC deployment > Multi-cluster and multi-cloud** for domain and project isolation
- **BYOC deployment > Data retention policy** for controlling stored data lifecycle

## Subpages
- **BYOC deployment > Platform architecture**
- **BYOC deployment > Configuring your data plane**
- **BYOC deployment > Multi-cluster and multi-cloud**
- **BYOC deployment > Data plane setup on AWS**
- **BYOC deployment > Data plane setup on GCP**
- **BYOC deployment > Data plane setup on Azure**
- **BYOC deployment > Data retention policy**
- **BYOC deployment > Enabling AWS resources**
- **BYOC deployment > Enabling GCP resources**
- **BYOC deployment > Enabling Azure resources**
- **BYOC deployment > Single sign on setup**


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/platform-architecture ===

# Platform architecture

The Union.ai architecture consists of two virtual private clouds, referred to as planes—the control plane and the data plane.

![](../../_static/images/user-guide/platform-architecture/union-architecture.png)

## Control plane

The control plane:
  * Runs within the Union.ai AWS account.
  * Provides the user interface through which users can access authentication, authorization, observation, and management functions.
  * Is responsible for placing executions onto data plane clusters and performing other cluster control and management functions.

## Data plane

All your workflow and task executions are performed in the data plane, which runs within your AWS or GCP account. The data plane's clusters are provisioned and managed by the control plane through a resident Union operator with minimal required permissions.

Union.ai operates one control plane for each supported region, which supports all data planes within that region. You can choose the region in which to locate your data plane. Currently, Union.ai supports the `us-west`, `us-east`, `eu-west`, and `eu-central` regions, and more are being added.

### Data plane nodes

Once the data plane is deployed in your AWS or GCP account, there are different kinds of nodes with different responsibilities running in your cluster. In Union.ai, we distinguish between default nodes and worker nodes.

Default nodes guarantee the basic operation of the data plane and are always running. Example services that run on these nodes include autoscaling (worker nodes), monitoring services, union operator, and many more.

Worker nodes are responsible for executing your workloads. You have full control over the configuration of your [worker nodes](./configuring-your-data-plane#worker-node-groups).

When worker nodes are not in use, they automatically scale down to the configured minimum. (The default is zero.)

## Union.ai operator

The Union.ai hybrid architecture lets you maintain ultimate ownership and control of your data and compute infrastructure while enabling Union.ai to handle the details of managing that infrastructure.

Management of the data plane is mediated by a dedicated operator (the Union.ai operator) resident on that plane.
This operator is designed to perform its functions with only the very minimum set of required permissions.
It allows the control plane to spin up and down clusters and provides Union.ai's support engineers with access to system-level logs and the ability to apply changes as per customer requests.
It _does not_ provide direct access to secrets or data.

In addition, communication is always initiated by the Union.ai operator in the data plane toward the Union.ai control plane, not the other way around.
This further enhances the security of your data plane.

Union.ai is SOC-2 Type 2 certified. A copy of the audit report is available upon request.

## Registry data

Registry data is composed of:

* Names of workflows, tasks, launch plans, and artifacts
* Input and output types for workflows and tasks
* Execution status, start time, end time, and duration of workflows and tasks
* Version information for workflows, tasks, launchplans, and artifacts
* Artifact definitions

This type of data is stored in the control plane and is used to manage the execution of your workflows.
This does not include any workflow or task code, nor any data that is processed by your workflows or tasks.

## Execution data

Execution data is composed of::

* Event data
* Workflow inputs
* Workflow outputs
* Data passed between tasks (task inputs and outputs)

This data is divided into two categories: *raw data* and *literal data*.

### Raw data

Raw data is composed of:

* Files and directories
* Dataframes
* Models
* Python-pickled types

These are passed by reference between tasks and are always stored in an object store in your data plane.
This type of data is read by (and may be temporarily cached) by the control plane as needed, but is never stored there.

### Literal data

* Primitive execution inputs (int, string... etc.)
* JSON-serializable dataclasses

These are passed by value, not by reference, and may be stored in the Union.ai control plane.

## Data privacy

If you are concerned with maintaining strict data privacy, be sure not to pass private information in literal form between tasks.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/configuring-your-data-plane ===

# Configuring your data plane

After you set up your data plane account(s), the next step is to specify the infrastructure you want to deploy.
You will need to send the following details to the Union.ai team:

* Which **BYOC deployment > Configuring your data plane > Cloud provider** will you use?
* Will this be a **BYOC deployment > Configuring your data plane > Multi-cluster** setup?
    * If so, how will Flyte domains and/or Flyte projects be mapped to clusters?
    * Additionally, how will clusters be grouped into cluster pools? (Each cluster pool will have its own metadata bucket)
* For each cluster:
    * **BYOC deployment > Configuring your data plane > Account ID** for this cluster (each cluster must be in its own account on your cloud provider)
    * **BYOC deployment > Configuring your data plane > Region** in which the cluster will be deployed.
    * **BYOC deployment > Configuring your data plane > VPC** setup (will you use your own VPC or have Union.ai provision one for you?)
    * **BYOC deployment > Configuring your data plane > Data retention policy** for workflow execution data stored in this cloud provider account.
    * For each **BYOC deployment > Configuring your data plane > Worker node groups > Node group name**:
        * **BYOC deployment > Configuring your data plane > Worker node groups > Node type**
        * **BYOC deployment > Configuring your data plane > Worker node groups > Minimum**
        * **BYOC deployment > Configuring your data plane > Worker node groups > Maximum**
        * **BYOC deployment > Configuring your data plane > Worker node groups > Interruptible instances**
        * **BYOC deployment > Configuring your data plane > Worker node groups > Taints**
        * **BYOC deployment > Configuring your data plane > Worker node groups > Disk**

## Cloud provider

You can choose AWS, Azure, or GCP as your cloud provider.
If you choose to have multiple clusters, they must all be in the same provider.

## Multi-cluster

You can choose a single or multi-cluster configuration.

In a multi-cluster configuration, you have separate clusters for each of your Flyte domains and/or Flyte projects.

A cluster in this context refers to a distinct EKS (in AWS), AKS (in Azure), or GKE (in GCP) instance in its own AWS account, Azure subscription, or GCP project.

The most common set up is to have a separate cluster for each Flyte domain: development, staging, and production.

You can further partition your deployment so that each Flyte domain-project pair has its own cluster in its own account.

In addition, clusters are grouped into cluster pools. Each cluster pool will have its own metadata bucket. You can group your clusters into pools based on your own criteria, for example, by region or by the type of workloads that will run on them.

See [Multi-cluster](./multi-cluster) for more information.

## Account ID

Provide the ID of the AWS account, Azure subscription, or GCP project in which each cluster will reside.

## Region

For each cluster, specify the region. Available regions are `us-west`, `us-east`, `eu-west`, and `eu-central`.

## VPC

Specify whether you want to set up your own VPC or use one provided by Union.ai.
If you are provisioning your own VPC, provide the VPC ID.

## Data retention policy

Each cluster has its own internal object store that is used to store data used in the execution of workflows.
This includes task input-output metadata, task input-output raw data, Flyte Decks data, and fast registration data.
For each cluster, you can choose to enable a data retention policy that defines a maximum time for this data to be stored, after which it will be automatically deleted.
Alternatively, you can set this to `unlimited` to disable automatic data deletion.
See [Data retention policy](./data-retention-policy) for more details.

## Worker node groups

Specify the worker node groups (in AWS) or worker node pools (in Azure and GCP) that you wish to have, with the following details for each. For more information about worker nodes, see [Platform architecture](./platform-architecture).

### Node group name

The name of the node group. This will be used as the node group name in the EKS, AKS, or GKE console.

### Node type

The instance type name, for example, `p3d.4xlarge`. (See [AWS instance types](https://aws.amazon.com/ec2/instance-types), [Azure VM sizes](https://learn.microsoft.com/en-us/azure/virtual-machines/sizes), or [GCP machine types](https://cloud.google.com/compute/docs/machine-types) for more information. Also see **BYOC deployment > Configuring your data plane > Resources held back** below.)

### Minimum

The minimum node number. The default is `0`.

Setting a minimum of `0` means that an execution may take longer to schedule since a node may have to spun up.
If you want to ensure that at least node is always available, set the minimum to `1`.

Note however, that a setting of `1` will only help the `0` to `1` spin-up issue.
It will not help in the case where you have `1` node available but need `2`, and so forth.
Ultimately, the minimum should be determined by the workload pattern that you expect.

### Maximum

The maximum node number. This setting must be explicitly set to a value greater than `0`.

### Interruptible instances

> [!NOTE]
> In AWS, the term *spot instance* is used.
> In Azure, the equivalent term is *spot VM*.
> In GCP, the equivalent term is *spot VM*.
> Here we use the term *interruptible instance* generically for all providers.

Specify whether this will be an **interruptible instance** or an **on-demand instance** node group.

Note that for each interruptible node group, an identical on-demand group will be configured as a fallback.
This fallback group will be identical in all respects to the interruptible group (instance type, taints, disk size, etc.), apart from being on-demand instead of interruptible.
The fallback group will be used when the retries on the interruptible group have been exhausted.

For more information on interruptible instances, see the interruptible instances documentation.

### Taints

Specify whether this node group will be a specialized node group reserved for specific tasks (typically with specialized hardware requirements).

If so, it will be configured with a *taint* so that only tasks configured with a *toleration* for that taint will be able to run on it.

Typically, only GPU node groups fall into this specialized category, and they will always be assigned taints in any case. It is not common to place taints on other types of node groups, but you can do so if you wish.

<!-- TODO ADD: For more detail on how taints and tolerations work see [Taints and tolerations](). -->

### Disk

Specify the disk size for the nodes in GiB. The default is `500 GiB`.

## Resources held back

When specifying node types and other resource parameters, you should keep in mind that the nominally quoted amount of a given resource is not always available to Flyte tasks.
For example, in an node instance rated at `16GiB`, some of that is held back for overhead and will not be available to Flyte task processes.

## Example specification
Values provided by you are in single quotes (').

```yaml
- Cloud provider: 'AWS'
- Multi-cluster: 'True'
    - Mapping: 'domain -> cluster'
- Clusters:
    - 'development'
        - Account ID: 'account-id-1'
        - Region: 'us-west'
        - VPC: 'vpc-id-1'
        - Data retention policy: '30 days'
        - Node groups:
            - 'node-group-1'
                - Node type: 'p3d.4xlarge'
                - Min: '2'
                - Max: '5'
                - Spot: 'True'
                - Taints: 'False'
                - Disk: '1500 GiB'
            - 'node-group2'
                - Node type: 't4.24xlarge'
                - Min: '2'
                - Max: '5'
                - Spot: 'True'
                - Taints: 'False'
                - Disk: '1500 GiB'
    - 'staging'
        - Account ID: 'account-id-2'
        - Region: 'us-west'
        - VPC: 'vpc-id-2'
        - Data retention policy: '30 days'
        - Node groups:
            - 'node-group-1'
                - Node type: 'p3d.4xlarge'
                - Min: '2'
                - Max: '5'
                - Spot: 'True'
                - Taints: 'False'
                - Disk: '1500 GiB'
            - 'node-group-2'
                - Node type: 't4.24xlarge'
                - Min: '2'
                - Max: '5'
                - Spot: 'True'
                - Taints: 'False'
                - Disk: '1500 GiB'
    - 'production'
        - Account ID: 'account-id-3'
        - Region: 'us-west'
        - VPC: 'vpc-id-3'
        - Data retention policy: 'unlimited'
        - Node groups:
            - 'node-group-1'
                - Node type: 'p3d.4xlarge'
                - Min: '2'
                - Max: '5'
                - Spot: 'False'
                - Taints: 'False'
                - Disk: '1500 GiB'
            - 'node-group-2'
                - Node type: 't4.24xlarge'
                - Min: '2'
                - Max: '5'
                - Spot: 'False'
                - Taints: 'False'
                - Disk: '1500 GiB'
```

## After deployment

Once Union.ai has configured and deployed your cluster(s), you will be able to see your data plane setup in **Usage > Compute**.

## Adjusting your configuration

To make changes to your cluster configuration, go to the [Union.ai Support Portal](https://support.union.ai).
This portal also accessible from **Usage > Compute** through the **Adjust Configuration** button.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/multi-cluster ===

# Multi-cluster and multi-cloud

When [configuring your data plane](./configuring-your-data-plane), you can map each domain or project to its own GCP project or AWS subaccount. You can even mix cloud providers: Some of your domains and/or projects can be mapped to AWS subaccounts while others can be mapped to GCP projects.

## Domain isolation

If you choose domain isolation, then you would have one GCP project or AWS subaccount for each domain. For example:

| Domain        | GCP project or AWS subaccount     |
| ------------- | --------------------------------- |
| `development` | `gcp-project-union-development`   |
| `staging`     | `gcp-project-union-staging`       |
| `production`  | `aws-subaccount-union-production` |

## Project isolation

If you choose project isolation, then you would have one GCP project or AWS subaccount for each Union.ai project-domain pair. For example:

| Domain/Project          | GCP Project or AWS Subaccount               |
| ----------------------- | ------------------------------------------- |
| `development/project-1` | `gcp-project-union-development-project-1`   |
| `development/project-2` | `gcp-project-union-development-project-2`   |
| `development/project-3` | `gcp-project-union-development-project-3`   |
| `staging/project-1`     | `gcp-project-union-staging-project-1`       |
| `staging/project-2`     | `gcp-project-union-staging-project-1`       |
| `staging/project-3`     | `gcp-project-union-staging-project-1`       |
| `production/project-1`  | `aws-subaccount-union-production-project-1` |
| `production/project-2`  | `aws-subaccount-union-production-project-1` |
| `production/project-3`  | `aws-subaccount-union-production-project-1` |

The precise set of GCP projects and/or AWS subaccounts depends on the number of Union.ai domains and projects that you have.

> [!NOTE] Limitations of project per GCP project/AWS subaccount
> Note that if you choose to map each Union.ai project to its own GCP project/AWS subaccount,
> you will need to define the set of such projects up front. This is because the Union.ai project will have to be
> created when the GCP project/AWS subaccount is set up.
>
> If you also want the ability to create projects on demand, this can be supported by having an additional
> _default_ GCP project/AWS subaccount. Any projects created _after_ onboarding will be created in that
> default GCP project/AWS subaccount.

## Data and metadata isolation

Each domain or project is isolated within its own AWS account or Google project, and therefore provides the level of compute and data isolation intrinsic to that arrangement. Specifically, execution-time isolation per domain or project is maintained for both compute and user data stored in blob store (or other configured storage).

In addition, metadata specific to the internals of Union.ai can be either isolated or shared across clusters, depending on the configuration you choose.

Specifically, the sharing of metadata is controlled by the cluster pool to which a cluster belongs. If two clusters are in the same cluster pool, then they _must_ share the same metadata bucket. If they are in different cluster pools, then they _must_ have different metadata buckets. You could, for example, have a single metadata bucket for all your development clusters, and a separate one for all your production clusters, by grouping the clusters into cluster pools accordingly. Alternatively you could have a separate metadata bucket for each cluster, by putting each cluster in its own cluster pool.

You specify the cluster pool to which a cluster belongs when you [configure your data plane](./configuring-your-data-plane) with the help of the Union.ai team.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/data-plane-setup-on-aws ===

# Data plane setup on AWS

To set up your data plane on Amazon Web Services (AWS) you must allow Union.ai to provision and maintain compute resources under your AWS account.
You will need to set up an IAM role for Union.ai to use that has sufficient permissions to do this provisioning.
Setting the permissions can be done either through CloudFormation or the AWS console.

Additionally, if you wish to manage your own Virtual Private Cloud (VPC) then you will need to set up the VPC according to the guidelines described below.
If you do not wish to manage your own VPC then no additional configuration is needed.

## Setting permissions through CloudFormation

You can do the setup quickly using AWS CloudFormation.

### Click the Launch Stack button

Ensure that you are logged into the desired AWS account and then select the appropriate region and launch the corresponding CloudFormation stack:

| Region         | Launch Stack                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `us-east-1`    | [![Launch AWS CloudFormation Stack](../../_static/images/deployment/data-plane-setup-on-aws/cloudformation-launch-stack.png)](https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/quickcreate?templateURL=https%3A%2F%2Funion-public.s3.amazonaws.com%2Ftemplates%2Fv0.13%2Funion-ai-admin-role.template.yaml&stackName=UnionCloudAccess&param_CrossAccountRoleName=union-ai-admin)       |
| `us-east-2`    | [![Launch AWS CloudFormation Stack](../../_static/images/deployment/data-plane-setup-on-aws/cloudformation-launch-stack.png)](https://us-east-2.console.aws.amazon.com/cloudformation/home?region=us-east-2#/stacks/quickcreate?templateURL=https%3A%2F%2Funion-public.s3.amazonaws.com%2Ftemplates%2Fv0.13%2Funion-ai-admin-role.template.yaml&stackName=UnionCloudAccess&param_CrossAccountRoleName=union-ai-admin)       |
| `us-west-2`    | [![Launch AWS CloudFormation Stack](../../_static/images/deployment/data-plane-setup-on-aws/cloudformation-launch-stack.png)](https://us-west-2.console.aws.amazon.com/cloudformation/home?region=us-west-2#/stacks/quickcreate?templateURL=https%3A%2F%2Funion-public.s3.amazonaws.com%2Ftemplates%2Fv0.13%2Funion-ai-admin-role.template.yaml&stackName=UnionCloudAccess&param_CrossAccountRoleName=union-ai-admin)       |
| `eu-west-1`    | [![Launch AWS CloudFormation Stack](../../_static/images/deployment/data-plane-setup-on-aws/cloudformation-launch-stack.png)](https://eu-west-1.console.aws.amazon.com/cloudformation/home?region=eu-west-1#/stacks/quickcreate?templateURL=https%3A%2F%2Funion-public.s3.amazonaws.com%2Ftemplates%2Fv0.13%2Funion-ai-admin-role.template.yaml&stackName=UnionCloudAccess&param_CrossAccountRoleName=union-ai-admin)       |
| `eu-west-2`    | [![Launch AWS CloudFormation Stack](../../_static/images/deployment/data-plane-setup-on-aws/cloudformation-launch-stack.png)](https://eu-west-2.console.aws.amazon.com/cloudformation/home?region=eu-west-2#/stacks/quickcreate?templateURL=https%3A%2F%2Funion-public.s3.amazonaws.com%2Ftemplates%2Fv0.13%2Funion-ai-admin-role.template.yaml&stackName=UnionCloudAccess&param_CrossAccountRoleName=union-ai-admin)       |
| `eu-central-1` | [![Launch AWS CloudFormation Stack](../../_static/images/deployment/data-plane-setup-on-aws/cloudformation-launch-stack.png)](https://eu-central-1.console.aws.amazon.com/cloudformation/home?region=eu-central-1#/stacks/quickcreate?templateURL=https%3A%2F%2Funion-public.s3.amazonaws.com%2Ftemplates%2Fv0.13%2Funion-ai-admin-role.template.yaml&stackName=UnionCloudAccess&param_CrossAccountRoleName=union-ai-admin) |

> [!NOTE] CloudFormation template
> All of these buttons launch the same CloudFormation template, just in different regions.
> The CloudFormation template itself is available at this URL:
>
> [https://union-public.s3.amazonaws.com/templates/v0.13/union-ai-admin-role.template.yaml](https://union-public.s3.amazonaws.com/templates/v0.13/union-ai-admin-role.template.yaml)
>
> For details on the functionality enabled by each of the permissions,
> see the [release notes](https://github.com/unionai/union-cloud-infrastructure/releases).

### Confirm the details

Once you have selected **Launch Stack**, you will be taken to the CloudFormation interface. Do the following:

1. Check the profile name in the top right corner to confirm that you are in the correct account.
2. Leave the default values in place:
   - `UnionCloudAccess` for the **Stack Name**.
   - `union-ai-admin` for **Cross Account Role Name**.
3. Enter the `external ID` provided by Union.ai team for **ExternalId**  
4. Select the checkbox indicating that you acknowledge that AWS CloudFormation may create IAM resources with custom names.
5. Select **Create Stack**.

### Share the role ARN

Once the above steps are completed, you will need to get the ARN of the newly created role (`union-ai-admin`) and send it to the Union.ai team:

1. In the navigation pane of the IAM console, choose **Roles**.
1. In the list of roles, choose the `union-ai-admin` role.
1. In the **Summary** section of the details pane, copy the **role ARN** value.
1. Share the ARN with the Union.ai team.
1. The Union.ai team will get back to you to verify that they are able to assume the role.

### Updating permissions through CloudFormation

From time to time Union.ai may need to update the `union-ai-admin` role to support new or improved functionality.

If you used CloudFormation to set up your stack in the first place, you will have to perform the update by replacing your CloudFormation template with a new one.

When an update is required:

- The Union.ai team will inform you that you need to perform the update.
- The URL of the template will be published above, in the **CloudFormation template** info box. This is always kept up to date with the latest template.

To perform the update on your system, copy the template URL and follow the directions here:

### Update your CloudFormation template

1. Log in to the AWS web console and navigate to **CloudFormation** for the region within which your data plane is deployed.
2. Select the `UnionCloudAccess` stack.
3. Select **Stack Actions > Create change set for current stack**.
4. Select **Replace current template**.
5. Input the new CloudFormation template URL provided to you by the Union.ai team (and published above in the **Current template** info box).
6. Select **Next**.
7. On the **Specify stack details** page, accept the defaults and select **Next**.
8. On the **Configure stack options** page, accept the defaults and select **Next**.
9. On the **Review UnionCloudAccess** page, accept the acknowledgment at the bottom of the page and select **Submit**.
10. Wait for the changeset to be generated by AWS (refresh the page if necessary).
11. Select **Execute change set**.

## Setting permissions manually

If you want to perform the setup manually, instead of using the CloudFormation method described above, do the following.

### Prepare the policy documents

First, copy the policy document `UnionIAMPolicy.json` below to an editor and replace`${AWS::Region}` with the correct region and `${AWS::AccountID}` with your account ID.

You will use this policy in a later step.

```json
{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Action":[
            "logs:ListTagsLogGroup",
            "logs:TagLogGroup",
            "logs:UntagLogGroup",
            "logs:DescribeLogGroups",
            "rds:DescribeDBSubnetGroups",
            "logs:DeleteLogGroup",
            "eks:CreateNodegroup",
            "eks:UpdateNodegroupConfig",
            "rds:CreateDBSubnetGroup",
            "logs:CreateLogGroup",
            "ec2:AllocateAddress",
            "eks:DeleteCluster",
            "rds:DeleteDBSubnetGroup",
            "kms:CreateAlias",
            "eks:DescribeCluster",
            "logs:PutRetentionPolicy",
            "kms:DeleteAlias"
         ],
         "Resource":[
            "arn:aws:kms:${AWS::Region}:${AWS::AccountID}:alias/*",
            "arn:aws:rds:${AWS::Region}:${AWS::AccountID}:subgrp:*",
            "arn:aws:ec2:${AWS::Region}:${AWS::AccountID}:elastic-ip/*",
            "arn:aws:eks:${AWS::Region}:${AWS::AccountID}:cluster/opta-*",
            "arn:aws:logs:${AWS::Region}:${AWS::AccountID}:log-group:opta-*",
            "arn:aws:logs:${AWS::Region}:${AWS::AccountID}:log-group::log-stream*",
            "arn:aws:logs:${AWS::Region}:${AWS::AccountID}:log-group:/aws/eks/opta-*:*"
         ],
         "Effect":"Allow",
         "Sid":"0"
      },
      {
         "Action":[
            "sqs:CreateQueue",
            "sqs:DeleteQueue",
            "sqs:SetQueueAttributes",
            "sqs:TagQueue",
            "sqs:UntagQueue"
         ],
         "Resource":[
            "arn:aws:sqs:${AWS::Region}:${AWS::AccountID}:Karpenter*"
         ],
         "Effect":"Allow"
      },
      {
         "Action":[
            "events:DescribeRule",
            "events:DeleteRule",
            "events:ListTargetsByRule",
            "events:PutRule",
            "events:PutTargets",
            "events:RemoveTargets",
            "events:TagResource"
         ],
         "Resource":[
            "arn:aws:events:${AWS::Region}:${AWS::AccountID}:rule/Karpenter*"
         ],
         "Effect":"Allow"
      },
      {
         "Action":[
            "eks:TagResource",
            "eks:UntagResource",
            "eks:ListTagsForResource",
            "eks:CreateAccessEntry",
            "eks:DescribeAccessEntry",
            "eks:UpdateAccessEntry",
            "eks:DeleteAccessEntry"
         ],
         "Resource":[
            "arn:aws:eks:${AWS::Region}:${AWS::AccountID}:cluster/opta-*"
         ],
         "Effect":"Allow",
         "Sid":"112"
      },
      {
         "Action":[
            "kms:EnableKeyRotation",
            "kms:PutKeyPolicy",
            "kms:GetKeyPolicy",
            "ec2:AttachInternetGateway",
            "kms:ListResourceTags",
            "kms:TagResource",
            "kms:UntagResource",
            "ec2:DetachInternetGateway",
            "eks:DescribeNodegroup",
            "kms:GetKeyRotationStatus",
            "eks:DeleteNodegroup",
            "ec2:CreateInternetGateway",
            "kms:ScheduleKeyDeletion",
            "kms:CreateAlias",
            "kms:DescribeKey",
            "ec2:DeleteInternetGateway",
            "kms:DeleteAlias",
            "kms:CreateGrant"
         ],
         "Resource":[
            "arn:aws:eks:${AWS::Region}:${AWS::AccountID}:nodegroup/*",
            "arn:aws:ec2:${AWS::Region}:${AWS::AccountID}:internet-gateway/*",
            "arn:aws:kms:${AWS::Region}:${AWS::AccountID}:key/*"
         ],
         "Effect":"Allow",
         "Sid":"1"
      },
      {
         "Action":[
            "ec2:CreateNatGateway",
            "ec2:DeleteNatGateway"
         ],
         "Resource":[
            "arn:aws:ec2:${AWS::Region}:${AWS::AccountID}:natgateway/*"
         ],
         "Effect":"Allow",
         "Sid":"2"
      },
      {
         "Action":[
            "ec2:CreateRoute",
            "ec2:DeleteRoute",
            "ec2:CreateRouteTable",
            "ec2:DeleteRouteTable",
            "ec2:AssociateRouteTable"
         ],
         "Resource":[
            "arn:aws:ec2:${AWS::Region}:${AWS::AccountID}:route-table/*",
            "arn:aws:ec2:${AWS::Region}:${AWS::AccountID}:subnet/subnet-*"
         ],
         "Effect":"Allow",
         "Sid":"3"
      },
      {
         "Action":[
            "ec2:AuthorizeSecurityGroupEgress",
            "ec2:AuthorizeSecurityGroupIngress"
         ],
         "Resource":[
            "arn:aws:ec2:${AWS::Region}:${AWS::AccountID}:security-group-rule/*"
         ],
         "Effect":"Allow",
         "Sid":"4"
      },
      {
         "Action":[
            "ec2:RevokeSecurityGroupIngress",
            "ec2:AuthorizeSecurityGroupEgress",
            "ec2:AuthorizeSecurityGroupIngress",
            "ec2:CreateSecurityGroup",
            "ec2:RevokeSecurityGroupEgress",
            "ec2:DeleteSecurityGroup"
         ],
         "Resource":[
            "arn:aws:ec2:${AWS::Region}:${AWS::AccountID}:security-group/*",
            "arn:aws:ec2:${AWS::Region}:${AWS::AccountID}:vpc/vpc-*"
         ],
         "Effect":"Allow",
         "Sid":"5"
      },
      {
         "Action":[
            "ec2:DeleteSubnet",
            "ec2:CreateNatGateway",
            "ec2:CreateSubnet",
            "ec2:ModifySubnetAttribute"
         ],
         "Resource":[
            "arn:aws:ec2:${AWS::Region}:${AWS::AccountID}:subnet/*"
         ],
         "Effect":"Allow",
         "Sid":"6"
      },
      {
         "Action":[
            "ec2:CreateNatGateway"
         ],
         "Resource":[
            "arn:aws:ec2:${AWS::Region}:${AWS::AccountID}:elastic-ip/eipalloc-*"
         ],
         "Effect":"Allow",
         "Sid":"7"
      },
      {
         "Action":[
            "ec2:DeleteFlowLogs",
            "ec2:CreateFlowLogs"
         ],
         "Resource":[
            "arn:aws:ec2:${AWS::Region}:${AWS::AccountID}:vpc-flow-log/*",
            "arn:aws:ec2:${AWS::Region}:${AWS::AccountID}:vpc/vpc*"
         ],
         "Effect":"Allow",
         "Sid":"8"
      },
      {
         "Action":[
            "ec2:CreateVpc",
            "ec2:CreateRouteTable",
            "ec2:AttachInternetGateway",
            "ec2:ModifyVpcAttribute",
            "ec2:DetachInternetGateway",
            "ec2:DeleteVpc",
            "ec2:CreateSubnet",
            "ec2:DescribeVpcAttribute",
            "ec2:AssociateVpcCidrBlock"
         ],
         "Resource":[
            "arn:aws:ec2:${AWS::Region}:${AWS::AccountID}:vpc/*"
         ],
         "Effect":"Allow",
         "Sid":"VisualEditor8"
      },
      {
         "Action":[
            "iam:DeleteOpenIDConnectProvider",
            "iam:GetOpenIDConnectProvider",
            "iam:CreateOpenIDConnectProvider",
            "iam:TagOpenIDConnectProvider",
            "iam:UntagOpenIDConnectProvider",
            "iam:ListOpenIDConnectProviderTags"
         ],
         "Resource":[
            "arn:aws:iam::${AWS::AccountID}:oidc-provider/*"
         ],
         "Effect":"Allow",
         "Sid":"VisualEditor9"
      },
      {
         "Action":[
            "iam:CreatePolicy",
            "iam:CreatePolicyVersion",
            "iam:DeletePolicyVersion",
            "iam:GetPolicyVersion",
            "iam:GetPolicy",
            "iam:ListPolicyVersions",
            "iam:DeletePolicy",
            "iam:ListPolicyTags",
            "iam:TagPolicy",
            "iam:UntagPolicy"
         ],
         "Resource":[
            "arn:aws:iam::${AWS::AccountID}:policy/*"
         ],
         "Effect":"Allow",
         "Sid":"VisualEditor10"
      },
      {
         "Action":[
            "iam:GetRole",
            "iam:TagRole",
            "iam:UntagRole",
            "iam:ListRoleTags",
            "iam:CreateRole",
            "iam:DeleteRole",
            "iam:AttachRolePolicy",
            "iam:PutRolePolicy",
            "iam:ListInstanceProfilesForRole",
            "iam:PassRole",
            "iam:CreateServiceLinkedRole",
            "iam:DetachRolePolicy",
            "iam:ListAttachedRolePolicies",
            "iam:DeleteRolePolicy",
            "iam:ListRolePolicies",
            "iam:GetRolePolicy"
         ],
         "Resource":[
            "arn:aws:iam::${AWS::AccountID}:role/*"
         ],
         "Effect":"Allow",
         "Sid":"VisualEditor111"
      },
      {
         "Action":[
            "ec2:DescribeAddresses",
            "ec2:EnableEbsEncryptionByDefault",
            "ec2:GetEbsEncryptionByDefault",
            "ec2:DescribeFlowLogs",
            "ec2:ResetEbsDefaultKmsKeyId",
            "ec2:DescribeInternetGateways",
            "ec2:DescribeNetworkInterfaces",
            "ec2:DescribeAvailabilityZones",
            "ec2:GetEbsDefaultKmsKeyId",
            "ec2:DescribeAccountAttributes",
            "kms:CreateKey",
            "ec2:DescribeNetworkAcls",
            "ec2:DescribeRouteTables",
            "ec2:ModifyEbsDefaultKmsKeyId",
            "eks:CreateCluster",
            "eks:UpdateClusterVersion",
            "eks:UpdateClusterConfig",
            "ec2:ReleaseAddress",
            "rds:AddTagsToResource",
            "rds:RemoveTagsFromResource",
            "rds:ListTagsForResource",
            "ec2:DescribeVpcClassicLinkDnsSupport",
            "ec2:CreateTags",
            "ec2:DescribeNatGateways",
            "ec2:DisassociateRouteTable",
            "ec2:DescribeSecurityGroups",
            "ec2:DescribeVpcClassicLink",
            "ec2:DescribeVpcs",
            "kms:ListAliases",
            "ec2:DisableEbsEncryptionByDefault",
            "sts:GetCallerIdentity",
            "ec2:DescribeSubnets",
            "ec2:DescribeSecurityGroupRules",
            "ec2:AllocateAddress",
            "ec2:AssociateAddress",
            "ec2:DisassociateAddress",
            "ec2:DescribeInstanceTypeOfferings",
            "logs:DescribeLogStreams",
            "iam:ListRoles",
            "iam:ListPolicies",
            "ec2:DescribeInstanceTypes",
            "servicequotas:GetServiceQuota",
            "cloudwatch:GetMetricStatistics"
         ],
         "Resource":"*",
         "Effect":"Allow",
         "Sid":"VisualEditor12"
      },
      {
         "Action":"dynamodb:*",
         "Resource":[
            "arn:aws:dynamodb:${AWS::Region}:${AWS::AccountID}:table/opta-*"
         ],
         "Effect":"Allow",
         "Sid":"VisualEditor13"
      },
      {
         "Action":"s3:*",
         "Resource":[
            "arn:aws:s3:::opta-*",
            "arn:aws:s3:::opta-*/",
            "arn:aws:s3:::union-*",
            "arn:aws:s3:::union-*/"
         ],
         "Effect":"Allow",
         "Sid":"VisualEditor14"
      },
      {
         "Action":[
            "events:DescribeRule",
            "events:ListTargetsByRule",
            "events:ListTagsForResource",
            "events:UntagResource"
         ],
         "Resource":[
            "arn:aws:events:${AWS::Region}:${AWS::AccountID}:rule/Karpenter*"
         ],
         "Effect":"Allow"
      },
      {
         "Action":[
            "sqs:GetQueueAttributes",
            "sqs:ListQueueTags"
         ],
         "Resource":[
            "arn:aws:sqs:${AWS::Region}:${AWS::AccountID}:Karpenter*"
         ],
         "Effect":"Allow"
      },
      {
         "Action":[
            "elasticache:CreateCacheSubnetGroup",
            "elasticache:AddTagsToResource",
            "elasticache:RemoveTagsFromResource",
            "elasticache:ListTagsForResource",
            "elasticache:DescribeCacheSubnetGroups",
            "elasticache:DeleteCacheSubnetGroup"
         ],
         "Resource":[
            "arn:aws:elasticache:${AWS::Region}:${AWS::AccountID}:subnetgroup:opta-*"
         ],
         "Effect":"Allow",
         "Sid":"ElastiCache"
      },
      {
         "Action":[
            "iam:CreateInstanceProfile",
            "iam:AddRoleToInstanceProfile",
            "iam:RemoveRoleFromInstanceProfile",
            "iam:DeleteInstanceProfile",
            "iam:TagInstanceProfile",
            "iam:UntagInstanceProfile",
            "iam:ListInstanceProfileTags",
            "iam:GetInstanceProfile",
            "iam:UpdateAssumeRolePolicy"
         ],
         "Resource":[
            "arn:aws:iam::${AWS::AccountID}:instance-profile/*"
         ],
         "Effect":"Allow",
         "Sid":"self0"
      },
      {
         "Action":[
            "ec2:RunInstances",
            "ec2:CreateTags",
            "ec2:DescribeTags",
            "ec2:DeleteTags",
            "ec2:DescribeImages",
            "ec2:CreateLaunchTemplate",
            "ec2:CreateLaunchTemplateVersion",
            "ec2:DescribeLaunchTemplates",
            "ec2:DescribeLaunchTemplateVersions",
            "ec2:DeleteLaunchTemplate",
            "ec2:DeleteLaunchTemplateVersions",
            "ec2:ModifyLaunchTemplate"
         ],
         "Resource":"*",
         "Effect":"Allow",
         "Sid":"self1"
      },
      {
         "Action":[
            "autoscaling:CreateAutoScalingGroup",
            "autoscaling:DeleteAutoScalingGroup",
            "autoscaling:DescribeAutoScalingGroups",
            "autoscaling:UpdateAutoScalingGroup",
            "autoscaling:CreateLaunchConfiguration",
            "autoscaling:SetInstanceProtection",
            "autoscaling:DescribeScalingActivities",
            "autoscaling:CreateOrUpdateTags",
            "autoscaling:DescribeTags",
            "autoscaling:DeleteTags"
         ],
         "Resource":"*",
         "Effect":"Allow",
         "Sid":"self2"
      },
      {
         "Action":[
            "eks:UpdateNodegroupConfig",
            "eks:ListNodegroups",
            "eks:UpdateNodegroupVersion",
            "eks:TagResource",
            "eks:UntagResource",
            "eks:ListTagsForResource",
            "eks:DescribeUpdate",
            "eks:DeleteNodegroup"
         ],
         "Resource":[
            "arn:aws:eks:${AWS::Region}:${AWS::AccountID}:nodegroup/opta-*/opta-*/*",
            "arn:aws:eks:${AWS::Region}:${AWS::AccountID}:nodegroup/opta-*",
            "arn:aws:eks:${AWS::Region}:${AWS::AccountID}:nodegroup/*",
            "arn:aws:eks:${AWS::Region}:${AWS::AccountID}:cluster/opta-*",
            "arn:aws:eks:${AWS::Region}:${AWS::AccountID}:addon/opta-*/*/*"
         ],
         "Effect":"Allow",
         "Sid":"AllowUpdateNodegroupConfig"
      },
      {
         "Action":[
            "eks:CreateAddon",
            "eks:UpdateAddon",
            "eks:DeleteAddon",
            "eks:DescribeAddonVersions",
            "eks:DescribeAddon",
            "eks:ListAddons"
         ],
         "Resource":[
            "arn:aws:eks:${AWS::Region}:${AWS::AccountID}:cluster/opta-*",
            "arn:aws:eks:${AWS::Region}:${AWS::AccountID}:addon/opta-*/*/*"
         ],
         "Effect":"Allow",
         "Sid":"AllowUpdateEKSAddonConfig"
      },
      {
         "Action":[
            "ec2:CreateVpcEndpoint",
            "ec2:ModifyVpcEndpoint",
            "ec2:DeleteVpcEndpoints"
         ],
         "Resource":[
            "arn:aws:ec2:${AWS::Region}:${AWS::AccountID}:vpc/vpc*",
            "arn:aws:ec2:${AWS::Region}:${AWS::AccountID}:vpc-endpoint/*",
            "arn:aws:ec2:${AWS::Region}:${AWS::AccountID}:route-table/*",
            "arn:aws:ec2:${AWS::Region}:${AWS::AccountID}:subnet/*",
            "arn:aws:ec2:${AWS::Region}:${AWS::AccountID}:security-group/*"
         ],
         "Effect":"Allow",
         "Sid":"AllowVpcEndpoints"
      },
      {
         "Action":[
            "ec2:DescribeVpcEndpoints",
            "ec2:DescribePrefixLists"
         ],
         "Resource":"*",
         "Effect":"Allow",
         "Sid":"AllowVpcEndpointReadPermissions"
      },
      {
         "Action":[
            "ecr:CreateRepository",
            "ecr:DeleteRepository",
            "ecr:TagResource",
            "ecr:UntagResource",
            "ecr:PutLifecyclePolicy",
            "ecr:DeleteLifecyclePolicy",
            "ecr:PutImageTagMutability",
            "ecr:PutImageScanningConfiguration",
            "ecr:BatchDeleteImage",
            "ecr:DeleteRepositoryPolicy",
            "ecr:SetRepositoryPolicy",
            "ecr:GetRepositoryPolicy",
            "ecr:PutReplicationConfiguration",
            "ecr:DescribeRepositories",
            "ecr:ListTagsForResource",
            "ecr:GetLifecyclePolicy",
            "ecr:GetRepositoryPolicy",
            "ecr:DescribeImages"
         ],
         "Resource":[
            "arn:aws:ecr:*:${AWS::AccountID}:repository/union/*"
         ],
         "Effect":"Allow",
         "Sid":"UnionImageBuilderRepoAdmin"
      },
      {
         "Action":[
            "ecr:GetAuthorizationToken"
         ],
         "Resource":"*",
         "Effect":"Allow",
         "Sid":"UnionAdminAuthToken"
      }
   ]
}
```

### Create the role manually

Next, you must create the role. Follow the directions here:

1. Sign in to the **AWS Management Console** as an administrator of your account, and open the **IAM console**.
2. Choose **Roles** and then select **Create role**.
3. Under **Select trusted entity**, choose **AWS account**.
4. Under **An AWS account**, select **Another AWS account**.
5. In the **Account ID** field, enter the Union.ai account ID: `479331373192`.
6. Under **Options,** you will see two items: **Require external ID** and **Require MFA**. At this point in the process, you can leave these unchecked.
7. Select **Next**. This will take you to the **Add permissions** page.
8. Select **Next**. We will setup permissions in a later step.
9. Enter the role name `union-ai-admin`.
10. (Optional) For **Description**, enter a description for the new role.
11. (Optional) Under **Tags**, add tags as key-value pairs. For more information about using tags in IAM, see[ Tagging IAM resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html).
12. After reviewing the role, choose **Create role**.
13. Search for the `union-ai-admin` role in the IAM Roles list and click on it.
14. Click **Add permissions** and select **Create inline policy** from the drop down menu.
15. On the Create policy screen, click the **JSON** tab.
16. Replace the contents of the policy editor with the **UnionIAMPolicy.json** file that you edited earlier.
17. Click **Review policy**.
18. Name the policy **UnionIAMPolicyManual** and click **Create policy**.

### Share the role ARN

Now you must obtain the Amazon Resource Name (ARN) of the role, a unique identifier for the role:

1. In the navigation pane of the IAM console, choose **Roles**.
2. In the list of roles, choose the `union-ai-admin` role.
3. In the **Summary** section of the details pane, copy the **role ARN** value.

Share the ARN with the Union.ai team.
The Union.ai team will get back to you to verify that they are able to assume the role.

### Updating permissions manually

From time to time Union.ai may need to update the `union-ai-admin` role to support new or improved functionality.
If you set up your role manually in the first place (as opposed to using CloudFormation), you will have to perform the update manually as well.
follow the directions here:

1. Sign in to the **AWS Management Console** as an administrator of your account, and open the **IAM console**.
2. Choose **Roles**
3. Search for the `union-ai-admin` role in the IAM Roles list and click on it.
4. Under **Permissions policies**, select the previously created policy (if you followed the above directions, it should be called **UnionIAMPolicyManual**).
5. The next screen will display the JSON for current policy.
6. Replace the current policy JSON with the updated copy of **UnionIAMPolicy.json** and click **Next**.
7. On the next page, review the new policy and click **Save changes**.

## Setting up and managing your own VPC (optional)

If you decide to manage your own VPC, instead of leaving it to Union.ai, then you will need to set it up yourself.
The VPC should be configured with the following characteristics.

- **Multiple availability zones**:
  - We recommend a minimum of 3.
- **A sufficiently large CIDR range**:
  - We recommend a /16 for the VPC, /28 for each public subnet, and /18 for each private subnet.
  - With most CNIs, a safe assumption is one IP allocated per pod. Small subnets can limit the number of pods that can be spun up when projects scale.
- **A public subnet** with:
  - An internet gateway configured for internet access.
- **A private subnet** with:
  - A NAT gateway setup for internet access.
- Enable **(Recommended) VPC Endpoints** to mitigate unnecessary NAT gateway network traffic:
  - Enable [S3 VPC gateway endpoint with appropriate route table association](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-s3.html).
  - Enable [VPC interface endpoints](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html) for the following services `com.amazonaws.<REGION>.logs`, `com.amazonaws.<REGION>.ecr.dkr`, `com.amazonaws.<REGION>.ec2`
    - Ensure the service names include the region that contains the aforementioned availability zones.
    - Ensure the subnet IDs are configured to include all the aforementioned availability zones.
    - Ensure the security groups allow all traffic from within the VPC.
    - Enable [Private DNS](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-s3.html#private-dns-s3) to support out of the box compatibility with data plane services.

Once your VPC is set up, you will need to provide the Union.ai team with the following information:

- **VPC ID**
  - Example: `vpc-8580ec61d96caf837`
- **Public subnet IDs** (one per availability zone)
  - Example: `subnet-d7d3ce57d1a546401`
- **Private subnet IDs** (one per availability zone)
  - Example: `subnet-bc2eafd5c11180be0`

## Private EKS endpoint

The requirements described so far, enable Union to operate with a `Public` or `Public and Private` EKS endpoint. 

To deploy the Union operator in your EKS cluster and to perform troubleshooting at the Kubernetes layer, Union requires access to the [EKS endpoint](https://docs.aws.amazon.com/eks/latest/userguide/cluster-endpoint.html). 

> This connection is not used for executions, only for cluster onboarding, upgrades and support.

For additional security, the EKS endpoint can be configured as `Private` only. In such case, Union implements a VPC Endpoint connection over [Private Link](https://docs.aws.amazon.com/vpc/latest/userguide/endpoint-services-overview.html), a lightweight yet robust mechanism to ensure management traffic doesn't leave the AWS network.

When AWS rolls out changes to the EKS endpoint, its IP address might change. To handle this and prevent any disconnect, the Union automation sets up a "jumper" ECS container in the customer account which forwards the incoming requests to the EKS Endpoint, acting as a reverse proxy, while a Network Load Balancer exposes an stable endpoint address. In this way, you get the security of a fully private connection and a reliable channel for Union staff to manage your cluster proactively or troubleshoot issues when needed.

![](../../_static/images/deployment/data-plane-setup-on-aws/aws_private_link_architecture.png)

For this setup, there are additional requirements you'll need to complete in your AWS account:

### Create additional roles for ECS

#### ECS Task Execution role
- **Role name**: `unionai-access-<REGION>-ecs-execution-role` 
- **Attached policy**: `AmazonECSTaskExecutionRolePolicy` (built-in policy)
- **Trust Relationship**:
```json
 {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "ecs-tasks.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```

#### ECS Task Definition role
- **Role name**: `unionai-access-<REGION>-ecs-task-role`  
- **Attached policy**:

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowSSMMessageChannels",
            "Effect": "Allow",
            "Action": [
                "ssmmessages:OpenDataChannel",
                "ssmmessages:OpenControlChannel",
                "ssmmessages:CreateDataChannel",
                "ssmmessages:CreateControlChannel"
            ],
            "Resource": "*"
        },
        {
            "Sid": "UpdateInstanceInfo",
            "Effect": "Allow",
            "Action": "ssm:UpdateInstanceInformation",
            "Resource": "*"
        }
    ]
}
```
- **Trust Relationship**:
```json
 {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "ecs-tasks.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```
### Attach a new IAM policy to the Union role

Add the following permissions as a new IAM policy attached to the `union-ai-admin` role (described in the **BYOC deployment > Data plane setup on AWS > Setting permissions manually > Prepare the policy documents** section) , replacing `REGION` and `ACCOUNT_ID` to match your environment:

```json
{
    "Statement": [
        {
            "Action": [
                "iam:GetRole"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:iam::<<ACCOUNT_ID>>:role/unionai-access-<<REGION>>-ecs-execution-role",
                "arn:aws:iam::<<ACCOUNT_ID>>:role/unionai-access-<<REGION>>-ecs-task-role"
            ],
            "Sid": "ECSTaskRoles"
        },
        {
            "Action": [
                "application-autoscaling:DescribeScalableTargets",
                "application-autoscaling:DescribeScalingActivities",
                "application-autoscaling:DescribeScalingPolicies",
                "cloudwatch:GetMetricData",
                "cloudwatch:GetMetricStatistics",
                "cloudwatch:ListMetrics",
                "ec2:DescribeNetworkInterfaces",
                "ec2:DescribeSecurityGroups",
                "ec2:DescribeSubnets",
                "ec2:DescribeVpcAttribute",
                "ec2:DescribeVpcEndpoints",
                "ec2:DescribeVpcEndpointConnections",
                "ec2:DescribeVpcEndpointServiceConfigurations",
                "ec2:DescribeVpcs",
                "ec2:DescribeInstances",
                "ec2:DescribeInstanceStatus",
                "ec2:GetConsoleOutput",
                "ecs:DeregisterTaskDefinition",
                "ecs:DescribeContainerInstances",
                "ecs:DescribeServiceDeployments",
                "ecs:DescribeServices",
                "ecs:DescribeTaskDefinition",
                "ecs:DescribeTasks",
                "ecs:GetTaskProtection",
                "ecs:ListClusters",
                "ecs:ListServices",
                "ecs:ListTaskDefinitionFamilies",
                "ecs:ListTaskDefinitions",
                "ecs:ListTasks",
                "eks:DescribeClusterVersions",
                "elasticloadbalancing:DescribeListeners",
                "elasticloadbalancing:DescribeLoadBalancerAttributes",
                "elasticloadbalancing:DescribeLoadBalancers",
                "elasticloadbalancing:DescribeTags",
                "elasticloadbalancing:DescribeTargetGroupAttributes",
                "elasticloadbalancing:DescribeTargetGroups",
                "elasticloadbalancing:DescribeTargetHealth",
                "logs:DescribeLogGroups",
                "servicediscovery:ListNamespaces",
                "iam:SimulatePrincipalPolicy",
                "ssm:StartSession"
            ],
            "Effect": "Allow",
            "Resource": "*",
            "Sid": "GlobalPermissions"
        },
        {
            "Action": [
                "ec2:AcceptVpcEndpointConnections",
                "ec2:CreateTags",
                "ec2:CreateVpcEndpointServiceConfiguration",
                "ec2:DeleteVpcEndpointServiceConfigurations",
                "ec2:DescribeVpcEndpointServicePermissions",
                "ec2:ModifyVpcEndpointServiceConfiguration",
                "ec2:ModifyVpcEndpointServicePermissions",
                "ec2:RejectVpcEndpointConnections",
                "ec2:StartVpcEndpointServicePrivateDnsVerification",
                "vpce:AllowMultiRegion"
            ],
            "Effect": "Allow",
            "Resource": "arn:aws:ec2:<<REGION>>:<<ACCOUNT_ID>>:vpc-endpoint-service/*",
            "Sid": "EC2ResourceSpecific"
        },
        {
            "Action": [
                "ec2:AuthorizeSecurityGroupEgress",
                "ec2:AuthorizeSecurityGroupIngress",
                "ec2:CreateSecurityGroup",
                "ec2:CreateTags",
                "ec2:DeleteSecurityGroup",
                "ec2:RevokeSecurityGroupEgress"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:ec2:<<REGION>>:<<ACCOUNT_ID>>:security-group/*",
                "arn:aws:ec2:<<REGION>>:<<ACCOUNT_ID>>:vpc/*"
            ],
            "Sid": "EC2SecurityGroups"
        },
        {
            "Action": [
                "eks:AccessKubernetesApi",
                "eks:DeleteNodegroup",
                "eks:DescribeCluster",
                "eks:DescribeNodegroup"
            ],
            "Effect": "Allow",
            "Resource": "arn:aws:eks:<<REGION>>:<<ACCOUNT_ID>>:cluster/*",
            "Sid": "EKSClusters"
        },
        {
            "Action": [
                "acm:AddTagsToCertificate",
                "acm:DeleteCertificate",
                "acm:DescribeCertificate",
                "acm:ListTagsForCertificate",
                "acm:RequestCertificate"
            ],
            "Effect": "Allow",
            "Resource": "arn:aws:acm:<<REGION>>:<<ACCOUNT_ID>>:certificate/*",
            "Sid": "ACMCertificates"
        },
        {
            "Action": [
                "logs:CreateLogGroup",
                "logs:DeleteLogGroup",
                "logs:DescribeLogGroups",
                "logs:FilterLogEvents",
                "logs:GetLogEvents",
                "logs:ListTagsForResource",
                "logs:PutRetentionPolicy",
                "logs:TagResource",
                "logs:UntagResource"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:logs:<<REGION>>:<<ACCOUNT_ID>>:log-group:/ecs/unionai/proxy-*",
                "arn:aws:logs:<<REGION>>:<<ACCOUNT_ID>>:log-group::log-stream"
            ],
            "Sid": "LogGroups"
        },
        {
            "Action": [
                "elasticloadbalancing:AddTags",
                "elasticloadbalancing:CreateListener",
                "elasticloadbalancing:CreateLoadBalancer",
                "elasticloadbalancing:CreateTargetGroup",
                "elasticloadbalancing:DescribeListeners",
                "elasticloadbalancing:DescribeLoadBalancerAttributes",
                "elasticloadbalancing:DescribeLoadBalancers",
                "elasticloadbalancing:DescribeTargetGroups",
                "elasticloadbalancing:DescribeTargetGroupAttributes",
                "elasticloadbalancing:DescribeTags",
                "elasticloadbalancing:DeleteListener",
                "elasticloadbalancing:DeleteLoadBalancer",
                "elasticloadbalancing:DeleteTargetGroup",
                "elasticloadbalancing:ModifyLoadBalancerAttributes",
                "elasticloadbalancing:ModifyTargetGroup",
                "elasticloadbalancing:ModifyTargetGroupAttributes"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:elasticloadbalancing:<<REGION>>:<<ACCOUNT_ID>>:loadbalancer/net/unionai-access-*/*",
                "arn:aws:elasticloadbalancing:<<REGION>>:<<ACCOUNT_ID>>:targetgroup/unionai-access-*/*",
                "arn:aws:elasticloadbalancing:<<REGION>>:<<ACCOUNT_ID>>:listener/net/unionai-access-*/*"
            ],
            "Sid": "LoadBalancer"
        },
        {
            "Action": [
                "ecs:CreateCluster",
                "ecs:CreateService",
                "ecs:DeleteCluster",
                "ecs:DeleteService",
                "ecs:DescribeClusters",
                "ecs:DescribeContainerInstances",
                "ecs:DescribeServices",
                "ecs:DescribeServiceDeployments",
                "ecs:DescribeServiceRevisions",
                "ecs:DescribeTaskDefinition",
                "ecs:ExecuteCommand",
                "ecs:ListClusters",
                "ecs:ListTagsForResource",
                "ecs:ListTaskDefinitions",
                "ecs:ListServices",
                "ecs:RegisterTaskDefinition",
                "ecs:TagResource",
                "ecs:UntagResource",
                "ecs:UpdateService",
                "ecs:StartTask",
                "ecs:StopTask"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:ecs:<<REGION>>:<<ACCOUNT_ID>>:cluster/unionai-access-*",
                "arn:aws:ecs:<<REGION>>:<<ACCOUNT_ID>>:service/unionai-access-*/*",
                "arn:aws:ecs:<<REGION>>:<<ACCOUNT_ID>>:task/unionai-access-*/*",
                "arn:aws:ecs:<<REGION>>:<<ACCOUNT_ID>>:task-definition/unionai-access-*:*"
            ],
            "Sid": "ECSClusterServiceTask"
        },
        {
            "Action": [
                "logs:DescribeLogGroups",
                "logs:DescribeLogStreams",
                "logs:GetLogEvents",
                "logs:GetQueryResults",
                "logs:StartQuery",
                "logs:StopQuery"
            ],
            "Effect": "Allow",
            "Resource": "arn:aws:logs:<<REGION>>:<<ACCOUNT_ID>>:log-group:/aws/ecs/containerinsights/unionai-access-*/*",
            "Sid": "ContainerInsights"
        }
    ],
    "Version": "2012-10-17"
}
```
Share the ARN of the two roles with the Union.ai team.
The Union.ai team will get back to you to verify that they are able to assume the role.

### Configure VPC Endpoints

Ensure your VPC include these endpoints so when the Union stack needs to connect to the corresponding AWS services, it does so without leaving the AWS network:

- `com.amazonaws.<REGION>.autoscaling`
- `com.amazonaws.<REGION>.xray`
- `com.amazonaws.<REGION>.s3`
- `com.amazonaws.<REGION>.sts`
- `com.amazonaws.<REGION>.ecr.api`
- `com.amazonaws.<REGION>.ssm`
- `com.amazonaws.<REGION>.ec2messages`
- `com.amazonaws.<REGION>.ec2`
- `com.amazonaws.<REGION>.ssmmessages`
- `com.amazonaws.<REGION>.ecr.dkr`
- `com.amazonaws.<REGION>.logs`
- `com.amazonaws.<REGION>.eks-auth`
- `com.amazonaws.<REGION>.eks`
- `com.amazonaws.<REGION>.elasticloadbalancing`


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/data-plane-setup-on-gcp ===

# Data plane setup on GCP

To set up your data plane on Google Cloud Platform (GCP) you must allow Union.ai to provision and maintain compute resources under your GCP account.
To do this you will need to provision a service account with sufficient permissions to perform these tasks.

## Select or create a project

The first step is to select an existing project or create a new one.
This is where Union.ai will provision all resources for your data plane.
Below, we use the placeholder `<ProjectID>` for the project ID.
The actual ID can be whatever you choose.
In addition, you will need the project number associated with your project.
Below we use the placeholder `<ProjectNumber>`.
The project number is visible on your project's [welcome page](https://console.cloud.google.com/welcome).

## Ensure billing is linked

Before your data plane can be deployed, you need to make sure that a billing account is linked to your project:
Go to the [billing page](https://console.cloud.google.com/billing/linkedaccount) of your `<ProjectId>` project and confirm that a billing account is linked.

## Create a workload identity pool and provider

Though your data plane will be in your project in GCP, the Union.ai control plane is still run in AWS.
To allow the control plane to interact with your data plane you must create a _workload identity pool_ and add Union.ai's AWS account as a workload provider.
For more details see the Google Cloud guide for [setting up workload identity federation](https://cloud.google.com/iam/docs/configuring-workload-identity-federation).

### In the GCP web console

1. In your project `<ProjectId>`, under **IAM & Admin > Workload Identity Federation**, select **+ CREATE POOL** to [create a new workload provider and pool](https://console.cloud.google.com/iam-admin/workload-identity-pools/create).
If you have not done so already, you will be guided to [enable the required APIs](https://console.cloud.google.com/flows/enableapi?apiid=iam.googleapis.com,cloudresourcemanager.googleapis.com,iamcredentials.googleapis.com,sts.googleapis.com).
2. **Pool Name**: `unionai` (you can also fill in the description if you like).
3. Under **Add a provider to pool**:
  * For **Select a provider**, choose **AWS**.
  * For **Provider name**, enter `unionai-aws`.
  * The **Provider ID** should be automatically set to `unionai-aws` as well. If not, select **EDIT** and enter it manually.
4. For **AWS Account ID**, enter `479331373192` (Union.ai's management account ID)
5. **Continue** with the default attribute mappings and conditions.

### On the command line using `gcloud`

Assuming you have the [`gcloud` tool ](https://cloud.google.com/sdk/gcloud)installed locally and are logged into `<UnionDataPlaneProjectID>`, you can check the existing workflow identity pools in your project with:

```bash
gcloud iam workload-identity-pools list --location="global"
```

To create the workload identity pool, do:

```bash
gcloud iam workload-identity-pools create unionai \
    --location="global" \
    --description="Union AI WIF" \
    --display-name="unionai"
```

To add the provider, do:

```bash
gcloud iam workload-identity-pools providers create-aws unionai-aws \
    --location="global"  \
    --workload-identity-pool="unionai" \
    --account-id="479331373192"
```

## Create a role for Union.ai admin

To ensure that the Union.ai team has all the privileges needed to deploy the data plane, _but no more than strictly necessary_, you will need to create a custom role that the Union.ai service account will assume.

To avoid having to manually select each separate required privilege we recommend that you perform this step on the command-line with `gcloud`.

First, you will need to download the following YAML file to the directory where you are running your `gcloud` commands.
This file is the role definition. It is a list of the privileges that will make up the new role.

- [`union-ai-admin-role.yaml`](https://github.com/unionai/union-cloud-infrastructure/blob/main/union-ai-admin/gcp/union-ai-admin-role.yaml)

Assuming you have the above file (`union-ai-admin-role.yaml`) in your current directory and substituting your project ID, do:

```bash
gcloud iam roles create UnionaiAdministrator \
    --project=<ProjectId> \
    --file=union-ai-admin-role.yaml
```

## Create the Union.ai admin service account

### In the GCP web console

1. Go to **IAM & Admin >** [**Service Accounts**](https://console.cloud.google.com/iam-admin/serviceaccounts).
2. Select **Create Service Account**
3. For **Name**, enter `Union.ai Administrator`.
4. For **ID**, enter `unionai-administrator`.
_Note that setup process used by the Union.ai team depends on the ID being this precise string_.
_If you use a different ID (though this is not recommended) then you must inform the Union.ai team of this change._
5. You can enter a **Description** if you wish.
6. Grant this service account access to your project `<ProjectId>` with the role create above, `UnionaiAdministrator`.

### On the command line using `gcloud`

Create the service account like this:

```bash
gcloud iam service-accounts create unionai-administrator \
    --project <ProjectId>
```

Bind the service account to the project and add the Union.ai Administrator role like this (again, substituting your project ID):

```bash
gcloud projects add-iam-policy-binding <ProjectId> \
    --member="serviceAccount:unionai-administrator@<ProjectId>.iam.gserviceaccount.com" \
    --role="projects/<ProjectId>/roles/UnionaiAdministrator"
```

## Grant access for the Workflow Identity Pool to the Service Account

### In the GCP web console

1. Go to the newly created [workload identity pool](https://console.cloud.google.com/iam-admin/workload-identity-pools/pool/unionai) page.
2. Select **Grant Access**.
3. Choose the newly created service account.
4. Select **Save**.

### On the command line using `gcloud`

To grant the WIP access to the service account, do the following.
Notice that you must substitute your `<ProjectId>` and your `<ProjectNumber>`.

```bash
gcloud iam service-accounts add-iam-policy-binding unionai-administrator@<ProjectId>.iam.gserviceaccount.com \
      --project=<ProjectId> \
      --role="roles/iam.workloadIdentityUser" \
      --member="principalSet://iam.googleapis.com/projects/<ProjectNumber>/locations/global/workloadIdentityPools/unionai/*"
```

## Enable services API

You will need to enable the following service APIs.

| Name | Endpoint |
|------|----------|
| Artifact Registry API | `artifactregistry.googleapis.com` |
| Cloud Autoscaling API | `autoscaling.googleapis.com` |
| Cloud Key Management Service (KMS) API | `cloudkms.googleapis.com` |
| Cloud Resource Manager API | `cloudresourcemanager.googleapis.com` |
| Compute Engine API | `compute.googleapis.com` |
| Kubernetes Engine API | `container.googleapis.com` |
| Container File System API | `containerfilesystem.googleapis.com` |
| Container Registry API | `containerregistry.googleapis.com` |
| Identity and Access Management (IAM) APIs | `iam.googleapis.com` |
| IAM Service Account Credentials API | `iamcredentials.googleapis.com` |
| Cloud Logging API | `logging.googleapis.com` |
| Cloud Monitoring API | `monitoring.googleapis.com` |
| Secret Manager API | `secretmanager.googleapis.com` |
| Service Networking API | `servicenetworking.googleapis.com` |
| Security Token Service API | `sts.googleapis.com` |
| Cloud SQL Admin API | `sqladmin.googleapis.com` |
| Cloud Storage Services API | `storage-api.googleapis.com` |

### In the GCP web console

Go to [Google Cloud API library](https://console.cloud.google.com/apis/library) and enable each of these by searching for it and clicking **ENABLE**.

### On the command line using `gcloud`

Perform the following `gcloud` commands:

```bash
gcloud services enable artifactregistry.googleapis.com
gcloud services enable autoscaling.googleapis.com
gcloud services enable cloudkms.googleapis.com
gcloud services enable cloudresourcemanager.googleapis.com
gcloud services enable compute.googleapis.com
gcloud services enable container.googleapis.com
gcloud services enable containerfilesystem.googleapis.com
gcloud services enable containerregistry.googleapis.com
gcloud services enable iam.googleapis.com
gcloud services enable iamcredentials.googleapis.com
gcloud services enable logging.googleapis.com
gcloud services enable monitoring.googleapis.com
gcloud services enable secretmanager.googleapis.com
gcloud services enable servicenetworking.googleapis.com
gcloud services enable sts.googleapis.com
gcloud services enable sqladmin.googleapis.com
gcloud services enable storage-api.googleapis.com
```

## Setting up and managing your own VPC (optional)

If you decide to manage your own VPC instead of leaving it to Union.ai, then you will need to set it up yourself.
The VPC should be configured with the following characteristics:

* We recommend using a VPC that resides in the same project as the Union.ai Data Plane Kubernetes cluster. If you want to use a [shared VPC](https://cloud.google.com/vpc/docs/shared-vpc), contact Union.ai support.
* Create a single VPC subnet with:
  * A primary IPv4 range with /18 CIDR mask. This is used for cluster node IP addresses.
  * A secondary range with /15 CIDR mask. This is used for Kubernetes Pod IP addresses. We recommend associating the name with pods, e.g. `gke-pods`.
  * A secondary range with /18 CIDR mask. This is used for Kubernetes service IP address. We recommend associating the name with services, e.g. `gke-services`.
  * Identify a /28 CIDR block that will be used for the Kubernetes Master IP addresses. Note this CIDR block is not reserved within the subnet. Google Kubernetes Engine requires this /28 block to be available.

Once your VPC is set up, provide the following to Union.ai:

* VPC name
* Subnet region and name
* The secondary range name for the /15 CIDR mask and /16 CIDR mask
* The /18 CIDR block that was left unallocated for the Kubernetes Master

### Example VPC CIDR Block allocation

* 10.0.0.0/18 Subnet 1 primary IPv4 range → Used for GCP Nodes
* 10.32.0.0/14 Cluster secondary IPv4 range named `gke-pods` → Used for Kubernetes Pods
* 10.64.0.0/18 Service secondary IPv4 range named `gke-services` → Used for Kubernetes Services
* 10.65.0.0/28 Unallocated for Kubernetes Master


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/data-plane-setup-on-azure ===

# Data plane setup on Azure

To set up your data plane on Azure, you must allow Union.ai to provision and maintain compute resources under your Azure subscription. To do this, you will need to provision an Azure app registration with sufficient permissions to an Azure subscription.

## Selecting Azure tenant and subscription

- Select the tenant ID for your organization. Refer to [Microsoft Entra ID service page](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview) from the Azure portal.
- We highly recommend creating a new subscription for Union.ai-specific services. This helps isolate permissions, service quotas, and costs for Union.ai managed Azure resources.
  - Ensure the subscription is tied to an active billing account.
- Provide the Tenant and Subscription ID to Union.ai.

## Create a Microsoft Entra Application Registration

Union.ai requires permissions to manage Azure and Microsoft Entra resources to create a dataplane. This step involves
creating a Union.ai specific App and granting it sufficient permission to manage the dataplane.

### Create a Microsoft Entra ID Application for Union.ai Access

Union.ai manages Azure resources through a [Microsoft Entra ID Application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) via [Workload Identity Federation](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust?pivots=identity-wif-apps-methods-azp).

1. Navigate to the [Application Registrations](https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade/quickStartType~/null/sourceType/Microsoft_AAD_IAM) page.
2. Create a new registration.
3. Create a new application. The name is your choice, but we recommend `union`. Leave it at the "Single Tenant" account type and do not add any registration URIs.
4. Navigate to your target [Azure Subscription](https://portal.azure.com/#view/Microsoft_Azure_Billing/SubscriptionsBladeV2).
5. Within the Subscription page select Access Control (IAM). Select Add Role Assignment and add the following roles scoped against the subscription:

- Contributor
- Role Based Access Control Administrator

6. Provide the Application Client ID to Union.ai.
7. Go the application registration page for the app you created.
8. Select "Certificates & secrets."
9. Select the "Federated Credentials" tab, then select "Add credential", and choose "Other issuer".
10. Set "Issuer" to `https://cognito-identity.amazonaws.com`
11. Set "Subject identifier" to `us-east-2:6f9a6050-887a-c4cc-0625-120a4805bc34`
12. "Name" is your choice, but we recommend `union-access`
13. Set "Audience" to `us-east-2:ad71bce5-161b-4430-85a5-7ea84a941e6a`

### Create Microsoft Entra ID Applications for Union.ai cost allocation

Union.ai requires new roles and applications to support Union's cost allocation feature.
This can be done by providing the `union` application additional permissions or you can choose to create the roles and applications yourself.

#### Union managed cost allocation roles

- Assign `User Access Administrator` role to the `union` application against the subscription. This enables Union.ai role creation.
- Assign `Application Administrator` role to the `union` application within Microsoft Entra ID. This allows Union to create applications.

#### Create cost allocation roles and applications manually

Union.ai requires a role and service principal for the internal OpenCost subsystem.

Create the OpenCost role for retrieving pricing data (name and subscription can be changed):

```bash
az role definition create --role-definition '{
  "Name": "UnionOpenCostRole",
  "Description": "Role used by OpenCost pod",
  "Actions": [
    "Microsoft.Compute/virtualMachines/vmSizes/read",
    "Microsoft.Resources/subscriptions/locations/read",
    "Microsoft.Resources/providers/read",
    "Microsoft.ContainerService/containerServices/read",
    "Microsoft.Commerce/RateCard/read"
  ],
  "NotActions": [],
  "AssignableScopes": [
    "/subscriptions/YOUR_SUBSCRIPTION_ID"
  ]
}'
```

Create the OpenCost service principal. This creates an application registration, service principal, client secret, and role assignment:

```bash
az ad sp create-for-rbac \
  --name "UnionOpenCost" \
  --role "UnionOpenCostRole" \
  --scopes "/subscriptions/YOUR_SUBSCRIPTION_ID" \
  --years 2
```

Share the output of the above `az ad sp create-for-rbac` command with Union.ai.

## (Recommended) Create a Microsoft Entra group for cluster administration

We recommend [creating a Microsoft Entra group](https://learn.microsoft.com/en-us/training/modules/create-users-and-groups-in-azure-active-directory/) for AKS cluster admin access.
AKS Cluster admin access is commonly provided to individuals that need direct (e.g. `kubectl`) access to the cluster.

Provide the group `Object ID` to Union.ai.

## (Optional) Setting up and managing your own VNet

If you decide to manage your own VNet instead of leaving it to Union.ai, you will need to set it up yourself.

### Required Union.ai VNet permissions

Union.ai requires permissions to read Azure network resources and assign the `Network Contributor` role to the underlying Union.ai Kubernetes cluster.

[Create a role assignment](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal) to allow Union.ai to read VNet resources and assign roles. These permissions should be scoped to the target Virtual Network (VNet). Follow these steps to set up the required access:

1. Navigate to the Azure portal and locate the target VNet.
2. In the VNet's access control (IAM) section, create a new role assignment.
3. For the 'Assigned to' field, select the Union.ai application's service principal.
4. For the 'Role' field, you have two options:
   - Simplest approach: Assign the built-in Azure roles `Reader` and `User Access Administrator`.
   - Advanced approach: Create a custom role with the following specific permissions:
     - `Microsoft.Network/*/read`
     - `Microsoft.Authorization/roleAssignments/write`
     - `Microsoft.Authorization/roleAssignments/delete`
     - `Microsoft.Authorization/roleAssignments/read`
     - `Microsoft.Authorization/roleDefinitions/read`
5. Ensure the 'Scope' is set to the target VNet.
6. Complete the role assignment process.

This configuration will provide the Union.ai application with the necessary permissions to interact with and manage resources within the specified VNet.

> [!NOTE] Creating Azure role assignments
>
> For more detailed instructions on creating role assignments, refer to the
> [official Azure documentation](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal).

### Required VNet properties

We recommend using a VNet within the same Azure tenant as your Union.ai data plane. It should be configured with the following characteristics:

- A single subnet with an address prefix with `/19` CIDR mask. This is used for Kubernetes nodes.
- One to five subnets with an address prefix with `/14` to `/18` CIDR mask. This is used for Kubernetes pods. `/14` is preferable to mitigate IP exhaustion. It is common to start with one subnet for initial clusters and add more subnets as workloads scale.
- An non-allocated (i.e., no subnet) `/19` CIDR range that will be retained for service CIDRs.
- Within the CIDR range, choose a single IP address that will be used for internal DNS. This IP address should not be the first address within the CIDR range.
- (Recommended): Enable [virtual network service endpoints](https://learn.microsoft.com/en-us/azure/virtual-network/virtual-network-service-endpoints-overview) `Microsoft.Storage`, `Microsoft.ContainerRegistry`, and `Microsoft.KeyVault`.
- (Recommended) Create a [NAT gateway for virtual network](https://learn.microsoft.com/en-us/azure/nat-gateway/quickstart-create-nat-gateway-portal) egress traffic. This allows scaling out public IP addresses and limit potential external rate limiting scenarios.

Once your VPC is set up, provide the following to Union.ai:

- The Virtual Network's subscription ID.
- The Virtual Network's name.
- The Virtual Network's resource group name.
- The Virtual Network's subnet name used for Kubernetes nodes.
- The Virtual Network's subnet names used for Kubernetes pods.
- The CIDR range intended to use for Kubernetes services.
- The IP address to be used for internal DNS.

### Example VPC CIDR Block allocation

- `10.0.0.0/8` for the VPC CIDR block.
- `10.0.0.0/19` for the Kubernetes node specific subnet.
- `10.4.0.0/14` for the initial Kubernetes pods specific subnet.
  - `10.8.0.0/14`, `10.12.0.0/14`, `10.16.0.0/14`, `10.20.0.0/14` for any future Kubernetes pod specific subnets.
- `10.0.96.0/19` unallocated for Kubernetes services.
- `10.0.96.10` for internal DNS.

## Union.ai Maintenance Windows

Union.ai configures a four hour maintainence window to run monthly on the first Sunday at 3AM with respect to the Azure location's timezone.

> [!NOTE] Setting up Tasks for Fault Tolerance
> During this time window Flyte execution pods could be potentially interrupted.
> We recommend leveraging
> [Flyte fault tolerance](https://docs.flyte.org/en/latest/concepts/tasks.html#fault-tolerance) and
> [checkpointing](https://docs.flyte.org/en/latest/user_guide/advanced_composition/intratask_checkpoints.html)
> to efficiently minimize failed executions.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/data-retention-policy ===

# Data retention policy

Data retention polices allow you to control what data is stored in your data plane and for how long.
This allows you to reduce costs by ensuring that you only keep data that you actually need.

Each data plane has its own Union.ai-internal object store (an AWS S3 bucket, GCS bucket or ABS container) that is used to store data used in the execution of workflows.
As a Union.ai administrator, you can specify retention policies for this data when setting up your data plane.
The policies are specified in discussion with the Union.ai team when you set up your Union.ai instance.
They are not adjustable through the UI or CLI.

## Data categories

The retention policy system distinguishes three categories of data:

1. Workflow execution data:
   - Task inputs and outputs (that is, primitive type literals)
   - `FlyteFile`/`FlyteDirectory` and other large offloaded data objects (like `DataFrame`s) both in their default locations and in any custom `raw-data-prefix` locations that may have been specified at execution time
   - Flyte `Deck` data.
   - Artifact data.
   - Internal metadata used by Union.ai.
2. Fast-registered code:
   - Local code artifacts that will be copied into the Flyte task container at runtime when using `union register` or `union run --remote --copy-all`.
3. Flyte plugin metadata (for example, Spark history server data).

Each category of data is stored in a separate Union.ai-managed object store bucket and versioning is enabled on these buckets.
This means that two separate retention policies can be specified for each data category: one for current versions and one for non-current versions.
The result is that there are four distinct retention policies to specify (though in most cases you can stick with the defaults, see below).

> [!NOTE] Object versions are not the same as Union.ai entity versions
> The versions discussed here are at the object level and are not related to the versions of workflows,
> tasks and other Union.ai entities that you see in the Union.ai UI.

## How policies are specified

A policy determines how long data in a given category and version-state (current vs. non-current) will be retained in the object store before it is automatically deleted.

A policy is specified as a time period in days, or `unlimited` (in which case automatic data deletion is disabled for that category and version-state).

## Deletion of current versions

For current version, deletion due to a retention period running out means moving the object to a non-current version, which we refer to as _soft-deletion_.

## Deletion of non-current versions

For non-current versions, deletion due to a retention period running out means permanent deletion.

## Defaults

|                     | Workflow execution data | Fast-registered code | Flyte-plugin metadata |
| ------------------- | ----------------------- | -------------------- | --------------------- |
| Current version     | unlimited               | unlimited            | unlimited             |
| Non-current version | 7 days                  | 7 days               | 7 days                |

By default:

- The retention policy for _current versions in all categories_ is `unlimited`, meaning that auto-deletion is disabled.

  - If you change this to a specified number of days, then auto-deletion will occur after that time period, but because it applies to current versions the data object will be soft-deleted (that is, moved to a non-current version), not permanently deleted.

- The retention policy for _non-current versions in all categories_ is `7 days`, meaning that auto-deletion will occur after 7 days and that the data will be permanently deleted.

## Attempting to access deleted data

If you attempt to access deleted data, you will receive an error:

- When workflow node input/output data is deleted, the Input/Output tabs in the UI will display a _Not Found_ error.
- When `Deck` data is deleted, the `Deck` view in the UI will display a _Not Found_ error.
- When artifacts are deleted, the artifacts UI will work, but it will display a URL that points to no longer existing artifact.

To remedy these types of errors, you will have to re-run the workflow that generated the data in question.

- When fast registered code data is deleted, the workflow execution will fail.

To remedy this type of error, you will have to both re-register and re-run the workflow.

## Separate sets of policies per cluster

If you have a multi-cluster set up, you can specify a different set of retention policies (one per category) for each cluster.

## Data retention and task caching

When enabling data retention, task caching will be adjusted accordingly. To avoid attempts to retrieve cache data that has already been deleted, the `age` of the cache will always be configured to be less than the sum of both retention periods.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/enabling-aws-resources ===

# Enabling AWS resources

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

Components of your Union.ai data plane will need to connect to and communicate with other resources in your cloud environment such as **BYOC deployment > Enabling AWS resources > Enabling AWS S3**, **BYOC deployment > Enabling AWS resources > Enabling AWS ECR**, and so forth.

> [!NOTE] Secret management
> We strongly recommend using the **Configure tasks > Secrets** to manage secrets rather than AWS Secrets Manager. If your organization must use AWS Secrets Manager, however, see **BYOC deployment > Enabling AWS resources > Enabling AWS Secrets Manager**.

As much as possible, access to the resources you need will be pre-configured by the Union.ai team when they set up your data plane.
For example, if you want your task code to have access to a specific S3 bucket or database, this can be pre-configured.
**You just have to inform the team of your specific requirements before the setup process begins**.

As your projects evolve, your needs may change.
You can always contact the Union.ai team for help enabling additional resources as required.

**There are also some cases where you may want to configure things on your own.**
**Below we give a general overview of these self-configuration options.**
**The sub-pages of this section give examples for specific resources.**

## Types of access

Broadly speaking, there are two categories of access that you are likely to have to deal with:

* **Infrastructure access**:
  Enabling access to a resource for your data plane infrastructure.
  The most common case occurs when you are using **BYOC deployment > Enabling AWS resources > Enabling AWS ECR** for your task container images, and it resides in an AWS account other than the one containing your data plane.
  In that case, some configuration is required to enable the Union.ai operator on your data plane to pull images from the registry when registering your workflows and tasks.
  **If you are using an ECR instance within the same AWS account as your data plane, then access is enabled by default and no further configuration is needed.**
* **Task code access**:
  Enabling access to a resource for your task code.
  For example, your task code might need to access **BYOC deployment > Enabling AWS resources > Enabling AWS S3** or **BYOC deployment > Enabling AWS resources > Enabling AWS Secrets Manager** at runtime.
  This involves granting permission to roles that are attached to the Kubernetes cluster within which your task code runs.

## Infrastructure-level access

The only infrastructure-level access issue you are likely to encounter is around access to an AWS Elastic Container Registry (ECR) _in an AWS account other than the one in which your data plane resides_.

**If your task container images are stored in an AWS Elastic Container Registry in the same AWS account as your data plane, then access is already enabled. You do not have to do anything.**

If your task container images reside in an ECR instance in **another AWS account** you will need configure that ECR instance to allow access from your data plane.
See **BYOC deployment > Enabling AWS resources > Enabling AWS ECR** for details.

## Task code access

When your task code runs, it executes within a pod in the Kubernetes cluster in your data plane.
To enable your task code to access cloud resources you must grant the appropriate permissions to a role that is attached to the Kubernetes cluster.

There are two main options for setting this up:

* **Project-domain-scoped access**: With this arrangement, you define the permissions you want to grant to your task code, and those permissions are applied only to specific project-domain pairs.
* **Global access**: With this arrangement, you define the permissions you want to grant to your task code, and those permissions are then applied to code in all your projects and domains.

Global access is recommended for most use cases since it is simpler, but if you have a compelling reason to restrict access, then the project-domain-scoped access is available, at the cost of some additional complexity in setup.

> [!NOTE] Relationship with RBAC
> The permissions being discussed here are attached to a project and domain.
> This is independent of the permissions granted to users and machine applications through Union.ai's role-based access control (see the user management documentation).
> But, the two types of permissions are related.
>
> For example, for a user (or machine application) to have read access to an S3 bucket, two things are required:
>
> * The user (or machine application) must have **execute** permission for the project and domain where the code that does the reading resides.
> * The project and domain must have read permission for the S3 bucket.

## Background

As you know, your workflows and tasks run in a Kubernetes cluster within your data plane.
Within that cluster, the Kubernetes pods allocated to run your task code are organized as follows:

* The set of task pods is partitioned into namespaces where each namespace corresponds to a project-domain pair.
* All workflows running in a given project and domain are run on pods within that namespace.
  For example, code in the `development` domain of project `foo` runs in the namespace `foo-development` while code in the `staging` domain of project `bar` runs in the namespace `bar-staging`, and so forth.
* By default, all project-domain namespaces are bound to a common IAM role which we will refer to as `<UserFlyteRole>`.
  Its actual name differs from organization to organization. **The actual name will have the form `<YourOrgPrefix>-userflyterole`**.
* The role `<UserFlyteRole>` has an attached policy called `userflyterole`.
  This policy contains all the permissions granted to your task code when your data plane was set up.
  If you requested permissions for resources specific to your organization at set up time, they will have been added here.

> [!NOTE] `<UserFlyteRole>` vs `userflyterole`
> The entity that we refer to here as `<UserFlyteRole>` is an IAM role.
> As mentioned the actual name of this role in your system will be of the form `<YourOrgPrefix>-userflyterole.`
>
> By default, this role has an attached IAM policy called `userflyterole`.
> This is the literal name used in all AWS-based data planes.
>
> **Be aware of the difference and don't get these two things confused!**

> [!NOTE] `<UserFlyteRole>`vs `<AdminFlyteRole>`
> In addition to the task pods, your cluster also contains pods that run Union.ai services, which are used to manage tasks and to connect your cluster to the control plane.
> These pods are bound to a different default role, `<AdminFlyteRole>` (again, its actual name differs from organization to organization).
> The separation of this role from `<UserFlyteRole>` serves to provide isolation between Union.ai administrative logic and your workflow logic.
>
> **You should not alter any settings associated with `<AdminFlyteRole>`**.

## Enabling access

To enable your task code to access a resource:

* **BYOC deployment > Enabling AWS resources > Enabling access > Creating a custom policy** that grants the appropriate permissions for your resource.
  This is the step where you define exactly which permissions you want to grant (read-only, read/write, list, etc.).
  The name of this policy is yours to determine.
  Here we will refer to it as `<CustomPolicy>`.

You can then choose whether to enable **global access** or **project-domain-scoped access**:

* **BYOC deployment > Enabling AWS resources > Enabling access > Setting up global access** to the resource, you simply attach `<CustomPolicy>` to the existing `<UserFlyteRole>`.
* **BYOC deployment > Enabling AWS resources > Enabling access > Setting up project-domain-scoped access** to your resource:
  * Create your own custom role (let's refer to it `<CustomRole>`)
  * Attach `<CustomPolicy>` to `<CustomRole>`.
  * Also, attach the policy called `userflyterole` to `<CustomRole>` (this will ensure that `<CustomRole>` has all the default permissions needed to allow tasks to run).
  * Attach `<CustomRole>` to the desired project-domain namespace.

![](../../../_static/images/user-guide/integrations/enabling-aws-resources/union-roles.png)

### Creating a custom policy

Regardless of which route you take (global vs project-domain-scoped) the first step is to create a policy that grants the desired permissions to your resource.

To create a new policy:

* Go to **IAM > Access management > Policies**.
* Select **Create policy**.
* Go through the sections of the visual editor to define the permissions you wish to grant.
  * Alternatively, you can paste a JSON definition directly into the JSON editor.
  * The details of what permissions to grant depend on the resource in question and the access you wish to grant.
    Specific examples are covered in **BYOC deployment > Enabling AWS resources > Enabling AWS S3** and **BYOC deployment > Enabling AWS resources > Enabling AWS Secrets Manager**.
* Proceed through the steps of the wizard, give your policy a name (which we will call `<CustomPolicy>`), and select **Create policy**.
* Record the name and ARN of your policy.
  Here we will refer to the ARN is `<CustomPolicyArn>`.

### Setting up global access

To set up global access, you must bind the `<CustomPolicy>` that you created above to the role `<UserFlyteRole>`.

> [!NOTE]
> As mentioned above, the actual name of `<UserFlyteRole>` has the form:
>
> **`<YourOrgPrefix>-userflyterole`**
>
> You should be able to find the role by searching in your AWS IAM console for roles with names that follow that pattern.

* Go to **IAM > Access management > Roles**.
* Find `<UserFlyteRole>` and select the checkbox beside it.
* In the **Add Permissions** drop-down menu, select **Attach Policies**.
* In the displayed list find `<CustomPolicy>` and select its checkbox, then select **Add permissions**.

> [!NOTE]
> Alternatively, you can perform the binding from the command line like this:
>
> ```bash
> $ aws iam attach-role-policy \
>  --policy-arn <CustomPolicyArn> \
>  --role-name <UserFlyteRole>
> ```
>
> Notice that in this case, you have to use `<CustomPolicyArn>` here instead of `<CustomPolicy>`.

**At this point, all task code in your organization will have access to the cloud resource as defined by your custom policy.**

### Setting up project-domain-scoped access

To set up project-domain-scoped access, you do this:

In AWS:

* Create the IAM role, `<CustomRole>`.
* Add the `userflyterole` policy to `<CustomRole>`.
* Add `<CustomPolicy>` to `<CustomRole>`.

In Union.ai (using `uctl`):

* Bind `<CustomRole>` to the project-domain pair desired.

### Create the IAM role

1. Sign in to the AWS Management Console as an administrator of your account, and open the IAM console.
2. In the navigation pane, choose **Roles** and then choose **Create role**.
3. Choose the **Web identity** role type.
4. In the **Identity provider** dropdown select `oidc.eks.<Suffix>.`Record this name.
5. Choose `sts.amazonaws.com` as the **Audience** and select **Next**.
6. On the **Add permissions** page, search for the `userflyterole` policy and check the box beside it and select **Next**.
7. Enter a name and description for this role.
8. Under **Step 1: Select trusted entities**, click edit and _replace_ the `Condition` block with the following, where `oidc.eks.<Suffix>` is the value from step 4, and `<Project>`, and `<Domain>` are the Union.ai project and domain pairs you want to set custom permissions for. Repeat for each project-domain pair.

```json
"Condition": {
    "StringEquals": {
        "oidc.eks.<Suffix>:sub": [
            "system:serviceaccount:<Project>-<Domain1>:default",
            "system:serviceaccount:<Project>-<Domain2>:default"
        ]
    }
}
```

9. Add additional permissions as needed, following [these steps](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html).
10. Select **Create role**.
11. In the **Summary** section of the new role's details pane, note the ARN value.

### Configure the cluster to use the new IAM role

Repeat the following steps for each project-domain pair:

1.  Create a file named `cluster_resource_attributes.yaml` with the following contents:

```yaml
attributes:
defaultUserRoleValue: <ARN from step 11 above>
domain: <domain>
project: <project>
```

2.  Run the following command to override the IAM role used for Union.ai Tasks in this Project-Domain:

```bash
uctl update cluster-resource-attribute --attrFile cluster_resource_attributes.yaml
```

3.  You can verify the overrides by running:

```bash
uctl get cluster-resource-attribute -p <project> -d <domain>
```

**At this point, only code in your chosen project-domain pairs will have access to the cloud resource as defined by your custom policy.**

## Subpages
- **BYOC deployment > Enabling AWS resources > Enabling AWS S3**
- **BYOC deployment > Enabling AWS resources > Enabling AWS ECR**
- **BYOC deployment > Enabling AWS resources > Enabling AWS Secrets Manager**


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/enabling-aws-resources/enabling-aws-s3 ===

# Enabling AWS S3

For Union.ai customers whose data plane is in AWS, we walk through setting up access to your own AWS S3 bucket.

> [!NOTE] AWS S3 in the Union.ai environment
> Your data plane is set up with a Kubernetes cluster and other resources.
> Among these are a number of S3 buckets used internally by the Union.ai operator running in the cluster (see [Platform architecture](../platform-architecture)) to store things like workflow metadata.
>
> **These **_**are not**_** the S3 bucket we are talking about in this section.**
>
> **We are discussing the case where you have **_**your own S3 bucket**_** that you set up to store input and output data used by your workflows.**

## Add permissions to your custom policy

In order to enable access to an AWS resource (in this case S3) you need to create a custom policy in AWS IAM with the required permissions and attach it to either the existing _User Flyte Role_ associated with your data plane Kubernetes cluster or to a custom role which you have created and attached to the cluster.
The general procedure is covered in **BYOC deployment > Enabling AWS resources > Enabling AWS S3**.

_In order to enable S3 access in particular, in the step_ [#add-permissions-to-your-custom-policy](./enabling-aws-s3#add-permissions-to-your-custom-policy) _you must specify the needed permissions. For example:_

- `s3:ListBucket` - This permission allows you to list the objects in the bucket.
- `s3:GetObject` - This permission allows you to retrieve objects from the bucket.
- `s3:PutObject` - This permission allows you to upload objects to the bucket.

Here is a sample JSON policy document that grants these permissions:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowReadWriteBucket",
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket",
        "s3:GetObject",
        "s3:PutObject"
      ],
      "Resource": [
        "arn:aws:s3:::<BucketName>/*",
        "arn:aws:s3:::<BucketName>"
      ]
    }
  ]
}
```

In the `Resource` field, replace `<BucketName>` with the actual name of your S3 bucket.

## Accessing S3 from your task code

Once you have enabled access to your S3 bucket, you can use the standard [AWS SDK for Python (Boto3)](https://aws.amazon.com/sdk-for-python/) in your task code to read and write to it.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/enabling-aws-resources/enabling-aws-ecr ===

# Enabling AWS ECR

## Access to ECR in the same account is enabled by default

When registering tasks and workflows, the Union.ai infrastructure in your data plane must have access to the container registry that holds the task container images you will be using.
If your data plane is on AWS then you may want to use AWS Elastic Container Registry (ECR) to store these images.

For details on how to use ECR when building and deploying your workflows, see the ImageSpec with ECR documentation.

**In most cases, you will be using an ECR instance in the same AWS account as your data plane.**
**If this is the case, then you do not need to configure anything.**
**Access to ECR in the same account is enabled by default.**

## Enabling cross-account access to ECR

If you want to store your task container images in an ECR instance in an AWS account _other than the one that holds your data plane_, then you will have to configure that ECR instance to permit access from your data plane.
Here are the details:

* Your Union.ai data plane comes pre-configured with a specific role, which we will refer to here as `<FlyteWorkerNodeGroupRole>`.
* The actual name of this role depends on your organization's name. It will be of the form `unionai-<YourOrganizationName>-flyteworker-node-group`.

To enable access to the ECR instance in the other account, do the following:

* In your data plane AWS account, Go to **IAM > Roles**.
Find the role `<FlyteWorkerNodeGroupRole>` and copy the ARN of that role.
We will call this `<FlyteWorkerNodeGroupRoleARN>`.
* In the other AWS account (the one that contains the ECR instance), go to **Amazon ECR > Repositories**,
* Find the ECR repository you want to enable and under **Permissions**, select **Edit,** then **Add Statement**.
* Specify the `<FlyteWorkerNodeGroupRoleARN>` as a **Principal** and add (at least) the following permissions:
  * `ecr:BatchCheckLayerAvailability`: This permission allows your data plane to check the availability of image layers in the registry.
  * `ecr:GetDownloadUrlForLayer`: This permission allows your data plane to retrieve a pre-signed URL that is required to download the image layers.
  * `ecr:BatchGetImage`: This permission allows your data plane to retrieve image manifests and image layer information from the registry.
* To specify the above parameters via JSON, select **Edit policy JSON** and use the following policy document:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowPull",
      "Effect": "Allow",
      "Principal": {
        "AWS": "<FlyteWorkerNodeGroupRoleARN>"
      },
      "Action": [
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "ecr:BatchCheckLayerAvailability"
      ]
    }
  ]
}
```

* Select **Save**.

Your Union.ai data plane infrastructure should now be able to pull images from the ECR instance. For more information see [How can I allow a secondary account to push or pull images in my Amazon ECR image repository?](https://repost.aws/knowledge-center/secondary-account-access-ecr)


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/enabling-aws-resources/enabling-aws-secrets-manager ===

# Enabling AWS Secrets Manager

> [!NOTE]
> This documentation is for customers who must use AWS Secrets Manager for organizational reasons. For everyone else, we strongly recommend using the
> [Union.ai secrets manager](../../../user-guide/task-configuration/secrets) to manage secrets rather than AWS Secrets Manager.

To enable your code to access secrets from AWS Secrets Manager you will need to

* Make sure AWS Secrets Manager is enabled.
* Create your secrets in AWS Secrets Manager.
* Create an AWS policy granting access to your secrets.
* Bind that policy to the User Flyte Role in your Union.ai data plane.
* Retrieve your secrets from within your workflow code.

## Ensure that AWS Secrets Manager is enabled

The first step is to make sure that AWS Secrets Manager is enabled in your AWS environment.
Contact the Union.ai team if you are unsure.

## Create your secrets

> [!NOTE]
> Secrets must be defined within the same region as your Union.ai data plane.
> For example, if your Union.ai data plane is located in `us-west-2`, ensure that the secrets are also in `us-west-2`.

Create your secrets in **AWS Secrets Manager** (see the [AWS documentation](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html) for details):

* Go to **AWS Secrets Manager**.
* Select **Store a new secret**.
* Under **Choose Secret type**:
  * Select **Other type of secret**.
  * Select **Plaintext** (**Key/value** is not supported).
  * Enter your **secret value**.
  * For **Encryption key,** leave the default setting: `aws/secretmanager`.
  * Select **Next**.
* Under **Configure secret**:
  * For **Secret name**, enter a string (this string will form part of the `SECRET_KEY` that you will use to access your secret from within your code).
  * Select **Next**.
* Under **Configure rotation** adjust the settings if needed, or skip the section if not. Then select **Next**.
* Under **Review** check that everything is correct and then select **Store**.

## Get the secret ARN

Once you have created a secret, navigate to **AWS Secrets Manager > Secrets** and select the secret you just created.
From there select **Secret ARN** and record the ARN.
Do this for each secret that you create.

A secret ARN looks like this:

```bash
arn:aws:secretsmanager:<Region>:<AccountId>:secret:<SecretName>-<SixRandomCharacters>
```

> [!NOTE]
> You will need your secret ARN when you access your secret from within your code.
> Specifically, you will need to divide it into two strings:
>
> * **`SECRET_GROUP`**: The part of the ARN up to and including `:secret:`
> Above, it is `arn:aws:secretsmanager:<Region>:<AccountId>:secret:`.
>
> * **`SECRET_KEY`**: The part of the ARN after `:secret:`
> Above, it is `<SecretName>-<SixRandomCharacters>`.
>
> See [Using AWS secrets in your code](./enabling-aws-secrets-manager#using-aws-secrets-in-your-task-code) for details on how these are used.

## Create a policy providing access to your secrets

To provide access to your newly created secrets in your code, you will first need to create a policy that grants read access to those secrets:

* Go to **IAM > Access management > Policies**.
* Select **Create Policy**.
* Open the **JSON** tab and paste in the following definition:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:<Region>:<AccountId>:secret:*"
    }
  ]
}
```

> [!NOTE]
> The`Resource`entry takes a wildcard string that must match the ARNs of the secrets in your environment that you want to grant access to.
> This can be all the secrets in your environment (as shown above) or some subset (achieved by making the wildcard match more specific).
> Be sure to substitute the appropriate`<Region>`and`<AccountNumber>`.

* Select **Next: Tags** and add tags if you wish.
* Select **Next: Review** and enter a **Name** for the policy
* Select **Create Policy**.
* Find your newly created policy in the policy list that comes up next and select it.
* Record the **Policy Name** and **Policy ARN** of your newly created policy.
It should be at the top of the policy summary page.
We will refer to the name as `<SecretManagerPolicyName>` and the ARN as `<SecretManagerPolicyArn>`.

> [!NOTE]
> Alternatively, you can create the policy from the command line like this (remember to substitute the`<Region>`and`<AccountId>`appropriately):
>
> ```bash
> $ aws iam create-policy \
>       --policy-name <YourPolicyName> \
>       --policy-document \
>       { \
>         "Version": "2012-10-17", \
>         "Statement": [ \
>           { \
>             "Effect": "Allow", \
>             "Action": "secretsmanager:GetSecretValue", \
>             "Resource": "arn:aws:secretsmanager:<Region>:<AccountId>:secret:*" \
>           } \
>         ]\
>       }
> ```

## Bind the policy to the User Flyte Role

To grant your code the permissions defined in the policy above, you must bind that policy to the `<UserFlyteRole>` used in your Union.ai data plane.
The precise name of this role differs by organization.
You will need this name as well as the ARN of the policy (`<SecretManagerPolicyArn>`, above) to perform the binding.
See **BYOC deployment > Enabling AWS resources > Enabling AWS Secrets Manager** for directions. Once the binding is done, your secrets are now accessible from within your Flyte code.

## Using AWS secrets in your task code

To use an AWS secret in your task code, do the following:

* Define a `Secret` class using the `SECRET_GROUP` and `SECRET_KEY` derived from the secret ARN, above, and pass it in the `secret_requests` parameter of the `@union.task` decorator.
* Inside the task code, retrieve the value of the secret with a call to\
  `union.current_context().secrets.get(SECRET_GROUP, SECRET_KEY)`.

Here is an example:

```python
import union

SECRET_GROUP = "arn:aws:secretsmanager:<Region>:<AccountId>:secret:"
SECRET_KEY = "<SecretName>-<SixRandomCharacters>"
SECRET_REQUEST = union.Secret(
  group=SECRET_GROUP,
  key=SECRET_KEY,
  mount_requirement=union.Secret.MountType.FILE
)

@union.task(secret_requests=[SECRET_REQUEST])
def t1():
    secret_val = union.current_context().secrets.get(
        SECRET_GROUP,
        group_version=SECRET_GROUP_VERSION
    )
    # do something with the secret. For example, communication with an external API.
    ...
```

> [!WARNING]
> Do not return secret values from tasks, as this will expose secrets to the control plane.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/enabling-gcp-resources ===

# Enabling GCP resources

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

Components of your Union.ai data plane will need to connect to and communicate with other resources in your cloud environment such as **BYOC deployment > Enabling GCP resources > Enabling Google Cloud Storage**, **BYOC deployment > Enabling GCP resources > Enabling Google Artifact Registry**, **BYOC deployment > Enabling GCP resources > Enabling BigQuery**, and so forth.

> [!NOTE] Secret management
> We strongly recommend using the **Configure tasks > Secrets** to manage secrets rather than Google Secret Manager. If your organization must use Google Secret Manager, however, see **BYOC deployment > Enabling GCP resources > Enabling Google Secret Manager**.

As much as possible, access to the resources you need will be pre-configured by the Union.ai team when they set up your data plane.
For example, if you want your task code to have access to a specific Cloud Storage bucket or BigQuery, this can be pre-configured.
**You just have to inform the team of your specific requirements before the setup process begins**.

As your projects evolve, your needs may change.
You can always contact the Union.ai team for help enabling additional resources as required.

**There are also some cases where you may want to configure things on your own.**
**Below we give a general overview of these self-configuration options.**
**The sub-pages of this section give examples for specific resources.**

## Types of access

Broadly speaking, there are two categories of access that you are likely to have to deal with:

* **Infrastructure access**:
  Enabling access to a resource for your data plane infrastructure.
  The most common case occurs when you are using Artifact Registry for your task container images and it resides in a project other than the one containing your data plane.
  In that case, some configuration is required to enable the Union.ai operator on your data plane to pull images from the registry when registering your workflows and tasks.
  **If you are using an Artifact Registry instance within the same project as your data plane, then access is enabled by default and no further configuration is needed.**
* **Task code access**:
  Enabling access to a resource for your task code.
  For example, your task code might need to access Cloud Storage or Secret Manager at runtime.
  This involves granting permission to a Google Service Account (GSA) that is attached to the Kubernetes cluster within which your task code runs.

## Infrastructure-level access

The only infrastructure-level access issue you are likely to encounter is around access to an Artifact Registry _in a GCP project other than the one in which your data plane resides_.

**If your task container images are stored in an Artifact Registry in the same GCP project as your data plane, then access is already enabled. You do not have to do anything.**

If your task container images reside in an Artifact Registry instance in **another GCP project** you will need to configure that instance to allow access from your data plane.
See Enabling Artifact Registry for details.

## Task code access

When your task code runs, it executes within a pod in the Kubernetes cluster in your data plane.
To enable your task code to access cloud resources you must grant the appropriate permissions to the Google Service Account (GSA) attached to the Kubernetes cluster.

There are two main options for setting this up:

* **Domain-scoped access**: With this arrangement, you define the permissions you want to grant to your task code, and those permissions are applied only to a specific domain.
* **Global access**: With this arrangement, you define the permissions you want to grant to your task code, and those permissions are then applied to code in all your projects and domains.

> [!NOTE] GCP only supports scoping by domain
> In AWS-based data planes, scoping by both project _and_ domain is supported.
> However, due to intrinsic architectural constraints, GCP-based data planes only support scoping by domain.

Global access is recommended for most use cases since it is simpler, but if you have a compelling reason to restrict access, then the project-domain-scoped access is available, at the cost of some additional complexity in setup.

> [!NOTE] Relationship with RBAC
> The permissions being discussed here are attached to a domain.
> This is independent of the permissions granted to users and machine applications through Union.ai's role-based access control (see **User management**).
> But, the two types of permissions are related.
>
> For example, for a user (or machine application) to have read access to a Cloud Storage bucket, two things are required:
>
> * The user (or machine application) must have **execute** permission for the project and domain where the code that does the reading resides.
> * The domain must have read permission for the Cloud Storage bucket.

## Domain-scoped access

**Because of the way that GCP works internally, domain-scoped access can only be configured by the Union.ai team.**

Please work directly with the Union.ai team if you have requirements that involve domain-scoped access to cloud resources.

If you need to add or change domain-scoped access after your data plane has been set up, you should also contact the team.

## Globally-scoped access

You can manage the configuration of globally-scoped access to GCP resources yourself without involving the Union.ai team.

In a GCP-based Union.ai data plane, globally-scoped access to resources is mediated by a single Google Service Account (GSA) that is configured as part of the data plane setup.
We refer to it as `<UserFlyteGSA>`.

`<UserFlyteGSA>` is bound to all the pods in your data plane's Kubernetes cluster that run your Flyte code.

To enable access to a resource in GCP you grant `<UserFlyteGSA>`access to that resource and assign it a role that includes the permissions that you want your code to have.

> [!NOTE] `<UserFlyteGSA>`
> Here we refer to the default global-access GSA as`<UserFlyteGSA>`because the precise name differs across installations.
> This GSA is identified by name and email of the following form:
>
> * Name: `<OrgName>-userflyterol-<Suffix>`
> * Email: `<OrgName>-userflyterol-<Suffix>@<OrgName>-gcp-dataplane.iam.gserviceaccount.com`

> [!NOTE] Google Service Account (GSA)
> We use the term Google Service Account (GSA) to refer to the accounts that are managed in the GCP console under **IAM & Admin > Service Accounts**.
> This is to distinguish them from Kubernetes Service Accounts (KSAs).
> KSAs are a distinct type of service account managed _within_ the Kubernetes cluster. You will not normally encounter these at the data plane level.

## Find the actual name of `<UserFlyteGSA>`

In this section we refer to the default global-access GSA as`<UserFlyteGSA>`because the precise name differs across installations. The actual name and email of this GSA have the following forms:

* Name: `<OrgName>-userflyterol-<Suffix>`
* Email: `<OrgName>-userflyterol-<Suffix>@<OrgName>-gcp-dataplane.iam.gserviceaccount.com`

**You will need to have the email identifier of this role on hand when you enable access to resources for your task code.**

To find the actual name of this GSA do the following:

* In the GCP data plane project, go to **IAM & Admin > Service accounts**.
* In the list of service account, find the one whose name and email match the pattern above. For example:

![](../../../_static/images/user-guide/integrations/enabling-gcp-resources/user-flyte-gsa.png)

* Copy this name to document in an editor.
  You will need it later to configure each specific resource.

## Subpages
- **BYOC deployment > Enabling GCP resources > Enabling Google Cloud Storage**
- **BYOC deployment > Enabling GCP resources > Enabling Google Artifact Registry**
- **BYOC deployment > Enabling GCP resources > Enabling Google Secret Manager**
- **BYOC deployment > Enabling GCP resources > Enabling BigQuery**


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/enabling-gcp-resources/enabling-google-cloud-storage ===

# Enabling Google Cloud Storage

For Union.ai customers whose data plane is in GCP, we walk through setting up access to your own Google Cloud Storage bucket.

> [!NOTE] Google Cloud Storage in the Union.ai environment
> Your data plane is set up with a Kubernetes cluster and other resources.
> Among these are a number of Google Cloud Storage (GCS) buckets used internally by the Union.ai operator running in the cluster (see [Platform architecture](../platform-architecture)) to store things like workflow metadata.
>
> **These are not the GCS buckets we are talking about in this section.**
>
> **We are discussing the case where you have **_**your own GCS bucket**_** that you set up to store input and output data used by your workflows.**

## Grant `<UserFlyteGSA>` access to the bucket

To enable access to a GCS bucket you have to add the `<UserFlyteGSA>` Google Service Account as a principal to that bucket and assign it a role that includes the permissions that you want your code to have.

* Find the actual name and email of the `<UserFlyteGSA>` in your Union.ai data plane GCP project (See [Find the actual name of `<UserFlyteGSA>`](_index#find-the-actual-name-of-userflytegsa))
* Go to **Cloud Storage > Buckets** and select the bucket to which you want to grant access.
* In the **Bucket details** view select the **Permissions** tab and then select **GRANT ACCESS**:

![](../../../_static/images/user-guide/integrations/enabling-gcp-resources/enabling-google-cloud-storage/bucket-details.png)

* In the **Grant access** panel:
  * Under **Add principals**, paste the actual name (in email form) of the `<UserFlyteGSA>` into the **New principals** field.
  * Under **Assign roles** add as many roles as you need.
    In the example below we add the roles enabling reading and writing: **Storage Object Viewer** and **Storage Object Creator**.

![](../../../_static/images/user-guide/integrations/enabling-gcp-resources/enabling-google-cloud-storage/grant-access-to-bucket.png)

* Click **SAVE**.

Your bucket should now be **globally accessible** to task code in all Flyte projects and domains in your Union.ai organization.

> [!NOTE] Domain-scoped permissions are not self-service
> If you want to assign permissions in a more fine-grained way, per project and/or domain, you need to contact the Union.ai team.
> See [Domain-scoped access](_index#domain-scoped-access).


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/enabling-gcp-resources/enabling-google-artifact-registry ===

# Enabling Google Artifact Registry

## Access to Artifact Registry in the same project is enabled by default

When registering tasks and workflows, the Union.ai infrastructure in your data plane must have access to the container registry that holds the task container images you will be using.
If your data plane is on GCP then you may want to use Google Artifact Registry (GAR) to store these images.

**In most cases, you will be using a GAR repository in the same GCP project as your data plane.**
**If this is the case, then you do not need to configure anything.**
**Access to GAR in the same project is enabled by default.**

## Enabling cross-project access to Artifact Registry

If you want to store your task container images in a GAR repository in a GCP project _other than the one that holds your data plane_, you must enable the node pool of your data plane to access that GAR.
This is the infrastructure-level access that we discussed [earlier](_index#infrastructure-level-access).
It is mediated by the a specific Google Service Account (GSA) which we will refer to here as `<FlyteWorkerGSA>`
(recall that this is in contrast to the task code access, which is mediated by a different default GSA, `<UserFlyteGSA>`).

> [!NOTE] `<FlyteWorkerGSA>`
> Here we refer to the default global-access GSA as`<FlyteWorkerGSA>`because the precise name differs across installations.
> This GSA is identified by name and email of the following form:
>
> * Name: `<OrgName>-flyteworker-<Suffix>`
> * Email: `<OrgName>-flyteworker-<Suffix>@<OrgName>-gcp-dataplane.iam.gserviceaccount.com`

To enable access to the GAR repository in the other account, do the following:

* In your data plane GCP project, go to **IAM > Service Accounts**.
  Find the GSA `<FlyteWorkerGSA>` and copy its email.
  We will call this `<FlyteWorkerGSAEmail>`.
* In the other GCP project account (the one that contains the GAR instance), go to **Artifact Registry > Repositories**.
* Find the GAR repository you want to enable and select the checkbox beside it.
* Under **Permissions** in the side panel, select **Add Principal**.
* Specify the `<FlyteWorkerGSAEmail>` as a **Principal** and assign (at least) the role **Artifact Registry Reader**.
* Select **Save**.

Your Union.ai data plane infrastructure should now be able to pull images from the GAR repository.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/enabling-gcp-resources/enabling-google-secret-manager ===

# Enabling Google Secret Manager

> [!NOTE]
> This documentation exists for customers who must use Google Secret Manager for organizational reasons. For everyone else, we strongly recommend using the
> [Union.ai secrets manager](../../../user-guide/task-configuration/secrets) to manage secrets rather than Google Secret Manager.

Access to a secret stored in Secret Manager in the same GCP project as the data plane is enabled by default.
All you need to do is:

* Create your secrets in Secret Manager.
* Retrieve your secrets from within your task code.

To access a secret stored in Secret Manager in a GCP project _other than the one that holds your data plane_ requires one additional step:
Granting the `<UserFlyteGSA>` (see **BYOC deployment > Enabling GCP resources > Enabling Google Secret Manager**) access to top the secret in the other projects.

## Create your secrets

Create your secrets in **Secret Manager** (see the [Secret Manager documentation](https://cloud.google.com/secret-manager/docs) for details):

* Go to **Security > Secret Manager**.
* Select **CREATE SECRET** at the top of the page.
* Fill in the **Name**, **Value,** and (optionally) the other parameters.
* Select **CREATE SECRET** at the bottom of the page.

Your secret should now be on the secrets list:

![](../../../_static/images/user-guide/integrations/enabling-gcp-resources/enabling-google-secret-manager/secret-manager.png)

Above we see a secret named `example-secret`.
Clicking on it will bring us to the **Secret details** page:

![](../../../_static/images/user-guide/integrations/enabling-gcp-resources/enabling-google-secret-manager/secret-details.png)

The secret has three important identifiers:

* The **GCP secret name**, in this case `example-secret`.
  You will need this if you are accessing a secret in the same project as your data plane.
* The **GCP secret path**, in this case `projects/956281974034/secrets/example-secret`.
  You will need this if you are accessing a secret in a different project from your data plane project.
* The **GCP secret version**, in this case `1`.
  This is required for both same- and cross-project cases.

## Same-project secrets

If your secret is stored in the Secret Manager of the same project as your data plane then the `<UserFlyteGSA>` will have access to it out-of-the-box.
No further configuration is necessary.

To use a same-project GCP secret in your task code, do the following:

* Define a `Secret` object where
  * `Secret.group` is the **GCP secret name**, in this case `example-secret`(optionally, you can use the **GCP secret path** instead, but the simple name is sufficient).
  * `Secret.group_version` is the **GCP secret version** (in this case `1`)
  * `Secret.mount_requirement` is `Secret.MountType.FILE`
* Pass that `Secret` object in the `secret_requests` parameter of the `@union.task` decorator.
* Inside the task code, retrieve the value of the secret with a call to
  `union.current_context().secrets.get(SECRET_GROUP, group_version=SECRET_GROUP_VERSION)`.

Here is an example:

```python
import union

SECRET_GROUP = "example-secret"
SECRET_GROUP_VERSION = "1"
SECRET_REQUEST = Secret(
            group=SECRET_GROUP,
            group_version=SECRET_GROUP_VERSION,
            mount_requirement=union.Secret.MountType.FILE
        )

@union.task(secret_requests=[SECRET_REQUEST])
def t1():
    secret_val = union.current_context().secrets.get(
        SECRET_GROUP,
        group_version=SECRET_GROUP_VERSION
    )
```

## Cross-project secrets

If your secret is stored in the Secret Manager of a project other than the one containing your data plane, then you will first need to grant the `<UserFlyteGSA>` permission to access it:

* Find the **email identifier** of the `<UserFlyteGSA>` in your data plane GCP project (see **BYOC deployment > Enabling GCP resources > Enabling Google Secret Manager** for details).
* Go to **Security > Secret Manager** in the GCP project that contains your secret.
* Select the secret that you want to access and select **GRANT ACCESS**.
* In the subsequent panel, under **Add principals**, paste in the email identifier of the `<UserFlyteGSA>` that you found above.
* Under **Assign roles** add at least the role **Secret Manager Secret Accessor**.
* Save the changes.

At this point, your task code will have access to the secret in the other project. To use that secret in your task code, do the following:

* Define a `union.Secret` object where
  * `union.Secret.group` is the **GCP secret path** (in this case, `projects/956281974034/secrets/example-secret`)
  * `union.Secret.group_version` is the **GCP secret version** (in this case `1`)
  * `union.Secret.mount_requirement` is `union.Secret.MountType.FILE`
* Pass that `union.Secret` object in the `secret_requests` parameter of the `@union.task` decorator.
* Inside the task code, retrieve the value of the secret with a call to\
`union.current_context().secrets.get(SECRET_GROUP, group_version=SECRET_GROUP_VERSION)`

> [!NOTE] GCP secret name vs GCP secret path
> In your task code, the only difference between using a same-project secret and a cross-project secret is
>
> * With a _same-project secret,_ you can use either the **GCP secret name** or the **GCP secret path** as the value of the parameter `union.Secret.group`.
> * With a _cross-project secret,_ you must use the **GCP secret path** as the value of the parameter `union.Secret.group`.

Here is an example:

```python
import union

SECRET_GROUP = "projects/956281974034/secrets/example-secret"
SECRET_GROUP_VERSION = "1"
SECRET_REQUEST = union.Secret(
            group=SECRET_GROUP,
            group_version=SECRET_GROUP_VERSION,
            mount_requirement=union.Secret.MountType.FILE
        )

@union.task(secret_requests=[SECRET_REQUEST])
def t1():
    secret_val = union.current_context().secrets.get(
        SECRET_GROUP,
        group_version=SECRET_GROUP_VERSION
    )
    # do something with the secret. For example, communication with an external API.
    ...
```

> [!WARNING]
> Do not return secret values from tasks, as this will expose secrets to the control plane.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/enabling-gcp-resources/enabling-bigquery ===

# Enabling BigQuery

For customers using the Google Cloud Platform as the data plane, Union.ai lets you easily pull data from BigQuery into your workflows. For most users on GCP, access to BigQuery should be enabled by default and bound to the service account used by the BigQuery connector.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/enabling-azure-resources ===

# Enabling Azure resources

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

Components of your Union.ai data plane will need to connect to and communicate with other resources in your Azure cloud environment, such as Azure [Blob Storage](https://azure.microsoft.com/en-ca/products/storage/blobs/) and [Container Registry](https://azure.microsoft.com/en-us/products/container-registry).

**BYOC deployment > Data plane setup on Azure** provides Union.ai with the necessary permissions to manage underlying Azure resources within your data plane. Access to non-Union.ai Azure resources is subject to Azure limitations and will require additional configuration.

As your projects evolve, your needs may change.
You can always contact the Union.ai team for help enabling additional resources as required.

## Types of access

There are two categories of access that you are likely to have to deal with:

* **Infrastructure access**:
  Enabling access to a resource for your data plane infrastructure.
  The most common case occurs when using your container registry task container images.
  In that case, refer to **BYOC deployment > Enabling Azure resources > Enabling Azure Container Registry (ACR)** to configure the Union.ai data plane to access that registry.
* **Task code access**:
  Enabling access to a resource for your task code.
  For example, your task code might need to access Azure Blob Storage at runtime.
  This involves granting permission to the [User-assigned managed identity](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview) attached to the Kubernetes cluster within which your task code runs.

## Infrastructure-level access

Infrastructure access with non-Union.ai-managed Azure resources will require additional configuration. Refer to **BYOC deployment > Enabling Azure resources > Enabling Azure Container Registry (ACR)** if you need access to images within an existing or non-Union.ai-managed container registry.

## Task code access

Union.ai tasks run within a Union.ai-managed Kubernetes pod in your data plane. Union.ai uses [Microsoft Entra Workload ID](https://learn.microsoft.com/en-us/azure/aks/workload-identity-overview?tabs=dotnet) to create user-assigned managed identities and access Union.ai-managed Azure resources. Additional permissions can be granted to the user-assigned managed identity to access Azure resources within the same Tenant.

Union.ai on Azure has two types of access arrangements:

* **Domain-scoped access**: With this arrangement, you define permissions you want to grant to your tasks, which are applied only to a specific Union.ai domain.
* **Global access**: With this arrangement, you define permissions you want to grant to your tasks, which are applied to an entire Azure subscription or resource group.

> [!NOTE] Azure only supports scoping by domain
> In AWS-based data planes, scoping by both project _and_ domain is supported.
> However, due to intrinsic architectural constraints, Azure-based data planes only support scoping by domain.

Global access is recommended for most use cases since it is simpler. Still, if you have a compelling reason to restrict access, then the subscription/resource group-domain-scoped access is available at the cost of additional complexity in setup.

> [!NOTE] Relationship with RBAC
> The permissions being discussed here are attached to a domain.
> This is independent of the permissions granted to users and machine applications through Union.ai's role-based access control (see the user management documentation).
> But, the two types of permissions are related.
>
> For example, for a user (or machine application) to have read access to a blob storage container, two things are required:
>
> * The user (or machine application) must have **execute** permission for the project and domain where the code that does the reading resides.
> * The domain must have read permission for the blob storage container.

## Domain-scoped access

**Because of the way that Azure works internally, domain-scoped access can only be configured by the Union.ai team.**

Please work directly with the Union.ai team if you have requirements that involve domain-scoped access to cloud resources.

## Globally-scoped access

Union.ai creates a managed identity prefixed with `flyteuser` within the resource group that contains the other Union.ai-managed data plane Azure resources. Navigate to [Azure portal Managed Identities](https://portal.azure.com/#view/HubsExtension/BrowseResource/resourceType/Microsoft.ManagedIdentity%2FuserAssignedIdentities) to find respective managed identity details.

Follow [Azure's official assigned roles documentation](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal) to assign an appropriate role to scope.

## Subpages
- **BYOC deployment > Enabling Azure resources > Enabling Azure Blob Storage**
- **BYOC deployment > Enabling Azure resources > Enabling Azure Container Registry (ACR)**
- **BYOC deployment > Enabling Azure resources > Enabling Azure Key Vault**


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/enabling-azure-resources/enabling-azure-blob-storage ===

# Enabling Azure Blob Storage

For Union.ai customers whose data plane is in Azure, we walk through setting up access to your own Azure Blob Storage container.

> [!NOTE] Azure Blob Storage in the Union.ai environment
> Your data plane is set up with a Kubernetes cluster and other resources.
> Among these are a number of Azure Storage containers used internally by the Union.ai operator running in the cluster (see [Platform architecture](../platform-architecture)) to store things like workflow metadata.
>
> **These are not the Azure Blob Storage containers we are talking about in this section.**
>
> **We are discussing the case where you have **_**your own Azure Blob Storage container**_**that you set up to store input and output data used by your workflows.**

## Providing permissions to Azure Blob Storage container

Union.ai data plane tasks employ Azure Workload Identity Federation to access Azure resources using an Azure user-assigned identity. Access to Azure Blob Storage containers requires updating permissions to permit this Union.ai-managed user-assigned identity.

### Union.ai-managed permissions

The simplest, most flexible approach is to provide Union.ai the ability to add roles assignments against the blob storage container. [Create a role assignment](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal) to allow Union.ai to assign roles to the blob storage container. These permissions should be scoped to the target container. Follow these steps to set up the required access:

1. Navigate to the Azure portal and locate the target storage container.
2. In the storage container's access control (IAM) section, create a new role assignment.
3. For the 'Assigned to' field, select the Union.ai application's service principal.
4. For the 'Role' field, you have two options:
  * Simplest approach: Assign the built-in Azure role `User Access Administrator`.
  * Advanced approach: Create a custom role with the following specific permissions:
    * `Microsoft.Authorization/roleAssignments/write`
    * `Microsoft.Authorization/roleAssignments/delete`
    * `Microsoft.Authorization/roleAssignments/read`
    * `Microsoft.Authorization/roleDefinitions/read`
5. Ensure the 'Scope' is set to the target blob storage container.
6. Complete the role assignment process.
7. Provide the blob storage container [resource ID](https://learn.microsoft.com/en-us/dotnet/api/microsoft.azure.management.storage.models.resource.id) to Union.ai support.

### Manage permissions directly

Managing permissions directly is required if it is not desirable to grant role assigning permissions to Union.ai. [Create a role assignment](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal)) assigning the `Storage Blob Data Contributor` role to the `userflyterole` user assigned identity scoped the blob storage container.

> [!NOTE] Union.ai managed user-assigned identities
> Refer to [Azure portal&#39;s user assigned managed identitites](https://portal.azure.com/#view/HubsExtension/BrowseResource/resourceType/Microsoft.ManagedIdentity%2FuserAssignedIdentities) if assistance is required identifying the `userflyterole` user assigned managed identity within the same resource group as the Union.ai data plane.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/enabling-azure-resources/enabling-azure-container-registry ===

# Enabling Azure Container Registry (ACR)

ACR can be used to store container images within Azure and accessed within your Azure-based Data Plane.

Union.ai leverages Azure Kubernetes Service (AKS) managed identities to authenticate with ACR.

Refer to [Azure documentation for more details](https://learn.microsoft.com/en-us/azure/container-registry/authenticate-kubernetes-options)

## Creating a container registry

### Creating a container registry outside of Union.ai

ACR instances that allow anonymous (I.E., public) access doesn't require additional configuration. Otherwise, the underlying AKS cluster must be granted permissions to pull from the container registry.

Private ACR for Union.ai images is only supported for ACRs within the same tenant as the Union.ai data plane. Refer to [Azure documentation](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-get-started-portal?tabs=azure-cli) for creating Container Registries.

### Creating a Union.ai-managed container registry

Upon request, Union.ai can create a container registry within your data plane.

By default this Union.ai-managed ACR instance:

* Will be created within the same subscription and resource group of the Azure Kubernetes cluster instance.
* Union.ai will create necessary permissions for the Azure Kubernetes cluster to pull images from the container registry.
* Container registry will be created with **Basic** service tier.
* In order to mitigate excessive storage costs, Union.ai creates a weekly [scheduled container registry task](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tasks-scheduled) to [purge](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-auto-purge#use-the-purge-command) **all** images with last modified dates older then 7 days. As a symptom, some 7 day old images will be rebuilt.

Upon request, Union.ai can:

* Configure the [Container Registry service tier](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-skus).
* Disable the purge task to prevent automated image delettion.
* Configure the purge task to run daily, weekly, and monthly deleting tasks with last modified dates older then 1, 7, and 30 days respectively.
* Configure a [regexp2 with RE2 compatiblity](https://github.com/dlclark/regexp2) regular expression to filter for which repository to purge. For example, `^(?!keep-repo).*` will keep all images with repositories prefixed with keep-repo, E.G., `<CONTAINER_REGISTRY_NAME>/keep-repo/my-image:my-tag>`.

Union.ai will provide the created container registry Name and Login server for Docker authentication.

## Enable access to ACR in a different subscription within the same Azure tenant

Union.ai data plane resources will require permissions to pull images from your container registry.

### Allow Union.ai to manage permissions

The simplest, most flexible approach is to provide Union.ai the ability to add roles assignments against the container registry. [Create a role assignment](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal) to allow Union.ai to assign roles to the container registry. These permissions should be scoped to the target container registry. Follow these steps to set up the required access:

1. Navigate to the Azure portal and locate the target container registry.
2. In the container registry's access control (IAM) section, create a new role assignment.
3. For the 'Assigned to' field, select the Union.ai application's service principal.
4. For the 'Role' field, you have two options:
    * Simplest approach: Assign the built-in Azure role `User Access Administrator`.
    * Advanced approach: Create a custom role with the following specific permissions:
      * `Microsoft.Authorization/roleAssignments/write`
      * `Microsoft.Authorization/roleAssignments/delete`
      * `Microsoft.Authorization/roleAssignments/read`
      * `Microsoft.Authorization/roleDefinitions/read`
5. Ensure the 'Scope' is set to the target container registry.
6. Complete the role assignment process.
7. Provide the container registry [resource ID](https://learn.microsoft.com/en-us/dotnet/api/microsoft.azure.management.storage.models.resource.id) to Union.ai support.

### Manage permissions directly

Managing permissions directly is required if it is not desirable to grant role assigning permissions to Union.ai. [Create a role assignment](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal) assigning the `AcrPull` role to the underlying AKS cluster kubelet service principal ID. The service principal ID can be provided by Union.ai support.

Note, this process needs to be repeated every time the underlying Kubernetes cluster is changed or a new cluster is added.

## Enable access to ACR in a different Azure tenant

Please contact and work directly with Union.ai support.

## References

* [Azure - Authenticate with Azure Container Registry (ACR) from Azure Kubernetes Service (AKS)](https://learn.microsoft.com/en-us/azure/aks/cluster-container-registry-integration?toc=%2Fazure%2Fcontainer-registry%2Ftoc.json&bc=%2Fazure%2Fcontainer-registry%2Fbreadcrumb%2Ftoc.json&tabs=azure-cli)
* [Azure - Pull images from a container registry to an AKS cluster in a different Microsoft Entra tenant](https://learn.microsoft.com/en-us/azure/container-registry/authenticate-aks-cross-tenant)


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/enabling-azure-resources/enabling-azure-key-vault ===

# Enabling Azure Key Vault

> [!NOTE]
> This documentation exists for customers who must use Azure Key Vault for organizational reasons. For everyone else, we strongly recommend using the
> [Union.ai secrets manager](../../../user-guide/task-configuration/secrets) to manage secrets rather than Azure Key Vault.

The Union.ai-managed `userflyterole` identity must be granted permission to access [Azure Key Vault secrets](https://learn.microsoft.com/en-us/azure/key-vault/secrets/about-secrets).

> [!NOTE] Managing Azure Key Vault secrets
> Refer to [Azure official documentation](https://learn.microsoft.com/en-us/azure/key-vault/secrets/quick-create-portal) for details on creating and managing secrets.

## Providing permissions to Azure Key Vault

Union.ai data plane tasks employ Azure Workload Identity Federation to access Azure resources using an Azure user-assigned identity. Access to Azure Key Vault containers requires updating permissions to permit this Union.ai-managed user-assigned identity.

[Create a role assignment](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal) assigning the `Key Vault Secrets User` role to the `userflyterole` user-assigned identity. Make sure it is scoped to the Azure Key Vault Secret.

> [!NOTE] Union.ai managed user-assigned identities
> Refer to [Azure portal's user assigned managed identitites](https://portal.azure.com/#view/HubsExtension/BrowseResource/resourceType/Microsoft.ManagedIdentity%2FuserAssignedIdentities) if assistance is required identifying the `userflyterole` user-assigned identity within the Union.ai data plane resource group.

## Accessing the secret within Union.ai

* Define a `Secret` object where
  * `Secret.group` is the a HTTP URI of the format `https://<KEY_VAULT_NAME>.vault.azure.net/secrets/<SECRET_NAME>`
  * `Secret.group_version` can be omitted to retrieve the latest version or set to an explicit secret version
  * `Secret.mount_requirement` is `Secret.MountType.FILE`
* Pass that `Secret` object in the `secret_requests` parameter of the `@union.task` decorator.
* Inside the task code, retrieve the value of the secret with:
  * `union.current_context().secrets.get(<SECRET_NAME>)` if `Secret.group_version` was omitted.
  * `union.current_context().secrets.get(<SECRET_NAME>, group_version=SECRET_GROUP_VERSION)` if `Secret.group_version` was specified.

Here are examples:

```python
import union

VAULT_NAME = "examplevault"
SECRET_NAME = "example-secret"

SECRET_GROUP = f"https://{VAULT_NAME}.vault.azure.net/secrets/{SECRET_NAME}"
SECRET_GROUP_VERSION = "12345"

SECRET_REQUEST_WITH_VERSION = union.Secret(
  group=SECRET_GROUP,
  group_version=SECRET_GROUP_VERSION,
  mount_requirement=union.Secret.MountType.FILE
)

@union.task(secret_requests=[SECRET_REQUEST_WITH_VERSION])
def task_with_versioned_secret():
    secret_val = union.current_context().secrets.get(
        SECRET_NAME,
        group_version=SECRET_GROUP_VERSION
    )

SECRET_REQUEST_FOR_LATEST = union.Secret(
  group=SECRET_GROUP,
  mount_requirement=union.Secret.MountType.FILE
)

@union.task(secret_requests=[SECRET_REQUEST_FOR_LATEST])
def task_with_latest_secret():
    secret_val = union.current_context().secrets.get(
        SECRET_NAME
    )
```


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/single-sign-on-setup ===

# Single sign on setup

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

Union.ai authentication uses OAuth2 with Okta and supports SAML and OIDC-compliant identity providers (IdP) to configure single sign on (SSO).

To enable SSO, create an app for your preferred identity provider and provide the associated secrets to the Union.ai team.
The team will then complete the process.

## Google OpenID Connect

To configure Google OpenID Connect, see **BYOC deployment > Single sign on setup > Google OpenID Connect**.

## Microsoft Entra ID (formerly Azure AD)

To configure Entra ID (Azure AD), see **BYOC deployment > Single sign on setup > Microsoft Entra ID (formerly Azure AD)**.

## Other identity providers

To configure other identity providers, see **BYOC deployment > Single sign on setup > Other identity providers**.

## Subpages
- **BYOC deployment > Single sign on setup > Google OpenID Connect**
- **BYOC deployment > Single sign on setup > Microsoft Entra ID (formerly Azure AD)**
- **BYOC deployment > Single sign on setup > Other identity providers**


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/single-sign-on-setup/google-oidc ===

# Google OpenID Connect

To set up your Union.ai instance to use Google OpenID Connect as the identity provider, follow the directions below.

> [!NOTE] Google Documentation
> In this article, we cover the same steps as in the
> [OpenID Connect](https://developers.google.com/identity/openid-connect/openid-connect) Google documentation,
> but with additional directions specific to Union.ai.

## Setting up OAuth 2.0

First, select an existing project or set up a new project in the
[Google Cloud Console](https://console.cloud.google.com).

1. Navigate to the **Clients** section for [Google Auth Platform](https://console.cloud.google.com/auth/).

2. Click **CREATE CLIENT**. If this is your first client, you might need to provide additional app details. There is no special configuration needed from the Union.ai side.

3. Under **Create OAuth client ID**, select **Web application** as the application type and assign a name.

4. Under **Authorized redirect URIs**, add an entry with the following callback URI:
   `https://signin.hosted.unionai.cloud/oauth2/v1/authorize/callback`.

5. Click **Create**.

## Obtain OAuth 2.0 credentials

Next, retrieve your credentials: Click on your configured client and copy the values for **Client ID** and **Client secret** to a text file on your computer.

![OAuth 2.0 credentials](../../../_static/images/user-guide/data-plane-setup/single-sign-on-setup/google-oidc/oauth-credentials.png)

## Share the client ID and client secret securely with Union.ai

Finally, you will need to share the client ID and client secret securely with Union.ai:

1. Copy the public key provided by Union.ai here: 📥 [public-key.txt](/_static/public/public-key.txt)

2. Encrypt the given text file on your computer with a PGP tool of your choice.

3. Share the encrypted message with the Union.ai team over Slack.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/single-sign-on-setup/microsoft-entra-id ===

# Microsoft Entra ID (formerly Azure AD)

To set up your Union.ai instance to use Microsoft Entra ID as the identity provider, follow the directions below.

> [!NOTE] Microsoft documentation
> In this article, we cover the same steps as the
> [Quickstart: Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) Microsoft documentation, but with additional directions specific
> to Union.ai.

## Register an Entra ID application

1. Log into your Azure account as a cloud application administrator or higher permission level.

1. In the identity drop down on the top right of the page (indicated by the email you are currently logged in as) select **Switch directory**, then select the directory yin which you want to register this application.

1. Browse to **Identity > Applications > App registrations** and select **New registration**.

1. Under **Name**, enter an appropriate display name. For example, `Union.ai Production`.

1. Under **Supported account types**, select **Accounts in this organizational directory only**.

1. Under **Redirect URI (optional)**, select **Web** and enter the following URI:

   `https://signin.hosted.unionai.cloud/oauth2/v1/authorize/callback`

1. Click **Register**.

> [!NOTE] Make the app visible to users
> New app registrations are hidden to users by default. You must enable the app when you are ready for
> users to see the app on their **My Apps** page.
> To enable the app, in the Microsoft Entra admin center, navigate to
> **Identity > Applications > Enterprise > applications** and select the app.
> Then, on the **Properties** page, toggle **Visible to users?** to **Yes**.

## Copy the values needed by the Union.ai team

When registration finishes, the Microsoft Entra admin center will display the app registration's **Overview** page, from which you can copy the Application (client) ID, Directory (tenant) ID, and client secret needed by the Union.ai team.

### Application (client) ID and directory (tenant) ID

Copy the **Application (client) ID** and **Directory (tenant) ID** from the overview page to a text file on your computer.

![Application and directory ID](../../../_static/images/user-guide/data-plane-setup/single-sign-on-setup/microsoft-entra-id/entra-id-application-and-directory-id.png)

### Client secret

To get the **client secret**, on the overview page, go to **Client credentials** and click **Add a certificate or secret**.

![Client credentials](../../../_static/images/user-guide/data-plane-setup/single-sign-on-setup/microsoft-entra-id/entra-id-client-credentials.png)

On the subsequent page, under **Client secrets**, click **New client secret** to generate a new secret.
Copy the **Value** of this secret to a plain text file on your computer.

![Client secret](../../../_static/images/user-guide/data-plane-setup/single-sign-on-setup/microsoft-entra-id/entra-id-client-secret.png)

## Share the client secret securely with Union.ai

1. Copy the public key provided by Union.ai here: 📥 [public-key.txt](/_static/public/public-key.txt)

2. Go to [https://pgptool.net](https://pgptool.net/).

3. Click the **Encrypt (+Sign)** tab.

4. Enter public key in **Public Key (For Verification)** section.

5. Skip the **Private Key** section.

6. Enter the **client secret** in plain text and encrypt it.

7. Save encypted text to a file and share with the Union.ai team over Slack.

8. Delete the **client secret** from the text file on your computer.

## Share the IDs with Union.ai

Share the **application (client) ID** and **directory (tenant) ID** with the Union.ai team over Slack.
These values do not have to be encrypted.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/byoc/single-sign-on-setup/other-identity-providers ===

# Other identity providers

Depending on the type of identity provider you are using, open the appropriate directions below on the Okta site:

- [Okta-to-Okta](https://developer.okta.com/docs/guides/add-an-external-idp/oktatookta/main/)

- [OpenID Connect (OIDC)](https://developer.okta.com/docs/guides/add-an-external-idp/openidconnect/main/)

- [SAML 2.0](https://developer.okta.com/docs/guides/add-an-external-idp/saml2/main/)

Now, referencing those directions, follow the steps below:

1. Navigate to the section with the heading **Create an app at the Identify Provider**.

1. Complete all the steps in that section and make a note of the **application (client) ID**.

1. Where a callback URI needs to be specified, use `https://signin.hosted.unionai.cloud/oauth2/v1/authorize/callback`.

1. The last step in the setup will generate the **client secret**. Copy this value to a text file on your computer.
   Make a copy of this value.

## Share the client secret securely with the Union.ai team

1. Copy the public key provided by Union.ai here: 📥 [public-key.txt](/_static/public/public-key.txt)

2. Go to [https://pgptool.net](https://pgptool.net/).

3. Click the **Encrypt (+Sign)** tab.

4. Enter public key in **Public Key (For Verification)** section.

5. Skip the **Private Key** section.

6. Enter the **client secret** in plain text and encrypt it.

7. Save encypted text to a file and share with the Union.ai team over Slack.

8. Delete the client secret from the text file on your computer.

## Share the application (client) ID with Union.ai

Share the **application (client) ID** with the Union.ai team over Slack.
This value does not have to be encrypted.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged ===

# Self-managed deployment

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

In a self-managed deployment, you operate the data plane on your own Kubernetes infrastructure.
Union.ai runs the control plane, but you manage the cluster, upgrades, and operational aspects of the data plane yourself.
Union.ai has no access to your cluster, providing the highest level of data isolation.

## Getting started

1. Review the [architecture](./architecture/_index) to understand the control plane, data plane operators, and security model.
2. Check the **Self-managed deployment > Cluster recommendations** for Kubernetes version, networking, and IP planning requirements.
3. Set up your data plane on your cloud provider:
   - **Self-managed deployment > Data plane setup on generic Kubernetes** (on-premise or any S3-compatible environment)
   - [AWS](./selfmanaged-aws/_index)
   - **Self-managed deployment > Data plane setup on GKE (GCP)**
   - **Self-managed deployment > Data plane setup on Azure**
   - **Self-managed deployment > Data plane setup on OCI**

## Configuration

After initial setup, configure platform features on your cluster:

- **Self-managed deployment > Advanced Configurations > Authentication**
- **Self-managed deployment > Advanced Configurations > Image Builder**
- **Self-managed deployment > Advanced Configurations > Multiple Clusters**
- **Self-managed deployment > Advanced Configurations > Configuring Service and Worker Node Pools**
- **Self-managed deployment > Advanced Configurations > Monitoring**
- **Self-managed deployment > Advanced Configurations > Persistent logs**
- **Self-managed deployment > Advanced Configurations > Data retention policies**
- **Self-managed deployment > Advanced Configurations > Namespace mapping**
- **Self-managed deployment > Advanced Configurations > Secrets**

## Reference

- [Helm chart reference](./helm-chart-reference/_index) for available chart values
- **Self-managed deployment > Architecture > Kubernetes Access Controls** for RBAC configuration details

## Subpages
- **Self-managed deployment > Architecture**
- **Self-managed deployment > Cluster recommendations**
- **Self-managed deployment > Data plane setup on generic Kubernetes**
- **Self-managed deployment > Data plane setup on AWS**
- **Self-managed deployment > Data plane setup on GKE (GCP)**
- **Self-managed deployment > Data plane setup on Azure**
- **Self-managed deployment > Data plane setup on OCI**
- **Self-managed deployment > Advanced Configurations**
- **Self-managed deployment > Helm chart reference**


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/architecture ===

# Architecture

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

This section covers the architecture of the Union.ai data plane.
It provides an overview of the components and their interactions within the system.
Understanding the architecture is crucial for effectively deploying and managing your Union.ai cluster.

## Subpages
- **Self-managed deployment > Architecture > Overview**
- **Self-managed deployment > Architecture > Kubernetes Access Controls**


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/architecture/overview ===

# Overview

The Union.ai architecture consists of two components, referred to as planes — the control plane and the data plane.

![](../../../_static/images/deployment/architecture.svg)

## Control plane

The control plane:
  * Runs within the Union.ai AWS account.
  * Provides the user interface through which users can access authentication, authorization, observation, and management functions.
  * Is responsible for placing executions onto data plane clusters and performing other cluster control and management functions.

## Data plane

Union.ai operates one control plane for each supported region, which supports all data planes within that region. You can choose the region in which to locate your data plane. Currently, Union.ai supports the `us-west`, `us-east`, `eu-west`, and `eu-central` regions, and more are being added.

### Data plane nodes

Worker nodes are responsible for executing your workloads. You have full control over the configuration of your worker nodes. When worker nodes are not in use, they automatically scale down to the configured minimum.

## Union.ai operator

The Union.ai hybrid architecture lets you maintain ultimate ownership and control of your data and compute infrastructure while enabling Union.ai to handle the details of managing that infrastructure.

Management of the data plane is mediated by a dedicated operator (the Union.ai operator) resident on that plane.
This operator is designed to perform its functions with only the very minimum set of required permissions.
It allows the control plane to spin up and down clusters and provides Union.ai's support engineers with access to system-level logs and the ability to apply changes as per customer requests.
It _does not_ provide direct access to secrets or data.

In addition, communication is always initiated by the Union.ai operator in the data plane toward the Union.ai control plane, not the other way around.
This further enhances the security of your data plane.

Union.ai is SOC-2 Type 2 certified. A copy of the audit report is available upon request.

## Registry data

Registry data is comprised of:

* Names of workflows, tasks, launch plans, and artifacts
* Input and output types for workflows and tasks
* Execution status, start time, end time, and duration of workflows and tasks
* Version information for workflows, tasks, launchplans, and artifacts
* Artifact definitions

This type of data is stored in the control plane and is used to manage the execution of your workflows.
This does not include any workflow or task code, nor any data that is processed by your workflows or tasks.

## Execution data

Execution data is comprised of::

* Event data
* Workflow inputs
* Workflow outputs
* Data passed between tasks (task inputs and outputs)

This data is divided into two categories: *raw data* and *literal data*.

### Raw data

Raw data is comprised of:

* Files and directories
* Dataframes
* Models
* Python-pickled types

These are passed by reference between tasks and are always stored in an object store in your data plane.
This type of data is read by (and may be temporarily cached) by the control plane as needed, but is never stored there.

### Literal data

* Primitive execution inputs (int, string... etc.)
* JSON-serializable dataclasses

These are passed by value, not by reference, and may be stored in the Union.ai control plane.

## Data privacy

If you are concerned with maintaining strict data privacy, be sure not to pass private information in literal form between tasks.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/architecture/kubernetes-rbac ===

# Kubernetes Access Controls

## Roles

See the [dataplane helm charts](https://github.com/unionai/helm-charts/tree/main/charts/dataplane) for detailed information about Roles and ClusterRoles.

### Role Permissions Summary

##### `proxy-system-secret`
- Scoped to `union` namespace
- Permissions on secrets: get, list, create, update, delete

##### `operator-system`
- Scoped to `union` namespace
- Permissions on secrets and deployments: get, list, watch, create, update

##### `union-operator-admission` (for webhook)
- Scoped to `union` namespace
- Permissions on secrets: get, create

### ClusterRole Permissions Summary

#### Metrics and Monitoring Roles

##### `release-name-kube-state-metrics`

- **Purpose**: Collects metrics from Kubernetes resources
- **Access Pattern**: Read-only (`list`, `watch`) to numerous resources across multiple API groups
- **Scope**: Comprehensive - covers core resources, workloads, networking, storage, and authentication

##### `prometheus-operator`
- **Access**: Full control (`*`) over Prometheus monitoring resources
- **Key Permissions**:
  - Complete access to monitoring.coreos.com API group resources
  - Full access to statefulsets, configmaps, secrets
  - Pod management (list, delete)
  - Service/endpoint management
  - Read-only for nodes, namespaces, ingresses

##### `union-operator-prometheus`
- **Access**: Read-only access to metrics sources
- **Resources**: nodes, services, endpoints, pods, endpointslices, ingresses
- **Special**: Access to `/metrics` and `/metrics/cadvisor` endpoints

#### Resource Management Roles

##### `clustersync-resource`
- **Access**: Full control (`*`) over core and RBAC resources
- **Resources**:
  - Core: configmaps, namespaces, pods, resourcequotas, secrets, services, serviceaccounts
  - RBAC: roles, rolebindings, clusterrolebindings
- **API Groups**: `""` (core) and `rbac.authorization.k8s.io`

##### `proxy-system`
- **Access**: Read-only (`get`, `list`, `watch`)
- **Resources**: events, flyteworkflows, pods/log, pods, rayjobs, resourcequotas

#### Workflow Management Roles

##### `operator-system`
- **Access**: Full control over Flyte workflows, CRUD for core resources
- **Resources**:
  - Full access to flyteworkflows
  - Management of pods, configmaps, resourcequotas, podtemplates, nodes
  - Access to `/metrics` endpoint

##### `flytepropeller-webhook-role`
- **Access**: Get, create, update, patch
- **Resources**: mutatingwebhookconfigurations, secrets, pods, replicasets/finalizers
##### `flytepropeller-role`
- **Access**: Varied per resource type
- **Key Permissions**:
  - Read-only for pods
  - Event management
  - CRD management
  - Full control over flyteworkflows including finalizers

## Service Access

### `operator/operator-proxy`
Service that provides access to both cluster resources and cloud provider APIs, particularly focused on compute resource management.

#### Kubernetes Resources

##### Core Resources
- Pods: Access via informers to monitor and manage pod lifecycle.
- Nodes: Access to retrieve node information.
- ResourceQuotas: Read access.
- ConfigMaps: Access for configuration management
- Secrets: Access for credentials storage
- Namespaces: Referenced in container/pod identification contexts

##### Custom Resources
- FlyteWorkflows: Management of v1alpha1.FlyteWorkflow resources
- Kueue Resources (optional): Access to ResourceFlavor, ClusterQueue, and other queue resources
- Karpenter NodePools (optional): For AWS-based compute resource management

##### Cloud Provider Resources
- Object Storage: Read/write operations to cloud storage buckets

##### Authentication and Configuration
- OAuth: Uses app ID for authentication with Union cloud services
- Service Account Roles: Configured via UserRoleKey and UserRole
- Cluster Information: Access to cluster metadata and metrics

### `FlytePropeller/PropellerWebhook`
Kubernetes operator that executes Flyte graphs natively on Kubernetes.

#### Kubernetes Resources
- Manages pod creation for executions
- Secret injection

#### Custom Resources
- FlyteWorkflows: Management of v1alpha1.FlyteWorkflow resources


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/cluster-recommendations ===

# Cluster recommendations

Union.ai is capable of running on any Kubernetes cluster.
This includes managed Kubernetes services such as Google Kubernetes Engine (GKE), Azure Kubernetes Service (AKS), and Amazon Elastic Kubernetes Service (EKS), as well as self-managed Kubernetes clusters.

While many configurations are supported, we have some recommendations to ensure the best performance and reliability of your Union deployment.

## Kubernetes Versions

We recommend running Kubernetes versions that are [actively supported by the Kubernetes community](https://kubernetes.io/releases/).  This
typically means running one of the most recent three minor versions.  For example, if the most recent version is 1.32, we recommend
running 1.32, 1.31, or 1.30.

## Networking Requirements

Many Container Network Interface (CNI) plugins require planning for IP address allocation capacity.
For example, [Amazon's VPC CNI](https://docs.aws.amazon.com/eks/latest/userguide/managing-vpc-cni.html) and [GKE's Dataplane v2](https://cloud.google.com/kubernetes-engine/docs/concepts/dataplane-v2)
allocate IP addresses to Kubernetes Pods out of one or more or your VPC's subnets.
If you are using one of these CNI plugins, you should ensure that your VPC's subnets have enough available IP addresses to support the number of concurrent tasks you expect to run.

We recommend using at least a `/16` CIDR range (65,536 addresses), you may optionally subdivide this range into smaller subnets to
support multiple availability zones or other network segmentation requirements.

In short, you should aim to have at least 1 IP address available for each task you expect to run concurrently.

# Performance Recommendations

## Node Pools

It is recommended but not required to use separate node pools for the Union services and the Union worker pods.  This allows you to
guard against resource contention between Union services and other tasks running in your cluster.  You can find additional information
in the [Configuring Node Pools](./configuration/node-pools) section.

# AWS

## S3

Each data plane uses an object store (an AWS S3 bucket, GCS bucket or ABS container) that is used to store data used in the execution of workflows.
As a Union.ai administrator, you can specify retention policies for this data when setting up your data plane 
(learn more [about the different types of data categories](./configuration/data-retention) stored by the data plane.)

Union recommends the use of two S3 buckets:

1. metadata bucket: contains workflow execution data such as Task inputs and outputs, etc
2. fast registration bucket: contain local code artifacts that will be copied into the Flyte task container at runtime when using `union register` or `union run --remote --copy-all`.

Note: You can choose to use a single bucket in your dataplane

### Data Retention

Union recommends using Lifecycle Policy on these buckets to manage the storage costs. See [Data retention policy](./configuration/data-retention) for more information.

## IAM

You will need to enable access to your S3 buckets from the cluster.

1. Update the EKS Node IAM role for your cluster to allow the data plane nodes to use your S3 buckets.
   This can be done by creating and attaching a new IAM policy which enables access to your S3 buckets.
   Use `union-flyte-worker` as the name of the new policy.
   The permissions for the policy will be:

   ```json
   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Sid": "Statement1",
               "Effect": "Allow",
               "Action": [
                   "s3:DeleteObject*",
                   "s3:GetObject*",
                   "s3:ListBucket",
                   "s3:PutObject*"
               ],
               "Resource": [
                   "arn:aws:s3:::<bucket-name>",
                   "arn:aws:s3:::<bucket-name>/*"
               ]
           }
       ]
   }
   ```

2. Attach this policy to your node group IAM role
3. Create an [IAM OIDC provider for your EKS cluster](https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html#_create_oidc_provider_eksctl).
4. Create a new role named `union-flyte-role` to enable applications in a Pod’s containers to make API requests to AWS services using AWS Identity and Access Management (IAM) permissions.

   The Trust Policy for this role will be:

   ```json
   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Principal": {
                   "Federated": "arn:aws:iam::$account_id:oidc-provider/$oidc_provider"
               },
               "Action": "sts:AssumeRoleWithWebIdentity",
               "Condition": {
                   "StringLike": {
                       "$oidc_provider:aud": "sts.amazonaws.com",
                       "$oidc_provider:sub": "system:serviceaccount:*:*"
                   }
               }
           }
       ]
   }
   ```
   where `$account_id` is your AWS account ID and `$oidc_provider` is the OIDC provider you created above.

   You can obtain these values using the AWS CLI:

   ```bash
   aws eks describe-cluster --region $cloud_region --name $cluster_name --query "cluster.identity.oidc.issuer" --output text
   ```

5. Attach the `union-flyte-worker` policy created above to this new role.

## EKS configuration

Union recommends installing the following EKS add-ons:
  - CoreDNS
  - Amazon VPC CNI
  - Kube-proxy

Union supports Autoscaling and the use of spot (interruptible) instances.

# AKS

## Secure access

Union recommends using [Microsoft Entra Workload ID](https://learn.microsoft.com/en-us/azure/aks/workload-identity-overview) to securely access Azure resources.

Ensure your AKS cluster is [enabled as OIDC Issuer](https://learn.microsoft.com/en-us/azure/aks/use-oidc-issuer).

Create a User Assigned Managed Identity with Federated Credentials that map to the following Kubernetes Service Accounts:

**Subject Identifier**

- `system:serviceaccount:<NAMESPACE>:flytepropeller-system`
- `system:serviceaccount:<NAMESPACE>:flytepropeller-webhook-system`
- `system:serviceaccount:<NAMESPACE>:operator-system`
- `system:serviceaccount:<NAMESPACE>:proxy-system`
- `system:serviceaccount:<NAMESPACE>:executor`

Where `<NAMESPACE>` is where you plan to install the Union operator (`union` by default)

Assign the `Storage Blob Data Owner` role to this Identity at the Storage Account level.

### Workers

This is the Identity that the Pods created for each execution will use to access Azure resources. Those Pods use the `default` K8s Service Account on each project-domain namespace, unless otherwise specified.

Create a User Assigned Managed Identity with Federated Credentials that map to the `default` K8s Service Account:

**Subject Identifier**

- `system:serviceaccount:development:default`
- `system:serviceaccount:staging:default`
- `system:serviceaccount:production:default`

Assign the `Storage Blob Data Owner` role to this Identity at the Storage Account level.

## Azure Key Vault
Union ships with an embedded secrets manager. Alternatively, you can enable Union to consume secrets from Azure Key Vault adding the following to your Helm values file:

```yaml
config:

  ## Optional integration with Azure Key Vault secrets manager
  core:
    webhook:
      embeddedSecretManagerConfig:
        enabled: true
        type: Azure
        azureConfig:
          vaultURI: ""https://kv-myorg-prod.vault.azure.net/" #full key vault URI
      secretManagerTypes:
        - Azure
        - Embedded

```
## Node pools

By default, the Union installation request the following resources:

|          | CPU (vCPUs)| Memory (GiB) |
|----------|------------|--------------|
| Requests |          14|          27.1|
| Limits   |          17|            32|

For GPU access, Union injects tolerations and label selectors to execution Pods.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/selfmanaged-generic ===

# Data plane setup on generic Kubernetes

Union.ai’s modular architecture allows for great flexibility and control.
The customer can decide how many clusters to have, their shape, and who has access to what.
All communication is encrypted.
The Union architecture is described on the [Architecture](./architecture/_index) page.

> [!NOTE] These instructions cover installing Union.ai in an on-premise Kubernetes cluster.
> If you are installing at a cloud provider, use the cloud provider specific instructions: [AWS](./selfmanaged-aws/_index), [Azure](./selfmanaged-azure), [OCI](./selfmanaged-oci).

## Assumptions

* You have a Union.ai organization, and you know the control plane URL for your organization. (e.g. https://your-org-name.us-east-2.unionai.cloud).
* You have a cluster name provided by or coordinated with Union.
* You have a Kubernetes cluster, running one of the most recent three minor Kubernetes versions. [Learn more](https://kubernetes.io/releases/version-skew-policy/).
* Object storage provided by a vendor or an S3 compatible platform (such as [Minio](https://min.io)).

## Prerequisites

* Install [Helm 3](https://helm.sh/docs/intro/install/).
* Install [uctl](../../api-reference/uctl-cli/_index).

## Deploy the Union.ai operator

1. Add the Union.ai Helm repo:

   ```bash
   helm repo add unionai https://unionai.github.io/helm-charts/
   helm repo update
   ```

2. Use the `uctl selfserve provision-dataplane-resources` command to generate a new client and client secret for communicating with your Union control plane, provision authorization permissions for the app to operate on the Union cluster name you have selected, generate values file to install dataplane in your Kubernetes cluster and provide follow-up instructions:

   ```bash
   uctl config init --host=<YOUR_UNION_CONTROL_PLANE_URL>
   uctl selfserve provision-dataplane-resources --clusterName <YOUR_SELECTED_CLUSTERNAME>  --provider metal
   ```

   * The command will output the ID, name, and a secret that will be used by the Union services to communicate with your control plane.
     It will also generate a YAML file specific to the provider that you specify, in this case `metal`, meaning "bare metal", or generic:

   ```bash
    -------------- ------------------------------------ ---------------------------- ------------------------------------------------- ------------------------------------------------------------------ ----------
   | ORGANIZATION | HOST                               | CLUSTER                    | CLUSTERAUTHCLIENTID                             | CLUSTERAUTHCLIENTSECRET                                          | PROVIDER |
    -------------- ------------------------------------ ---------------------------- ------------------------------------------------- ------------------------------------------------------------------ ----------
   | xxxxxxxxxxx  | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | xxxxxxxxxxxxxxxxxxxxxxxxxx | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | xxxxx    |
    -------------- ------------------------------------ ---------------------------- ------------------------------------------------- ------------------------------------------------------------------ ----------
   1 rows

   ✅ Generated <ORGNAME>-values.yaml
   ======================================================================
   Installation Instructions
   ======================================================================

   Step 1: Prepare your Kubernetes cluster.

   Step 2: Clone and navigate to helm-charts repository
     git clone https://github.com/unionai/helm-charts && cd helm-charts

   Step 3: Configure your S3-compatible storage endpoint & credentials in the values file

   Step 4: Install the data plane CRDs
     helm upgrade --install unionai-dataplane-crds charts/dataplane-crds

   Step 5: Install the data plane
     helm upgrade --install unionai-dataplane charts/dataplane \
       --namespace union \
       --values <ORGNAME>-values.yaml

   Step 6: Verify installation
     kubectl get pods -n union

   Step 7: Once you have your dataplane up and running, create API keys for your organization. If you have already just call the same command again to propogate the keys to new cluster:
     uctl create apikey --keyName EAGER_API_KEY --org <your-org-name>

   Step 8: You can now trigger v2 executions on this dataplane.
   ```

  * Save the secret that is displayed. Union does not store the credentials, rerunning the same command can be used to show same secret later which stream through the OAuth Apps provider.
  * Create the `EAGER_API_KEY` as instructed in Step 7 of the command output. This step is required for every dataplane you plan to use for V2 executions.

3.  Update the values file correctly:
    For example, `<UNION_FLYTE_ROLE_ARN>` is the ARN of the new IAM role created in the [AWS Cluster Recommendations](./cluster-recommendations#iam)

4. Optionally configure the resource `limits` and `requests` for the different services.
   By default, these will be set minimally, will vary depending on usage, and follow the Kubernetes `ResourceRequirements` specification.

   * `clusterresourcesync.resources`
   * `flytepropeller.resources`
   * `flytepropellerwebhook.resources`
   * `operator.resources`
   * `proxy.resources`

5. Once deployed you can check to see if the cluster has been successfully registered to the control plane:

   ```bash
   uctl get cluster
    ----------- ------- --------------- -----------
   | NAME      | ORG   | STATE         | HEALTH    |
    ----------- ------- --------------- -----------
   | <cluster> | <org> | STATE_ENABLED | HEALTHY   |
    ----------- ------- --------------- -----------
   1 rows
   ```

6. You can then register and run some example workflows through your cluster to ensure that it is working correctly.

   ```bash
   uctl register examples --project=union-health-monitoring --domain=development
   uctl validate snacks --project=union-health-monitoring --domain=development
    ---------------------- ----------------------------------- ---------- -------------------------------- -------------- ----------- ---------------
   | NAME                 | LAUNCH PLAN NAME                  | VERSION  | STARTED AT                     | ELAPSED TIME | RESULT    | ERROR MESSAGE |
    ---------------------- ----------------------------------- ---------- -------------------------------- -------------- ----------- ---------------
   | alskkhcd6wx5m6cqjlwm | basics.hello_world.hello_world_wf | v0.3.341 | 2025-05-09T18:30:02.968183352Z | 4.452440953s | SUCCEEDED |               |
    ---------------------- ----------------------------------- ---------- -------------------------------- -------------- ----------- ---------------
   1 rows
   ```


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/selfmanaged-aws ===

# Data plane setup on AWS

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

To set up your Union.ai data plane on Amazon Web Services (AWS), you provision and manage the compute resources in your own AWS account.

### **Self-managed deployment > Data plane setup on AWS > Manual setup on AWS**

Set up the data plane manually using AWS CloudFormation or the AWS console

## Subpages
- **Self-managed deployment > Data plane setup on AWS > Manual setup on AWS**


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/selfmanaged-aws/manual ===

# Manual setup on AWS

Union.ai's modular architecture allows for great flexibility and control.
The customer can decide how many clusters to have, their shape, and who has access to what.
All communication is encrypted.  The Union architecture is described on the [Architecture](../architecture/_index) page.

## Assumptions

* You have a Union.ai organization, and you know the control plane URL for your organization.
* You have a cluster name provided by or coordinated with Union.
* You have a Kubernetes cluster, running one of the most recent three minor K8s versions.
  [Learn more](https://kubernetes.io/releases/version-skew-policy/)
* You have configured an S3 bucket.
* You have an IAM Role, Trust Policy and OIDC provider configured as indicated in the [AWS section in Cluster Recommendations](../cluster-recommendations#aws) section.

## Prerequisites

* Install [Helm 3](https://helm.sh/docs/intro/install/).
* Install [uctl](../../../api-reference/uctl-cli/_index).

## Deploy the Union.ai operator

1. Add the Union.ai Helm repo:

   ```bash
   helm repo add unionai https://unionai.github.io/helm-charts/
   helm repo update
   ```

2. Use the `uctl selfserve provision-dataplane-resources` command to generate a new client and client secret for communicating with your Union control plane, provision authorization permissions for the app to operate on the union cluster name you have selected, generate values file to install dataplane in your Kubernetes cluster and provide follow-up instructions:

   ```bash
   uctl config init --host=<YOUR_UNION_CONTROL_PLANE_URL>
   uctl selfserve provision-dataplane-resources --clusterName <YOUR_SELECTED_CLUSTERNAME>  --provider aws
   ```

   * The command will output the ID, name, and a secret that will be used by the Union services to communicate with your control plane.
     It will also generate a YAML file specific to the provider that you specify, in this case `aws`:

   ```bash
    -------------- ------------------------------------ ---------------------------- ------------------------------------------------- ------------------------------------------------------------------ ----------
   | ORGANIZATION | HOST                               | CLUSTER                    | CLUSTERAUTHCLIENTID                             | CLUSTERAUTHCLIENTSECRET                                          | PROVIDER |
    -------------- ------------------------------------ ---------------------------- ------------------------------------------------- ------------------------------------------------------------------ ----------
   | xxxxxxxxxxx  | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | xxxxxxxxxxxxxxxxxxxxxxxxxx | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | xxxxx    |
    -------------- ------------------------------------ ---------------------------- ------------------------------------------------- ------------------------------------------------------------------ ----------
   1 rows

   ✅ Generated <ORGNAME>-values.yaml
   ======================================================================
   Installation Instructions
   ======================================================================

   Step 1: Setup the infrastucture on AWS. Our team can share terrform scripts to help with this.

   Step 2: Clone and navigate to helm-charts repository
     git clone https://github.com/unionai/helm-charts && cd helm-charts

   Step 3: Ensure S3 bucket & IAM roles are configured; set role ARN(s) in values

   Step 4: Install the data plane CRDs
     helm upgrade --install unionai-dataplane-crds charts/dataplane-crds

   Step 5: Install the data plane
     helm upgrade --install unionai-dataplane charts/dataplane \
       --namespace union \
       --values <ORGNAME>-values.yaml

   Step 6: Verify installation
     kubectl get pods -n union

   Step 7: Once you have your dataplane up and running, create API keys for your organization. If you have already just call the same command again to propogate the keys to new cluster:
     uctl create apikey --keyName EAGER_API_KEY --org <your-org-name>

   Step 8: You can now trigger v2 executions on this dataplane.
   ```
   * Save the secret that is displayed. Union does not store the credentials, rerunning the same command can be used to show same secret later which stream through the OAuth Apps provider.
   * Create the `EAGER_API_KEY` as instructed in Step 7 of the command output. This step is required for every dataplane you plan to use for v2 executions.

3. Update the values file correctly:
   For example, `<UNION_FLYTE_ROLE_ARN>` is the ARN of the new IAM role created in the [AWS Cluster Recommendations](../cluster-recommendations#iam)

4. Optionally configure the resource `limits` and `requests` for the different services.
   By default, these will be set minimally, will vary depending on usage, and follow the Kubernetes `ResourceRequirements` specification.

   * `clusterresourcesync.resources`
   * `flytepropeller.resources`
   * `flytepropellerwebhook.resources`
   * `operator.resources`
   * `proxy.resources`

5. Once deployed you can check to see if the cluster has been successfully registered to the control plane:

   ```bash
   uctl get cluster
    ----------- ------- --------------- -----------
   | NAME      | ORG   | STATE         | HEALTH    |
    ----------- ------- --------------- -----------
   | <cluster> | <org> | STATE_ENABLED | HEALTHY   |
    ----------- ------- --------------- -----------
   1 rows
   ```

6. You can then register and run some example workflows through your cluster to ensure that it is working correctly.

   ```bash
   uctl register examples --project=union-health-monitoring --domain=development
   uctl validate snacks --project=union-health-monitoring --domain=development
    ---------------------- ----------------------------------- ---------- -------------------------------- -------------- ----------- ---------------
   | NAME                 | LAUNCH PLAN NAME                  | VERSION  | STARTED AT                     | ELAPSED TIME | RESULT    | ERROR MESSAGE |
    ---------------------- ----------------------------------- ---------- -------------------------------- -------------- ----------- ---------------
   | alskkhcd6wx5m6cqjlwm | basics.hello_world.hello_world_wf | v0.3.341 | 2025-05-09T18:30:02.968183352Z | 4.452440953s | SUCCEEDED |               |
    ---------------------- ----------------------------------- ---------- -------------------------------- -------------- ----------- ---------------
   1 rows
   ```


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/selfmanaged-gcp ===

# Data plane setup on GKE (GCP)

Union.ai’s modular architecture allows for great flexibility and control.
The customer can decide how many clusters to have, their shape, and who has access to what.
All communication is encrypted.
The Union architecture is described on the [Architecture](./architecture/_index) page.

> [!NOTE] These instructions cover installing Union.ai in an on-premise Kubernetes cluster.
> If you are installing at a cloud provider, use the cloud provider specific instructions: [AWS](./selfmanaged-aws/_index), [Azure](./selfmanaged-azure), [OCI](./selfmanaged-oci).

## Assumptions

* You have a Union.ai organization, and you know the control plane URL for your organization. (e.g. https://your-org-name.us-east-2.unionai.cloud).
* You have a Kubernetes cluster, running one of the most recent three minor Kubernetes versions. [Learn more](https://kubernetes.io/releases/version-skew-policy/).
* A GCS Bucket and Google Service Accounts that has access to
* Existing Kubernetes Service Accounts with access to the bucket or permissions to create Service Account bindings

## Prerequisites

* Install [Helm 3](https://helm.sh/docs/intro/install/).
* Install [uctl](../../api-reference/uctl-cli/_index).

## Deploy the Union.ai operator

1. Add the Union.ai Helm repo:

   ```bash
   helm repo add unionai https://unionai.github.io/helm-charts/
   helm repo update
   ```

2. Use the `uctl selfserve provision-dataplane-resources` command to generate a new client and client secret for communicating with your Union control plane, provision authorization permissions for the app to operate on the Union cluster name you have selected, generate values file to install dataplane in your Kubernetes cluster and provide follow-up instructions:

   ```bash
   uctl config init --host=<YOUR_UNION_CONTROL_PLANE_URL>
   uctl selfserve provision-dataplane-resources --clusterName <YOUR_SELECTED_CLUSTERNAME>  --provider gcp
   ```

   * The command will output the ID, name, and a secret that will be used by the Union services to communicate with your control plane.
     It will also generate a YAML file specific to the provider that you specify, in this case `metal`, meaning "bare metal", or generic:

   ```bash
    -------------- ------------------------------------ ---------------------------- ------------------------------------------------- ------------------------------------------------------------------ ----------
   | ORGANIZATION | HOST                               | CLUSTER                    | CLUSTERAUTHCLIENTID                             | CLUSTERAUTHCLIENTSECRET                                          | PROVIDER |
    -------------- ------------------------------------ ---------------------------- ------------------------------------------------- ------------------------------------------------------------------ ----------
   | xxxxxxxxxxx  | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | xxxxxxxxxxxxxxxxxxxxxxxxxx | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | xxxxx    |
    -------------- ------------------------------------ ---------------------------- ------------------------------------------------- ------------------------------------------------------------------ ----------
   1 rows

   ✅ Generated <ORGNAME>-values.yaml
   ======================================================================
   Installation Instructions
   ======================================================================

   Step 1: Prepare your Kubernetes cluster.

   Step 2: Clone and navigate to helm-charts repository
     git clone https://github.com/unionai/helm-charts && cd helm-charts

   Step 3: Configure your S3-compatible storage endpoint & credentials in the values file

   Step 4: Install the data plane CRDs
     helm upgrade --install unionai-dataplane-crds charts/dataplane-crds

   Step 5: Install the data plane
     helm upgrade --install unionai-dataplane charts/dataplane \
       --namespace union \
       --values <ORGNAME>-values.yaml

   Step 6: Verify installation
     kubectl get pods -n union

   Step 7: Once you have your dataplane up and running, create API keys for your organization. If you have already just call the same command again to propogate the keys to new cluster:
     uctl create apikey --keyName EAGER_API_KEY --org <your-org-name>

   Step 8: You can now trigger v2 executions on this dataplane.
   ```

  * Save the secret that is displayed. Union does not store the credentials, rerunning the same command can be used to show same secret later which stream through the OAuth Apps provider.
  * Create the `EAGER_API_KEY` as instructed in Step 7 of the command output. This step is required for every dataplane you plan to use for V2 executions.

3.  Update the values file correctly:
    For example, `<UNION_FLYTE_ROLE_ARN>` is the ARN of the new IAM role created in the [AWS Cluster Recommendations](./cluster-recommendations#iam)

4. Optionally configure the resource `limits` and `requests` for the different services.
   By default, these will be set minimally, will vary depending on usage, and follow the Kubernetes `ResourceRequirements` specification.

   * `clusterresourcesync.resources`
   * `flytepropeller.resources`
   * `flytepropellerwebhook.resources`
   * `operator.resources`
   * `proxy.resources`

5. Once deployed you can check to see if the cluster has been successfully registered to the control plane:

   ```bash
   uctl get cluster
    ----------- ------- --------------- -----------
   | NAME      | ORG   | STATE         | HEALTH    |
    ----------- ------- --------------- -----------
   | <cluster> | <org> | STATE_ENABLED | HEALTHY   |
    ----------- ------- --------------- -----------
   1 rows
   ```

6. You can then register and run some example workflows through your cluster to ensure that it is working correctly.

   ```bash
   uctl register examples --project=union-health-monitoring --domain=development
   uctl validate snacks --project=union-health-monitoring --domain=development
    ---------------------- ----------------------------------- ---------- -------------------------------- -------------- ----------- ---------------
   | NAME                 | LAUNCH PLAN NAME                  | VERSION  | STARTED AT                     | ELAPSED TIME | RESULT    | ERROR MESSAGE |
    ---------------------- ----------------------------------- ---------- -------------------------------- -------------- ----------- ---------------
   | alskkhcd6wx5m6cqjlwm | basics.hello_world.hello_world_wf | v0.3.341 | 2025-05-09T18:30:02.968183352Z | 4.452440953s | SUCCEEDED |               |
    ---------------------- ----------------------------------- ---------- -------------------------------- -------------- ----------- ---------------
   1 rows
   ```


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/selfmanaged-azure ===

# Data plane setup on Azure

Union.ai’s modular architecture allows for great flexibility and control.
The customer can decide how many clusters to have, their shape, and who has access to what.
All communication is encrypted.  The Union architecture is described on the [Architecture](./architecture/_index) page.

## Assumptions

* You have a Union.ai organization, and you know the control plane URL for your organization.
* You have a cluster name provided by or coordinated with Union.
* You have a Kubernetes cluster, running one of the most recent three minor K8s versions.
  [Learn more](https://kubernetes.io/releases/version-skew-policy/).
* You have configured a storage bucket.
* You have configured your AKS cluster as indicated in the [Cluster Recommendations](./cluster-recommendations#aks) section.

## Prerequisites

* Install [Helm 3](https://helm.sh/docs/intro/install/).
* Install [uctl](../../api-reference/uctl-cli/_index).

## Deploy the Union.ai operator

1. Add the Union.ai Helm repo:

   ```bash
   helm repo add unionai https://unionai.github.io/helm-charts/
   helm repo update
   ```

2. Use the `uctl selfserve provision-dataplane-resources` command to generate a new client and client secret for communicating with your Union control plane, provision authorization permissions for the app to operate on the Union cluster name you have selected, generate values file to install dataplane in your Kubernetes cluster and provide follow-up instructions:

   ```bash
   uctl config init --host=<YOUR_UNION_CONTROL_PLANE_URL>
   uctl selfserve provision-dataplane-resources --clusterName <YOUR_SELECTED_CLUSTERNAME>  --provider azure
   ```

   * The command will output the ID, name, and a secret that will be used by the Union services to communicate with your control plane.
     It will also generate a YAML file specific to the provider that you specify, in this case `azure`:

   ```bash
     -------------- ------------------------------------ ---------------------------- ------------------------------------------------- ------------------------------------------------------------------ ----------
   | ORGANIZATION | HOST                               | CLUSTER                    | CLUSTERAUTHCLIENTID                             | CLUSTERAUTHCLIENTSECRET                                          | PROVIDER |
    -------------- ------------------------------------ ---------------------------- ------------------------------------------------- ------------------------------------------------------------------ ----------
   | xxxxxxxxxxx  | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | xxxxxxxxxxxxxxxxxxxxxxxxxx | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | xxxxx    |
    -------------- ------------------------------------ ---------------------------- ------------------------------------------------- ------------------------------------------------------------------ ----------
   1 rows

   ✅ Generated <ORGNAME>-values.yaml
   ======================================================================
   Installation Instructions
   ======================================================================

   Step 1: Setup the infrastucture on Azure. Our team can share terrform scripts to help with this.

   Step 2: Clone and navigate to helm-charts repository
     git clone https://github.com/unionai/helm-charts && cd helm-charts

   Step 3: Configure Azure Blob (stow) & Workload Identity client IDs in values

   Step 4: Install the data plane CRDs
     helm upgrade --install unionai-dataplane-crds charts/dataplane-crds

   Step 5: Install the data plane
     helm upgrade --install unionai-dataplane charts/dataplane \
       --namespace union \
       --values <ORGNAME>-values.yaml

   Step 6: Verify installation
     kubectl get pods -n union

   Step 7: Once you have your dataplane up and running, create API keys for your organization. If you have already just call the same command again to propogate the keys to new cluster:
     uctl create apikey --keyName EAGER_API_KEY --org <your-org-name>

   Step 8: You can now trigger v2 executions on this dataplane.
   ```

   * Save the secret that is displayed. Union does not store the credentials, rerunning the same command can be used to show same secret later which stream through the OAuth Apps provider.
   * Create the `EAGER_API_KEY` as instructed in Step 7 of the command output. This step is required for every dataplane you plan to use for V2 executions.

3. Update the values file correctly:
   For example, `<UNION_FLYTE_ROLE_ARN>` is the ARN of the new IAM role created in the [AWS Cluster Recommendations](./cluster-recommendations#iam)

4. Optionally configure the resource `limits` and `requests` for the different services.
   By default, these will be set minimally, will vary depending on usage, and follow the Kubernetes `ResourceRequirements` specification.

   * `clusterresourcesync.resources`
   * `flytepropeller.resources`
   * `flytepropellerwebhook.resources`
   * `operator.resources`
   * `proxy.resources`

5. Once deployed you can check to see if the cluster has been successfully registered to the control plane:

   ```bash
   uctl get cluster
    ----------- ------- --------------- -----------
   | NAME      | ORG   | STATE         | HEALTH    |
    ----------- ------- --------------- -----------
   | <cluster> | <org> | STATE_ENABLED | HEALTHY   |
    ----------- ------- --------------- -----------
   1 rows
   ```

6. You can then register and run some example workflows through your cluster to ensure that it is working correctly.

   ```bash
   uctl register examples --project=union-health-monitoring --domain=development
   uctl validate snacks --project=union-health-monitoring --domain=development
    ---------------------- ----------------------------------- ---------- -------------------------------- -------------- ----------- ---------------
   | NAME                 | LAUNCH PLAN NAME                  | VERSION  | STARTED AT                     | ELAPSED TIME | RESULT    | ERROR MESSAGE |
    ---------------------- ----------------------------------- ---------- -------------------------------- -------------- ----------- ---------------
   | alskkhcd6wx5m6cqjlwm | basics.hello_world.hello_world_wf | v0.3.341 | 2025-05-09T18:30:02.968183352Z | 4.452440953s | SUCCEEDED |               |
    ---------------------- ----------------------------------- ---------- -------------------------------- -------------- ----------- ---------------
   1 rows
   ```


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/selfmanaged-oci ===

# Data plane setup on OCI

Union.ai’s modular architecture allows for great flexibility and control.
The customer can decide how many clusters to have, their shape, and who has access to what.
All communication is encrypted.
The Union architecture is described on the [Architecture](./architecture/_index) page.

## Assumptions

* You have a Union.ai organization, and you know the control plane URL for your organization.
* You have a cluster name provided by or coordinated with Union.
* You have a Kubernetes cluster, running one of the most recent three minor Kubernetes versions.
  [Learn more](https://kubernetes.io/releases/version-skew-policy/).
* You have configured a storage bucket.
* You have configured your OKE cluster as indicated in [Cluster Recommendations](./cluster-recommendations).

## Prerequisites

* Install [Helm 3](https://helm.sh/docs/intro/install/).
* Install [uctl](../../api-reference/uctl-cli/_index).

## Deploy the Union.ai operator

1. Add the Union.ai Helm repo:

   ```bash
   helm repo add unionai https://unionai.github.io/helm-charts/
   helm repo update
   ```

2. Use the `uctl selfserve provision-dataplane-resources` command to generate a new client and client secret for communicating with your Union control plane, provision authorization permissions for the app to operate on the union cluster name you have selected, generate values file to install dataplane in your Kubernetes cluster and provide follow-up instructions:

   ```bash
   uctl config init --host=<YOUR_UNION_CONTROL_PLANE_URL>
   uctl selfserve provision-dataplane-resources --clusterName <YOUR_SELECTED_CLUSTERNAME>  --provider oci
   ```

   * The command will output the ID, name, and a secret that will be used by the Union services to communicate with your control plane.
     It will also generate a YAML file specific to the provider that you specify, in this case `oci`:

   ```bash
     -------------- ------------------------------------ ---------------------------- ------------------------------------------------- ------------------------------------------------------------------ ----------
   | ORGANIZATION | HOST                               | CLUSTER                    | CLUSTERAUTHCLIENTID                             | CLUSTERAUTHCLIENTSECRET                                          | PROVIDER |
    -------------- ------------------------------------ ---------------------------- ------------------------------------------------- ------------------------------------------------------------------ ----------
   | xxxxxxxxxxx  | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | xxxxxxxxxxxxxxxxxxxxxxxxxx | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | xxxxx    |
    -------------- ------------------------------------ ---------------------------- ------------------------------------------------- ------------------------------------------------------------------ ----------
   1 rows

   ✅ Generated <ORGNAME>-values.yaml
   ======================================================================
   Installation Instructions
   ======================================================================

   Step 1: Setup the infrastucture on OCI. Our team can share terrform scripts to help with this.

   Step 2: Clone and navigate to helm-charts repository
     git clone https://github.com/unionai/helm-charts && cd helm-charts

   Step 3: Ensure storage bucket & Access keys are configured; in values

   Step 4: Install the data plane CRDs
     helm upgrade --install unionai-dataplane-crds charts/dataplane-crds

   Step 5: Install the data plane
     helm upgrade --install unionai-dataplane charts/dataplane \
       --namespace union \
       --values <ORGNAME>-values.yaml

   Step 6: Verify installation
     kubectl get pods -n union

   Step 7: Once you have your dataplane up and running, create API keys for your organization. If you have already just call the same command again to propogate the keys to new cluster:
     uctl create apikey --keyName EAGER_API_KEY --org <your-org-name>

   Step 8: You can now trigger v2 executions on this dataplane.
   ```
   * Save the secret that is displayed. Union does not store the credentials, rerunning the same command can be used to show same secret later which stream through the Oauth Apps provider.
   * Create the `EAGER_API_KEY` as instructed in Step 7 of the command output. This step is required for every dataplane you plan to use for V2 executions.

3.  Update the values file correctly:
    For example, `<UNION_FLYTE_ROLE_ARN>` is the ARN of the new IAM role created in the [AWS Cluster Recommendations](./cluster-recommendations#iam)

4. Optionally configure the resource `limits` and `requests` for the different services.
   By default, these will be set minimally, will vary depending on usage, and follow the Kubernetes `ResourceRequirements` specification.

   * `clusterresourcesync.resources`
   * `flytepropeller.resources`
   * `flytepropellerwebhook.resources`
   * `operator.resources`
   * `proxy.resources`

5. Once deployed you can check to see if the cluster has been successfully registered to the control plane:

   ```bash
   uctl get cluster
    ----------- ------- --------------- -----------
   | NAME      | ORG   | STATE         | HEALTH    |
    ----------- ------- --------------- -----------
   | <cluster> | <org> | STATE_ENABLED | HEALTHY   |
    ----------- ------- --------------- -----------
   1 rows
   ```

6. You can then register and run some example workflows through your cluster to ensure that it is working correctly.

   ```bash
   uctl register examples --project=union-health-monitoring --domain=development
   uctl validate snacks --project=union-health-monitoring --domain=development
    ---------------------- ----------------------------------- ---------- -------------------------------- -------------- ----------- ---------------
   | NAME                 | LAUNCH PLAN NAME                  | VERSION  | STARTED AT                     | ELAPSED TIME | RESULT    | ERROR MESSAGE |
    ---------------------- ----------------------------------- ---------- -------------------------------- -------------- ----------- ---------------
   | alskkhcd6wx5m6cqjlwm | basics.hello_world.hello_world_wf | v0.3.341 | 2025-05-09T18:30:02.968183352Z | 4.452440953s | SUCCEEDED |               |
    ---------------------- ----------------------------------- ---------- -------------------------------- -------------- ----------- ---------------
   1 rows
   ```


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/configuration ===

# Advanced Configurations

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

This section covers the configuration of union features on your Union.ai cluster.

## Subpages
- **Self-managed deployment > Advanced Configurations > Configuring Service and Worker Node Pools**
- **Self-managed deployment > Advanced Configurations > Authentication**
- **Self-managed deployment > Advanced Configurations > Code Viewer**
- **Self-managed deployment > Advanced Configurations > Image Builder**
- **Self-managed deployment > Advanced Configurations > Multiple Clusters**
- **Self-managed deployment > Advanced Configurations > Persistent logs**
- **Self-managed deployment > Advanced Configurations > Monitoring**
- **Self-managed deployment > Advanced Configurations > Secrets**
- **Self-managed deployment > Advanced Configurations > Data retention policies** - Implications of object storage retention or lifecycle policies on the default bucket and metadata.
- **Self-managed deployment > Advanced Configurations > Namespace mapping**


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/configuration/node-pools ===

# Configuring Service and Worker Node Pools

As a best practice, we recommend using separate node pools for the Union services and the Union worker pods. This allows
you to guard against resource contention between Union services and other tasks running in your cluster.

Start by creating two node pools in your cluster. One for the Union services and one for the Union worker pods.
Configure the node pool for the Union services with the `union.ai/node-role: services` label.  The worker pool will
be configured with the `union.ai/node-role: worker` label.  You will also need to taint the nodes in the service and
worker pools to ensure that only the appropriate pods are scheduled on them.

The nodes for Union services should be tainted with:

```bash
kubectl taint nodes <node-name> union.ai/node-role=services:NoSchedule
```
The nodes for execution workers should be tainted with:

```bash
kubectl taint nodes <node-name> union.ai/node-role=worker:NoSchedule
```

Vendor interfaces and provisioning tools may support tainting nodes automatically through configuration options.

Set the scheduling constraints for the Union services in your values file:

```yaml
scheduling:
  affinity:
    nodeAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        nodeSelectorTerms:
        - matchExpressions:
          - key: union.ai/node-role
            operator: In
            values:
            - services
  tolerations:
    - effect: NoSchedule
      key: union.ai/node-role
      operator: Equal
      value: services
```

To ensure that your worker processes are scheduled on the worker node pool, set the following for the Flyte kubernetes plugin:

```yaml
config:
  k8s:
    plugins:
      k8s:
        default-affinity:
          nodeAffinity:
            requiredDuringSchedulingIgnoredDuringExecution:
              nodeSelectorTerms:
              - matchExpressions:
                - key: union.ai/node-role
                  operator: In
                  values:
                  - worker
        default-tolerations:
          - effect: NoSchedule
            key: union.ai/node-role
            operator: Equal
            value: worker
```


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/configuration/authentication ===

# Authentication

Union.ai uses [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html) for user authentication and [OAuth 2.0](https://tools.ietf.org/html/rfc6749) for service-to-service authorization. You must configure an external Identity Provider (IdP) to enable authentication on your deployment.

## Overview

Authentication is enforced at two layers:

1. **Ingress layer** — The control plane nginx ingress validates every request to protected routes via an auth subrequest to the `/me` endpoint.
2. **Application layer** — `flyteadmin` manages browser sessions, validates tokens, and exposes OIDC discovery endpoints.

The following diagram shows how these layers interact for browser-based authentication:

```mermaid
sequenceDiagram
    participant B as Browser
    participant N as Nginx Ingress
    participant F as Flyteadmin
    participant IdP as Identity Provider
    B->>N: Request protected route
    N->>F: Auth subrequest (GET /me)
    F-->>N: 401 (no session)
    N-->>B: 302 → /login
    B->>F: GET /login (unprotected)
    F-->>B: 302 → IdP authorize endpoint
    B->>IdP: Authenticate (PKCE)
    IdP-->>B: 302 → /callback?code=...
    B->>F: GET /callback (exchange code)
    F->>IdP: Exchange code for tokens
    F-->>B: Set-Cookie + 302 → original URL
    B->>N: Retry with session cookie
    N->>F: Auth subrequest (GET /me)
    F-->>N: 200 OK
    N-->>B: Forward to backend service
```

## Prerequisites

- A Union.ai deployment with the control plane installed.
- An OIDC-compliant Identity Provider (IdP).
- Access to create OAuth applications in your IdP.
- A secret management solution for delivering client secrets to pods (e.g., External Secrets Operator with AWS Secrets Manager, HashiCorp Vault, or native Kubernetes secrets).

## Configuring your Identity Provider

You must create three OAuth applications in your IdP:

| Application | Type | Grant Types | Purpose |
|---|---|---|---|
| Web app (browser login) | Web | `authorization_code` | Console/web UI authentication |
| Native app (SDK/CLI) | Native (PKCE) | `authorization_code`, `device_code` | SDK and CLI authentication |
| Service app (internal) | Service | `client_credentials` | All service-to-service communication |

> [!NOTE]
> A single service app is shared by both control plane and dataplane services. If your security policy requires separate credentials per component, you can create additional service apps, but the configuration below assumes a single shared client.

### Authorization server setup

1. Create a custom authorization server in your IdP (or use the default).
2. Add a scope named `all`.
3. Add an access policy that allows all registered clients listed above.
4. Add a policy rule that permits `authorization_code`, `client_credentials`, and `device_code` grant types.
5. Note the **Issuer URI** (e.g., `https://your-idp.example.com/oauth2/<server-id>`).
6. Note the **Token endpoint** (e.g., `https://your-idp.example.com/oauth2/<server-id>/v1/token`).

### Application details

#### 1. Web application (browser login)

- **Type**: Web Application
- **Sign-on method**: OIDC
- **Grant types**: `authorization_code`
- **Sign-in redirect URI**: `https://<your-domain>/callback`
- **Sign-out redirect URI**: `https://<your-domain>/logout`
- Note the **Client ID** → used as `OIDC_CLIENT_ID`
- Note the **Client Secret** → stored in `flyte-admin-secrets` (see **Self-managed deployment > Advanced Configurations > Authentication > Secret delivery**)

#### 2. Native application (SDK/CLI)

- **Type**: Native Application
- **Sign-on method**: OIDC
- **Grant types**: `authorization_code`, `urn:ietf:params:oauth:grant-type:device_code`
- **Sign-in redirect URI**: `http://localhost:53593/callback`
- **Require PKCE**: Always
- **Consent**: Trusted (skip consent screen)
- Note the **Client ID** → used as `CLI_CLIENT_ID` (no secret needed for public clients)

#### 3. Service application (internal)

- **Type**: Service (machine-to-machine)
- **Grant types**: `client_credentials`
- Note the **Client ID** → used as `INTERNAL_CLIENT_ID` (control plane) and `AUTH_CLIENT_ID` (dataplane)
- Note the **Client Secret** → stored in multiple Kubernetes secrets (see **Self-managed deployment > Advanced Configurations > Authentication > Secret delivery**)

## Control plane Helm configuration

The control plane Helm chart requires auth configuration in several sections. All examples below use the global variables defined in `values.<cloud>.selfhosted-intracluster.yaml`.

### Global variables

Set these in your customer overrides file:

```yaml
global:
  OIDC_BASE_URL: "<issuer-uri>"             # e.g. "https://your-idp.example.com/oauth2/default"
  OIDC_CLIENT_ID: "<web-app-client-id>"     # Browser login
  CLI_CLIENT_ID: "<native-app-client-id>"   # SDK/CLI
  INTERNAL_CLIENT_ID: "<service-client-id>" # Service-to-service
  AUTH_TOKEN_URL: "<token-endpoint>"         # e.g. "https://your-idp.example.com/oauth2/default/v1/token"
```

### Flyteadmin OIDC configuration

Configure `flyteadmin` to act as the OIDC relying party. This enables the `/login`, `/callback`, `/me`, and `/logout` endpoints:

```yaml
flyte:
  configmap:
    adminServer:
      server:
        security:
          useAuth: true
      auth:
        grpcAuthorizationHeader: flyte-authorization
        httpAuthorizationHeader: flyte-authorization
        authorizedUris:
          - "http://flyteadmin:80"
          - "http://flyteadmin.<namespace>.svc.cluster.local:80"
        appAuth:
          authServerType: External
          externalAuthServer:
            baseUrl: "<issuer-uri>"
          thirdPartyConfig:
            flyteClient:
              clientId: "<native-app-client-id>"
              redirectUri: "http://localhost:53593/callback"
              scopes:
                - all
        userAuth:
          openId:
            baseUrl: "<issuer-uri>"
            clientId: "<web-app-client-id>"
            scopes:
              - profile
              - openid
              - offline_access
          cookieSetting:
            sameSitePolicy: LaxMode
            domain: ""
          idpQueryParameter: idp
```

Key settings:

- `useAuth: true` — registers the `/login`, `/callback`, `/me`, and `/logout` HTTP endpoints. **Required** for auth to function.
- `authServerType: External` — use your IdP as the authorization server (not flyteadmin's built-in server).
- `grpcAuthorizationHeader: flyte-authorization` — the header name used for bearer tokens. Both the SDK and internal services use this header.

### Flyteadmin and scheduler admin SDK client

Flyteadmin and the scheduler use the admin SDK to communicate with other control plane services. Configure client credentials so these calls are authenticated:

```yaml
flyte:
  configmap:
    adminServer:
      admin:
        clientId: "<service-client-id>"
        clientSecretLocation: "/etc/secrets/client_secret"
```

The secret is mounted from the `flyte-admin-secrets` Kubernetes secret (see **Self-managed deployment > Advanced Configurations > Authentication > Secret delivery**).

### Scheduler auth secret

The flyte-scheduler mounts a separate Kubernetes secret (`flyte-secret-auth`) at `/etc/secrets/`. Enable this mount:

```yaml
flyte:
  secrets:
    adminOauthClientCredentials:
      enabled: true
      clientSecret: "placeholder"
```

> [!NOTE]
> Setting `clientSecret: "placeholder"` causes the subchart to render the `flyte-secret-auth` Kubernetes Secret. Use External Secrets Operator with `creationPolicy: Merge` to overwrite the placeholder with the real credential, or create the secret directly before installing the chart.

### Service-to-service authentication

Control plane services communicate through nginx and need OAuth tokens. Configure the admin SDK client credentials and the union service auth:

```yaml
configMap:
  admin:
    clientId: "<service-client-id>"
    clientSecretLocation: "/etc/secrets/union/client_secret"
  union:
    auth:
      enable: true
      type: ClientSecret
      clientId: "<service-client-id>"
      clientSecretLocation: "/etc/secrets/union/client_secret"
      tokenUrl: "<token-endpoint>"
      authorizationMetadataKey: flyte-authorization
      scopes:
        - all
```

The secret is mounted from the control plane service secret (see **Self-managed deployment > Advanced Configurations > Authentication > Secret delivery**).

### Executions service

The executions service has its own admin client connection that also needs auth:

```yaml
services:
  executions:
    configMap:
      executions:
        app:
          adminClient:
            connection:
              authorizationHeader: flyte-authorization
              clientId: "<service-client-id>"
              clientSecretLocation: "/etc/secrets/union/client_secret"
              tokenUrl: "<token-endpoint>"
              scopes:
                - all
```

### Ingress auth annotations

The control plane ingress uses nginx auth subrequests to enforce authentication. These annotations are set on protected ingress routes:

```yaml
ingress:
  protectedIngressAnnotations:
    nginx.ingress.kubernetes.io/auth-url: "https://$host/me"
    nginx.ingress.kubernetes.io/auth-signin: "https://$host/login?redirect_url=$escaped_request_uri"
    nginx.ingress.kubernetes.io/auth-response-headers: "Set-Cookie"
    nginx.ingress.kubernetes.io/auth-cache-key: "$http_flyte_authorization$http_cookie"
  protectedIngressAnnotationsGrpc:
    nginx.ingress.kubernetes.io/auth-url: "https://$host/me"
    nginx.ingress.kubernetes.io/auth-response-headers: "Set-Cookie"
    nginx.ingress.kubernetes.io/auth-cache-key: "$http_authorization$http_flyte_authorization$http_cookie"
```

For every request to a protected route, nginx makes a subrequest to `/me`. If flyteadmin returns 200 (valid session or token), the request is forwarded. If 401, the user is redirected to `/login` for browser clients, or the 401 is returned directly for API clients.

## Dataplane Helm configuration

When the control plane has OIDC enabled, the dataplane must also authenticate. All dataplane services use the same service app credentials (`AUTH_CLIENT_ID`), which is the same client as `INTERNAL_CLIENT_ID` on the control plane.

### Dataplane global variables

```yaml
global:
  AUTH_CLIENT_ID: "<service-client-id>"  # Same as INTERNAL_CLIENT_ID
```

### Cluster resource sync

```yaml
clusterresourcesync:
  config:
    union:
      auth:
        enable: true
        type: ClientSecret
        clientId: "<service-client-id>"
        clientSecretLocation: "/etc/union/secret/client_secret"
        authorizationMetadataKey: flyte-authorization
        tokenRefreshWindow: 5m
```

### Operator (union service auth)

```yaml
config:
  union:
    auth:
      enable: true
      type: ClientSecret
      clientId: "<service-client-id>"
      clientSecretLocation: "/etc/union/secret/client_secret"
      authorizationMetadataKey: flyte-authorization
      tokenRefreshWindow: 5m
```

### Propeller admin client

```yaml
config:
  admin:
    admin:
      clientId: "<service-client-id>"
      clientSecretLocation: "/etc/union/secret/client_secret"
```

### Executor (eager mode)

Injects the `EAGER_API_KEY` secret into task pods for authenticated eager-mode execution:

```yaml
executor:
  config:
    unionAuth:
      injectSecret: true
      secretName: EAGER_API_KEY
```

### Dataplane secrets

Enable the `union-secret-auth` Kubernetes secret mount for dataplane pods:

```yaml
secrets:
  admin:
    enable: true
    create: false
    clientId: "<service-client-id>"
    clientSecret: "placeholder"
```

> [!NOTE]
> `create: false` means the chart does not create the `union-secret-auth` Kubernetes Secret. You must provision it externally (see **Self-managed deployment > Advanced Configurations > Authentication > Secret delivery**). Setting `clientSecret: "placeholder"` with `create: true` is also supported if you want the chart to create the secret and then overwrite it via External Secrets Operator.

## Secret delivery

Client secrets must be delivered to pods as files mounted into the container filesystem. The table below lists the required Kubernetes secrets, their mount paths, and which components use them:

| Kubernetes Secret | Mount Path | Components | Namespace |
| --- | --- | --- | --- |
| `flyte-admin-secrets` | `/etc/secrets/` | flyteadmin | `union-cp` |
| `flyte-secret-auth` | `/etc/secrets/` | flyte-scheduler | `union-cp` |
| Control plane service secret | `/etc/secrets/union/` | executions, cluster, usage, and other CP services | `union-cp` |
| `union-secret-auth` | `/etc/union/secret/` | operator, propeller, CRS | `union` |

All secrets must contain a key named `client_secret` with the service app's OAuth client secret value.

### Option A: External Secrets Operator (recommended)

If you use [External Secrets Operator (ESO)](https://external-secrets.io/) with a cloud secret store, create `ExternalSecret` resources that sync the client secret into each Kubernetes secret:

```yaml
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: flyte-admin-secrets-auth
  namespace: union-cp
spec:
  secretStoreRef:
    name: default
    kind: SecretStore
  refreshInterval: 1h
  target:
    name: flyte-admin-secrets
    creationPolicy: Merge
    deletionPolicy: Retain
  data:
    - secretKey: client_secret
      remoteRef:
        key: "<your-secret-store-key>"
---
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: flyte-secret-auth
  namespace: union-cp
spec:
  secretStoreRef:
    name: default
    kind: SecretStore
  refreshInterval: 1h
  target:
    name: flyte-secret-auth
    creationPolicy: Merge
    deletionPolicy: Retain
  data:
    - secretKey: client_secret
      remoteRef:
        key: "<your-secret-store-key>"
---
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: union-secret-auth
  namespace: union
spec:
  secretStoreRef:
    name: default
    kind: SecretStore
  refreshInterval: 1h
  target:
    name: union-secret-auth
    creationPolicy: Merge
    deletionPolicy: Retain
  data:
    - secretKey: client_secret
      remoteRef:
        key: "<your-secret-store-key>"
```

> [!NOTE]
> `creationPolicy: Merge` ensures the ExternalSecret adds the `client_secret` key alongside any existing keys in the target secret.

### Option B: Direct Kubernetes secrets

If you manage secrets directly:

```bash
# Control plane — flyteadmin
kubectl create secret generic flyte-admin-secrets \
  --from-literal=client_secret='<SERVICE_CLIENT_SECRET>' \
  -n union-cp

# Control plane — scheduler
kubectl create secret generic flyte-secret-auth \
  --from-literal=client_secret='<SERVICE_CLIENT_SECRET>' \
  -n union-cp

# Control plane — union services (add to existing secret)
kubectl create secret generic union-controlplane-secrets \
  --from-literal=pass.txt='<DB_PASSWORD>' \
  --from-literal=client_secret='<SERVICE_CLIENT_SECRET>' \
  -n union-cp --dry-run=client -o yaml | kubectl apply -f -

# Dataplane — operator, propeller, CRS
kubectl create secret generic union-secret-auth \
  --from-literal=client_secret='<SERVICE_CLIENT_SECRET>' \
  -n union
```

## SDK and CLI authentication

The SDK and CLI use PKCE (Proof Key for Code Exchange) for interactive authentication:

1. The SDK calls `AuthMetadataService/GetPublicClientConfig` (an unprotected endpoint) to discover the `flytectl` client ID and redirect URI.
2. The SDK opens a browser to the IdP's authorize endpoint with a PKCE challenge.
3. The user authenticates in the browser.
4. The IdP redirects to `localhost:53593/callback` with an authorization code.
5. The SDK exchanges the code for tokens and stores them locally.
6. Subsequent requests include the token in the `flyte-authorization` header.

No additional SDK configuration is required beyond the standard `uctl` or Union config:

```yaml
admin:
  endpoint: dns:///<your-domain>
  authType: Pkce
  insecure: false
```

For headless environments (CI/CD), use the **Self-managed deployment > Advanced Configurations > Authentication > SDK and CLI authentication > Client credentials for CI/CD** flow instead.

### Client credentials for CI/CD

For automated pipelines, create a service app in your IdP and configure:

```yaml
admin:
  endpoint: dns:///<your-domain>
  authType: ClientSecret
  clientId: "<your-ci-client-id>"
  clientSecretLocation: "/path/to/client_secret"
```

Or use environment variables:

```bash
export FLYTE_CREDENTIALS_CLIENT_ID="<your-ci-client-id>"
export FLYTE_CREDENTIALS_CLIENT_SECRET="<your-ci-client-secret>"
export FLYTE_CREDENTIALS_AUTH_MODE=basic
```

## Troubleshooting

### Browser login redirects in a loop

Verify that `useAuth: true` is set in `flyte.configmap.adminServer.server.security`. Without this, the `/login`, `/callback`, and `/me` endpoints are not registered.

### SDK gets 401 Unauthenticated

1. Check that the `AuthMetadataService` routes are in the **unprotected** ingress (no auth-url annotation).
2. Verify the SDK can reach the token endpoint. The SDK discovers it via `AuthMetadataService/GetOAuth2Metadata`.
3. Check that `grpcAuthorizationHeader` matches the header name used by the SDK (`flyte-authorization`).

### Internal services get 401

1. Verify that `configMap.union.auth.enable: true` and the `client_secret` file exists at the configured `clientSecretLocation`.
2. Check `ExternalSecret` sync status: `kubectl get externalsecret -n <namespace>`.
3. Verify the secret contains the correct key: `kubectl get secret <secret-name> -n <namespace> -o jsonpath='{.data.client_secret}' | base64 -d`.

### Operator or propeller cannot authenticate

1. Verify `union-secret-auth` exists in the dataplane namespace and contains `client_secret`.
2. Check operator logs for auth errors: `kubectl logs -n union -l app.kubernetes.io/name=operator --tail=50 | grep -i auth`.
3. Verify the `AUTH_CLIENT_ID` matches the control plane's `INTERNAL_CLIENT_ID`.
4. Verify the service app is included in the authorization server's access policy.

### Scheduler fails to start

1. Verify `flyte-secret-auth` exists in the control plane namespace: `kubectl get secret flyte-secret-auth -n union-cp`.
2. Check that `flyte.secrets.adminOauthClientCredentials.enabled: true` is set.
3. Check scheduler logs: `kubectl logs -n union-cp deploy/flytescheduler --tail=50`.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/configuration/code-viewer ===

# Code Viewer

The Union UI allows you to view the exact code that executed a specific task. Union securely transfers the [code bundle](../../../user-guide/run-scaling/life-of-a-run#phase-2-image-building) directly to your browser without routing it through the control plane.

![Code Viewer](../../../_static/images/deployment/configuration/code-viewer/demo.png)

## Enable CORS policy on your fast registration bucket

To support this feature securely, your bucket must allow CORS access from Union. The configuration steps vary depending on your cloud provider.

### AWS S3 Console

1. Open the AWS Console.
2. Navigate to the S3 dashboard.
3. Select your fast registration bucket. By default, this is the same as the metadata bucket configured during initial deployment.
4. Click the **Permissions** tab and scroll to **Cross-origin resource sharing (CORS)**.
5. Click **Edit** and enter the following policy:
![S3 CORS Policy](../../../_static/images/deployment/configuration/code-viewer/s3.png)

```
[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "GET",
            "HEAD",
        ],
        "AllowedOrigins": [
            "https://*.unionai.cloud"
        ],
        "ExposeHeaders": [
            "ETag"
        ],
        "MaxAgeSeconds": 3600
    }
]
```

For more details, see the [AWS S3 CORS documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/cors.html).

### Google GCS

Google Cloud Storage requires CORS configuration via the command line.

1. Create a `cors.json` file with the following content:
    ```json
    [
        {
        "origin": ["https://*.unionai.cloud"],
        "method": ["HEAD", "GET"],
        "responseHeader": ["ETag"],
        "maxAgeSeconds": 3600
        }
    ]
    ```
2. Apply the CORS configuration to your bucket:
    ```bash
    gcloud storage buckets update gs://<fast_registration_bucket> --cors-file=cors.json
    ```
3. Verify the configuration was applied:
   ```bash
   gcloud storage buckets describe gs://<fast_registration_bucket> --format="default(cors_config)"

   cors_config:
   - maxAgeSeconds: 3600
     method:
     - GET
     - HEAD
     origin:
     - https://*.unionai.cloud
     responseHeader:
     - ETag
   ```
For more details, see the [Google Cloud Storage CORS documentation](https://docs.cloud.google.com/storage/docs/using-cors#command-line).

### Azure Storage

For Azure Storage CORS configuration, see the [Azure Storage CORS documentation](https://learn.microsoft.com/en-us/rest/api/storageservices/cross-origin-resource-sharing--cors--support-for-the-azure-storage-services).

## Troubleshooting

| Error Message | Cause | Fix |
|---------------|-------|-----|
| `Not available: No code available for this action.` | The task does not have a code bundle. This occurs when the code is baked into the Docker image or the task is not a code-based task. | This is expected behavior for tasks without code bundles. |
| `Not Found: The code bundle file could not be found. This may be due to your organization's data retention policy.` | The code bundle was deleted from the bucket, likely due to a retention policy. | Review your fast registration bucket's retention policy settings. |
| `Error: Code download is blocked by your storage bucket's configuration. Please contact your administrator to enable access.` | CORS is not configured on the bucket. | Configure CORS on your bucket using the instructions above. |


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/configuration/image-builder ===

# Image Builder

Union Image Builder supports the ability to build container images within the dataplane. This enables the use of the `remote` builder type for any defined [Container Image](../../../user-guide/task-configuration/container-images).

Configure the use of remote image builder:
```bash
flyte create config --builder=remote --endpoint...
```

Write custom [container images](../../../user-guide/task-configuration/container-images):
```python
env = flyte.TaskEnvironment(
    name="hello_v2",
    image=flyte.Image.from_debian_base()
        .with_pip_packages("<package 1>", "<package 2>")
)
```

> By default, Image Builder is disabled and has to be enabled by configuring the builder type to `remote` in flyte config

## Requirements

* The image building process runs in the target run's project and domain. Any image push secrets needed to push images to the registry will need to be accessible from the project & domain where the build happens.

## Configuration

Image Builder is configured directly through Helm values.

```yaml
imageBuilder:

  # Enable Image Builder
  enabled: true

  # -- The config map build-image container task attempts to reference.
  # -- Should not change unless coordinated with Union technical support.
  targetConfigMapName: "build-image-config"

  # -- The URI of the buildkitd service. Used for externally managed buildkitd services.
  # -- Leaving empty and setting imageBuilder.buildkit.enabled to true will create a buildkitd service and configure the Uri appropriately.
  # -- E.g. "tcp://buildkitd.buildkit.svc.cluster.local:1234"
  buildkitUri: ""

  # -- The default repository to publish images to when "registry" is not specified in ImageSpec.
  # -- Note, the build-image task will fail unless "registry" is specified or a default repository is provided.
  defaultRepository: ""

  # -- How build-image task and operator proxy will attempt to authenticate against the default #    repository.
  # -- Supported values are "noop", "google", "aws", "azure"
  # -- "noop" no authentication is attempted
  # -- "google" uses docker-credential-gcr to authenticate to the default registry
  # -- "aws" uses docker-credential-ecr-login to authenticate to the default registry
  # -- "azure" uses az acr login to authenticate to the default registry. Requires Azure Workload Identity to be enabled.
  authenticationType: "noop"

  buildkit:

    # -- Enable buildkit service within this release.
    enabled: true

    # Configuring Union managed buildkitd Kubernetes resources.
    ...
```

## Authentication

### AWS

By default, Union is intended to be configured to use [IAM roles for service accounts (IRSA)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) for authentication. Setting `authenticationType` to `aws` configures Union image builder related services to use AWS default credential chain. Additionally, Union image builder uses [`docker-credential-ecr-login`](https://github.com/awslabs/amazon-ecr-credential-helper) to authenticate to the ecr repository configured with `defaultRepository`.

`defaultRepository` should be the fully qualified ECR repository name, e.g. `<AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/<REPOSITORY_NAME>`.

Therefore, it is necessary to configure the user role with the following permissions.

```json
{
  "Effect": "Allow",
  "Action": [
    "ecr:GetAuthorizationToken"
  ],
  "Resource": "*"
},
{
  "Effect": "Allow",
  "Action": [
    "ecr:BatchCheckLayerAvailability",
    "ecr:BatchGetImage",
    "ecr:GetDownloadUrlForLayer"
  ],
  "Resource": "*"
  // Or
  // "Resource": "arn:aws:ecr:<AWS_REGION>:<AWS_ACCOUNT_ID>:repository/<REPOSITORY>"
}
```

Similarly, the `operator-proxy` requires the following permissions

```json
{
  "Effect": "Allow",
  "Action": [
    "ecr:GetAuthorizationToken"
  ],
  "Resource": "*"
},
{
  "Effect": "Allow",
  "Action": [
    "ecr:DescribeImages"
  ],
  "Resource": "arn:aws:ecr:<AWS_REGION>:<AWS_ACCOUNT_ID>:repository/<REPOSITORY>"
}
```

#### AWS Cross Account access

Access to repositories that do not exist in the same AWS account as the data plane requires additional ECR resource-based permissions. An ECR policy like the following is required if the configured `defaultRepository` or `ImageSpec`'s `registry` exists in an AWS account different from the dataplane's.

```json
{
  "Statement": [
    {
      "Sid": "AllowPull",
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::<DATAPLANE_AWS_ACCOUNT>:role/<user-role>",
          "arn:aws:iam::<DATAPLANE_AWS_ACCOUNT>:role/<node-role>",
          // ... Additional roles that require image pulls
        ]
      },
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:BatchGetImage",
        "ecr:GetDownloadUrlForLayer"
      ]
    },
    {
      "Sid": "AllowDescribeImages",
      "Action": [
        "ecr:DescribeImages"
      ],
      "Principal": {
        "AWS": [
          "arn:aws:iam::<DATAPLANE_AWS_ACCOUNT>:role/<operator-proxy-role>",
        ]
      },
      "Effect": "Allow"
    },
    {
      "Sid": "ManageRepositoryContents"
      // ...
    }
  ],
  "Version": "2012-10-17"
}
```

In order to support a private ImageSpec `base_image` the following permissions are required.

```json
{
  "Statement": [
    {
      "Sid": "AllowPull",
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::<DATAPLANE_AWS_ACCOUNT>:role/<user-role>",
          "arn:aws:iam::<DATAPLANE_AWS_ACCOUNT>:role/<node-role>",
          // ... Additional roles that require image pulls
        ]
      },
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:BatchGetImage",
        "ecr:GetDownloadUrlForLayer"
      ]
    },
  ]
}
```

### Google Cloud Platform

By default, GCP uses [Kubernetes Service Accounts to GCP IAM](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#kubernetes-sa-to-iam) for authentication. Setting `authenticationType` to `google` configures Union image builder related services to use GCP default credential chain. Additionally, Union image builder uses [`docker-credential-gcr`](https://github.com/GoogleCloudPlatform/docker-credential-gcr) to authenticate to the Google artifact registries referenced by `defaultRepository`.

`defaultRepository` should be the full name to the repository in combination with an optional image name prefix. `<GCP_LOCATION>-docker.pkg.dev/<GCP_PROJECT_ID>/<REPOSITORY_NAME>/<IMAGE_PREFIX>`.

It is necessary to configure the GCP user service account with `iam.serviceAccounts.signBlob` project level permissions.

#### GCP Cross Project access

Access to registries that do not exist in the same GCP project as the data plane requires additional GCP permissions.

* Configure the user "role" service account with the `Artifact Registry Writer`.
* Configure the GCP worker node and union-operator-proxy service accounts with the `Artifact Registry Reader` role.

### Azure

By default, Union is designed to use Azure [Workload Identity Federation](https://learn.microsoft.com/en-us/azure/aks/workload-identity-deploy-cluster) for authentication using [user-assigned managed identities](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities?pivots=identity-mi-methods-azp) in place of AWS IAM roles.

* Configure the user "role" user-assigned managed identity with the `AcrPush` role.
* Configure the Azure kubelet identity ID and operator-proxy user-assigned managed identities with the `AcrPull` role.

### Private registries

Follow guidance in this section to integrate Image Builder with private registries:

#### GitHub Container Registry

1. Follow the [GitHub guide](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) to log in to the registry locally.
2. Create a Union secret:
```bash
flyte create secret --type image_pull --from-docker-config --registries ghcr.io SECRET_NAME
```

> This secret will be available to all projects and domains in your tenant. [Learn more about Union Secrets](./union-secrets)
> Check alternative ways to create image pull secrets in the [API reference](../../../api-reference/flyte-cli#flyte-create-secret)

3. Reference this secret in the Image object:

```python
env = flyte.TaskEnvironment(
    name="hello_v2",
    # Allow image builder to pull and push from the private registry. `registry` field isn't required if it's configured
    # as the default registry in imagebuilder section in the helm chart values file.
    image=flyte.Image.from_debian_base(registry="<my registry url>", name="private", registry_secret="<YOUR_SECRET_NAME>")
        .with_pip_packages("<package 1>", "<package 2>"),
    # Mount the same secret to allow tasks to pull that image
    secrets=["<YOUR_SECRET_NAME>"]
)
```

This will enable Image Builder to push images and layers to a private GHCR. It'll also allow pods for this task environment to pull
this image at runtime.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/configuration/multi-cluster ===

# Multiple Clusters

Union enables you to integrate multiple Kubernetes clusters into a single Union control plane using the `clusterPool` abstraction.

Currently, the clusterPool configuration is performed by Union in the control plane when you provide the mapping between clusterPool name and clusterNames using the following structure:

```yaml
clusterPoolname:
  - clusterName
```
With `clusterName` matching the name you used to install the Union operator Helm chart.

You can have as many cluster pools as needed:

**Example**

```yaml
default: # this is the clusterPool where executions will run, unless another mapping specified
  - my-dev-cluster
development-cp:
  - my-dev-cluster
staging-cp:
  - my-staging-cluster
production-cp:
  - production-cluster-1
  - production-cluster-2
dr-region:
  - dr-site-cluster
```

## Using cluster pools

Once the Union team configures the clusterPools in the control plane, you can proceed to configure mappings:

### project-domain-clusterPool mapping

1. Create a YAML file that includes the project, domain, and clusterPool:

**Example: cpa-dev.yaml**

```yaml
domain: development
project: flytesnacks
clusterPoolName: development-cp
```

2. Update the control plane with this mapping:

```bash
uctl update cluster-pool-attributes --attrFile cpa-dev.yaml
```
3. New executions in `flytesnacks-development` should now run in the `my-dev-cluster`

### project-domain-workflow-clusterPool mapping

1. Create a YAML file that includes the project, domain, and clusterPool:

**Example: cpa-dev.yaml**

```yaml
domain: production
project: flytesnacks
workflow: my_critical_wf
clusterPoolName: production-cp
```

2. Update the control plane with this mapping:

```bash
uctl update cluster-pool-attributes --attrFile cpa-prod.yaml
```
3. New executions of the `my_critical_wf` workflow in `flytesnacks-production` should now run in any of the clusters under `production-cp`

## Data sharing between cluster pools

The sharing of metadata is controlled by the cluster pool to which a cluster belongs. If two clusters are in the same cluster pool, then they must share the same metadata bucket, defined in the Helm values as `storage.bucketName`.

If they are in different cluster pools, then they **must** have different metadata buckets. You could, for example, have a single metadata bucket for all your development clusters, and a separate one for all your production clusters, by grouping the clusters into cluster pools accordingly.

 Alternatively you could have a separate metadata bucket for each cluster, by putting each cluster in its own cluster pool.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/configuration/persistent-logs ===

# Persistent logs

Persistent logging is enabled by default. The data plane deploys [FluentBit](https://fluentbit.io/) as a DaemonSet that collects container logs from every node and writes them to the `persisted-logs/` path in the object store configured for your data plane.

FluentBit runs under the `fluentbit-system` Kubernetes service account. This service account must have write access to the storage bucket so FluentBit can push logs. The sections below describe how to grant that access on each cloud provider.

## AWS (IRSA)

On EKS, use [IAM Roles for Service Accounts (IRSA)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) to grant the FluentBit service account permission to write to S3.

### 1. Create an IAM policy

Create an IAM policy that allows writing to your metadata S3 bucket:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:PutObjectAcl",
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::<BUCKET_NAME>",
        "arn:aws:s3:::<BUCKET_NAME>/persisted-logs/*"
      ]
    }
  ]
}
```

Replace `<BUCKET_NAME>` with the name of your data plane metadata bucket.

### 2. Create an IAM role with a trust policy

Create an IAM role that trusts the EKS OIDC provider and is scoped to the `fluentbit-system` service account:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/<OIDC_PROVIDER>"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "<OIDC_PROVIDER>:sub": "system:serviceaccount:<NAMESPACE>:fluentbit-system",
          "<OIDC_PROVIDER>:aud": "sts.amazonaws.com"
        }
      }
    }
  ]
}
```

Replace:

- `<ACCOUNT_ID>` with your AWS account ID
- `<OIDC_PROVIDER>` with your EKS cluster's OIDC provider (e.g. `oidc.eks.us-east-1.amazonaws.com/id/EXAMPLE`)
- `<NAMESPACE>` with the namespace where the data plane is installed (default: `union`)

You can retrieve the OIDC provider URL with:

```bash
aws eks describe-cluster --name <CLUSTER_NAME> --region <REGION> \
  --query "cluster.identity.oidc.issuer" --output text
```

Attach the IAM policy from step 1 to this role.

### 3. Configure the Helm values

Set the IRSA annotation on the FluentBit service account in your data plane Helm values:

```yaml
fluentbit:
  serviceAccount:
    name: fluentbit-system
    annotations:
      eks.amazonaws.com/role-arn: "arn:aws:iam::<ACCOUNT_ID>:role/<FLUENTBIT_ROLE_NAME>"
```

## Azure (Workload Identity Federation)

On AKS, use [Microsoft Entra Workload Identity](https://learn.microsoft.com/en-us/azure/aks/workload-identity-overview) to grant the FluentBit service account access to Azure Blob Storage.

### Azure prerequisites

- Your AKS cluster must be [enabled as an OIDC Issuer](https://learn.microsoft.com/en-us/azure/aks/use-oidc-issuer)
- The [Azure Workload Identity](https://learn.microsoft.com/en-us/azure/aks/workload-identity-deploy-cluster) mutating webhook must be installed on your cluster

### 1. Create or reuse a Managed Identity

Create a User Assigned Managed Identity (or reuse an existing one):

```bash
az identity create \
  --name fluentbit-identity \
  --resource-group <RESOURCE_GROUP> \
  --location <LOCATION>
```

Note the `clientId` from the output.

### 2. Add a federated credential

Create a federated credential that maps the `fluentbit-system` Kubernetes service account to the managed identity:

```bash
az identity federated-credential create \
  --name fluentbit-federated-credential \
  --identity-name fluentbit-identity \
  --resource-group <RESOURCE_GROUP> \
  --issuer <AKS_OIDC_ISSUER_URL> \
  --subject "system:serviceaccount:<NAMESPACE>:fluentbit-system" \
  --audiences "api://AzureADTokenExchange"
```

Replace:

- `<RESOURCE_GROUP>` with your Azure resource group
- `<AKS_OIDC_ISSUER_URL>` with the OIDC issuer URL of your AKS cluster
- `<NAMESPACE>` with the namespace where the data plane is installed (default: `union`)

You can retrieve the OIDC issuer URL with:

```bash
az aks show --name <CLUSTER_NAME> --resource-group <RESOURCE_GROUP> \
  --query "oidcIssuerProfile.issuerUrl" --output tsv
```

### 3. Assign a storage role

Assign the `Storage Blob Data Contributor` role to the managed identity at the storage account level:

```bash
az role assignment create \
  --assignee <CLIENT_ID> \
  --role "Storage Blob Data Contributor" \
  --scope "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.Storage/storageAccounts/<STORAGE_ACCOUNT>"
```

### 4. Configure the Azure Helm values

Set the Workload Identity annotation on the FluentBit service account in your data plane Helm values:

```yaml
fluentbit:
  serviceAccount:
    name: fluentbit-system
    annotations:
      azure.workload.identity/client-id: "<CLIENT_ID>"
```

You must also ensure the FluentBit pods have the Workload Identity label. If you have already set `additionalPodLabels` for your data plane, confirm the following label is present:

```yaml
additionalPodLabels:
  azure.workload.identity/use: "true"
```

## GCP (Workload Identity)

On GKE, use [GKE Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity) to grant the FluentBit service account access to GCS.

### GCP prerequisites

- [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#enable) must be enabled on your GKE cluster

### 1. Create or reuse a GCP service account

Create a GCP service account (or reuse an existing one):

```bash
gcloud iam service-accounts create fluentbit-gsa \
  --display-name "FluentBit logging service account" \
  --project <PROJECT_ID>
```

### 2. Grant storage permissions

Grant the service account write access to the metadata bucket:

```bash
gcloud storage buckets add-iam-policy-binding gs://<BUCKET_NAME> \
  --member "serviceAccount:fluentbit-gsa@<PROJECT_ID>.iam.gserviceaccount.com" \
  --role "roles/storage.objectAdmin"
```

### 3. Bind the Kubernetes service account to the GCP service account

Allow the `fluentbit-system` Kubernetes service account to impersonate the GCP service account:

```bash
gcloud iam service-accounts add-iam-policy-binding \
  fluentbit-gsa@<PROJECT_ID>.iam.gserviceaccount.com \
  --role "roles/iam.workloadIdentityUser" \
  --member "serviceAccount:<PROJECT_ID>.svc.id.goog[<NAMESPACE>/fluentbit-system]"
```

Replace:

- `<PROJECT_ID>` with your GCP project ID
- `<BUCKET_NAME>` with the name of your data plane metadata bucket
- `<NAMESPACE>` with the namespace where the data plane is installed (default: `union`)

### 4. Configure the GCP Helm values

Set the Workload Identity annotation on the FluentBit service account in your data plane Helm values:

```yaml
fluentbit:
  serviceAccount:
    name: fluentbit-system
    annotations:
      iam.gke.io/gcp-service-account: "fluentbit-gsa@<PROJECT_ID>.iam.gserviceaccount.com"
```

## Disabling persistent logs

To disable persistent logging entirely, set the following in your Helm values:

```yaml
fluentbit:
  enabled: false
```


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/configuration/monitoring ===

# Monitoring

The Union.ai data plane deploys a static [Prometheus](https://prometheus.io/) instance that collects metrics required for platform features like cost tracking, task-level resource monitoring, and execution observability. This Prometheus instance is pre-configured and requires no additional setup.

For operational monitoring of the cluster itself (node health, API server metrics, CoreDNS, etc.), the data plane chart includes an optional [kube-prometheus-stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack) instance that can be enabled separately.

## Architecture overview

The data plane supports two independent monitoring concerns:

| Concern | What it monitors | How it's deployed | Configurable |
|---------|-----------------|-------------------|--------------|
| **Union features** | Task execution metrics, cost tracking, GPU utilization, container resources | Static Prometheus with pre-built scrape config | Retention, resources, scheduling |
| **Cluster health** (optional) | Kubernetes components, node health, alerting, Grafana dashboards | `kube-prometheus-stack` via `monitoring.enabled` | Full kube-prometheus-stack values |

```
                    ┌─────────────────────────────────────┐
                    │          Data Plane Cluster          │
                    │                                     │
                    │  ┌──────────────────────┐           │
                    │  │  Static Prometheus   │           │
                    │  │  (Union features)    │           │
                    │  │  ┌────────────────┐  │           │
                    │  │  │ Scrape targets │  │           │
                    │  │  │ - kube-state   │  │           │
                    │  │  │ - cAdvisor     │  │           │
                    │  │  │ - propeller    │  │           │
                    │  │  │ - opencost     │  │           │
                    │  │  │ - dcgm (GPU)   │  │           │
                    │  │  │ - envoy        │  │           │
                    │  │  └────────────────┘  │           │
                    │  └─────────────────────-┘           │
                    │                                     │
                    │  ┌──────────────────────┐           │
                    │  │  kube-prometheus     │           │
                    │  │  -stack (optional)   │           │
                    │  │  - Prometheus        │           │
                    │  │  - Alertmanager      │           │
                    │  │  - Grafana           │           │
                    │  │  - node-exporter     │           │
                    │  └──────────────────────┘           │
                    └─────────────────────────────────────┘
```

## Union features Prometheus

The static Prometheus instance is always deployed and pre-configured to scrape the metrics that Union.ai requires. No Prometheus Operator or CRDs are needed. This instance is a platform dependency and should not be replaced or reconfigured.

### Scrape targets

The following targets are scraped automatically:

| Job | Target | Metrics collected |
|-----|--------|------------------|
| `kube-state-metrics` | Pod/node resource requests, limits, status, capacity | Cost calculations, resource tracking |
| `kubernetes-cadvisor` | Container CPU and memory usage via kubelet | Task-level resource monitoring |
| `flytepropeller` | Execution round info, fast task duration | Execution observability |
| `opencost` | Node hourly cost rates (CPU, RAM, GPU) | Cost tracking |
| `gpu-metrics` | DCGM exporter metrics (when `dcgm-exporter.enabled`) | GPU utilization |
| `serving-envoy` | Envoy upstream request counts and latency (when `serving.enabled`) | Inference serving metrics |

### Configuration

The static Prometheus instance is configured under the `prometheus` key in your data plane values:

```yaml
prometheus:
  image:
    repository: prom/prometheus
    tag: v3.3.1
  # Data retention period
  retention: 3d
  # Route prefix for the web UI and API
  routePrefix: /prometheus/
  resources:
    limits:
      cpu: "3"
      memory: "3500Mi"
    requests:
      cpu: "1"
      memory: "1Gi"
  serviceAccount:
    create: true
    annotations: {}
  priorityClassName: system-cluster-critical
  nodeSelector: {}
  tolerations: []
  affinity: {}
```

> [!NOTE] Retention and storage
> The default 3-day retention is sufficient for Union.ai features. Increase `retention` if you query historical feature metrics directly.

### Internal service endpoint

Other data plane components reach Prometheus at:

```
http://union-operator-prometheus.<NAMESPACE>.svc:80/prometheus
```

OpenCost is pre-configured to use this endpoint. You do not need to change it unless you rename the Helm release.

## Enabling cluster health monitoring

To enable operational monitoring with Prometheus Operator, Alertmanager, Grafana, and node-exporter:

```yaml
monitoring:
  enabled: true
```

This deploys a full [kube-prometheus-stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack) instance with sensible defaults:

- Prometheus with 7-day retention
- Grafana with admin credentials (override `monitoring.grafana.adminPassword` in production)
- Node exporter, kube-state-metrics, kubelet, CoreDNS, API server, etcd, and scheduler monitoring
- Default alerting and recording rules

### Prometheus Operator CRDs

The `kube-prometheus-stack` uses the Prometheus Operator, which discovers scrape targets and alerting rules through Kubernetes CRDs (ServiceMonitor, PodMonitor, PrometheusRule, etc.). If you prefer to use static scrape configs with your own Prometheus instead, see **Self-managed deployment > Advanced Configurations > Monitoring > Scraping Union services from your own Prometheus**.

To install the CRDs, use the `dataplane-crds` chart:

```yaml
# dataplane-crds values
crds:
  flyte: true
  prometheusOperator: true  # Install Prometheus Operator CRDs
```

Then install or upgrade the CRDs chart before the data plane chart:

```shell
helm upgrade --install union-dataplane-crds unionai/dataplane-crds \
  --namespace union \
  --set crds.prometheusOperator=true
```

> [!NOTE] CRD installation order
> CRDs must be installed before the data plane chart. The `dataplane-crds` chart should be deployed first, and the monitoring stack's own CRD installation is disabled (`monitoring.crds.enabled: false`) to avoid conflicts.

### Customizing the monitoring stack

The monitoring stack accepts all [kube-prometheus-stack values](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack#configuration) under the `monitoring` key. Common overrides:

```yaml
monitoring:
  enabled: true

  # Grafana
  grafana:
    enabled: true
    adminPassword: "my-secure-password"
    ingress:
      enabled: true
      ingressClassName: nginx
      hosts:
        - grafana.example.com

  # Prometheus retention and resources
  prometheus:
    prometheusSpec:
      retention: 30d
      resources:
        requests:
          memory: "2Gi"

  # Alertmanager
  alertmanager:
    enabled: true
    # Configure receivers, routes, etc.
```

The monitoring stack's Prometheus supports [remote write](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_write) for forwarding metrics to external time-series databases (Amazon Managed Prometheus, Grafana Cloud, Thanos, etc.):

```yaml
monitoring:
  prometheus:
    prometheusSpec:
      remoteWrite:
        - url: "https://aps-workspaces.<REGION>.amazonaws.com/workspaces/<WORKSPACE_ID>/api/v1/remote_write"
          sigv4:
            region: <REGION>
```

For the full set of configurable values, see the [kube-prometheus-stack chart documentation](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack).

## Scraping Union services from your own Prometheus

If you already run Prometheus in your cluster, you can scrape Union.ai data plane services for operational visibility. All services expose metrics on standard ports.

> [!NOTE] Union features Prometheus
> The built-in static Prometheus handles all metrics required for Union.ai platform features. Scraping from your own Prometheus is for additional operational visibility only -- it does not replace the built-in instance.

### Static scrape configs

Add these jobs to your Prometheus configuration:

```yaml
scrape_configs:
  # Data plane service metrics (operator, propeller, etc.)
  - job_name: union-dataplane-services
    kubernetes_sd_configs:
      - role: endpoints
        namespaces:
          names: [union]
    relabel_configs:
      - source_labels: [__meta_kubernetes_service_label_app_kubernetes_io_instance]
        regex: union-dataplane
        action: keep
      - source_labels: [__meta_kubernetes_endpoint_port_name]
        regex: debug
        action: keep
```

### ServiceMonitor (Prometheus Operator)

If you run the Prometheus Operator, create a ServiceMonitor instead:

```yaml
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: union-dataplane-services
  namespace: union
spec:
  selector:
    matchLabels:
      app.kubernetes.io/instance: union-dataplane
  namespaceSelector:
    matchNames:
      - union
  endpoints:
    - port: debug
      path: /metrics
      interval: 30s
```

This requires the Prometheus Operator CRDs. Install them via the `dataplane-crds` chart with `crds.prometheusOperator: true`.

## Further reading

- [Prometheus documentation](https://prometheus.io/docs/introduction/overview/) -- comprehensive guide to Prometheus configuration, querying, and operation
- [Prometheus remote write](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_write) -- forwarding metrics to external storage
- [Prometheus `kubernetes_sd_config`](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) -- Kubernetes service discovery for scrape targets
- [kube-prometheus-stack chart](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack) -- full monitoring stack with Grafana and alerting
- [OpenCost documentation](https://www.opencost.io/docs/) -- cost allocation and tracking


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/configuration/union-secrets ===

# Secrets

[Union Secrets](../../../user-guide/task-configuration/secrets) are enabled by default. Union Secrets are managed secrets created through the native Kubernetes secret manager.

The only configurable option is the namespace where the secret is stored. To override the default behavior, set `proxy.secretManager.namespace` in the values file used by the helm chart. If this is not specified, the `union` namespace will be used by default.

Example:
```yaml
proxy:
  secretManager:
    # -- Set the namespace for union managed secrets created through the native Kubernetes secret manager. If the namespace is not set,
    # the release namespace will be used.
    namespace: "secret"
```


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/configuration/data-retention ===

Implications of object storage retention or lifecycle policies on the default bucket and metadata.

# Data retention policies

Union.ai relies on object storage for both **metadata** and **raw data** (your data that is passing through the workflow). Bucket-level retention and lifecycle policies (such as S3 lifecycle rules) that affect the metadata store can cause execution failures, broken history, and data loss.

## How Union.ai uses the default bucket

The platform uses a **default object store bucket** in the data plane for two distinct purposes:

1. **Metadata store** — References, execution state, and pointers to task outputs. The control plane and UI use this metadata to schedule workflows, resolve task dependencies, display execution history, and resolve output locations. This data is required for the correct operation of the platform.

2. **Raw data store** — Large task inputs and outputs or complex types (for example `FlyteFile`, dataframes, etc.). The metadata store holds only pointers to these blobs; the actual bytes live in the raw data store.

Because the **default bucket contains the metadata store**, it must be treated as **durable storage**. Retention or lifecycle policies that delete or overwrite objects in this bucket are **not supported** and can lead to data loss and system failure. There is **no supported way** to recover from metadata loss.

## Impact of metadata loss

| Area | Impact |
|------|--------|
| **UI and APIs** | Execution list or detail views may show errors or "resource not found." Output previews may fail to load. |
| **Execution engine** | In-flight or downstream tasks that depend on a node's output can fail. Retry state may be lost. |
| **Caching** | Pointers to cached outputs may be lost, resulting in cache misses; tasks may re-run or fail. |
| **Traces** | [Trace](../../../user-guide/task-programming/traces) checkpoint data (used by `@flyte.trace` for fine-grained recovery from system failures) may be lost, preventing resume-from-checkpoint. |
| **Data** | Raw blobs may still exist, but without metadata the system has no pointers to them. That data becomes **orphaned**. Downstream tasks that consume outputs by reference will fail at runtime. |
| **Operations** | Audit trails and the record of what ran, when, and with what outputs are lost. |

## Retention on a separate raw-data location

If you separate raw data from metadata, you can apply retention policies **only to the raw data location** while keeping metadata durable. This is the only supported approach for applying retention. You can do this either by configuring separate buckets using `configuration.storage.metadataContainer` and `configuration.storage.userDataContainer` in the [data plane chart](https://github.com/unionai/helm-charts/blob/master/charts/dataplane/values.yaml), or by using a metadata prefix within the same bucket (see **Self-managed deployment > Advanced Configurations > Data retention policies > Customizing the metadata path** below).

Be aware of the trade-offs:

- **Historical executions** that reference purged raw data will fail.
- **Cached task outputs** stored as raw data will be lost, causing cache misses and task re-execution.
- **Trace checkpoints** stored in the raw-data location will be purged, preventing resume-from-checkpoint for affected executions.

Data correctness is not silently violated, but the benefits of caching and trace-based recovery are lost for purged data.

## Customizing the metadata path

You can control where metadata is stored within the bucket via the **`config.core.propeller.metadata-prefix`** setting (e.g. `metadata/propeller` in the [data plane chart values](https://github.com/unionai/helm-charts/blob/master/charts/dataplane/values.yaml)). This lets you design lifecycle rules that **exclude** the metadata prefix (for example, in S3 lifecycle rules, apply expiration only to prefixes that do not include the metadata path) so that only non-metadata paths are subject to retention.

Confirm the exact prefix and bucket layout for your deployment from the chart configuration, and validate any retention rules in a non-production environment before applying them broadly.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/configuration/namespace-mapping ===

# Namespace mapping

By default, Union.ai maps each project-domain pair to a Kubernetes namespace using the pattern `{project}-{domain}`. For example, the project `flytesnacks` in domain `development` runs workloads in namespace `flytesnacks-development`.

You can customize this mapping by setting the `namespace_mapping.template` value in your Helm configuration.

## Template syntax

The template uses Go template syntax with two variables:

- `{{ project }}` — the project name
- `{{ domain }}` — the domain name (e.g., `development`, `staging`, `production`)

### Examples

| Template | Project | Domain | Resulting namespace |
|----------|---------|--------|---------------------|
| `{{ project }}-{{ domain }}` (default) | `flytesnacks` | `development` | `flytesnacks-development` |
| `{{ domain }}` | `flytesnacks` | `development` | `development` |
| `myorg-{{ project }}-{{ domain }}` | `flytesnacks` | `development` | `myorg-flytesnacks-development` |

> [!WARNING]
> Changing namespace mapping after workflows have run will cause existing data in old namespaces to become inaccessible. Plan your namespace mapping before initial deployment.

## Data plane configuration

Set the `namespace_mapping` value at the top level of your dataplane Helm values. This single value cascades to all services that need it: clusterresourcesync, propeller, operator, and executor.

```yaml
namespace_mapping:
  template: "myorg-{{ '{{' }} project {{ '}}' }}-{{ '{{' }} domain {{ '}}' }}"
```

> [!NOTE]
> The template uses Helm's backtick escaping for Go template delimiters. In your values file, wrap `{{ project }}` and `{{ domain }}` with backtick-escaped `{{` and `}}` delimiters as shown above.

## How it works

Namespace mapping controls several components:

| Component | Role |
|-----------|------|
| **Clusterresourcesync** | Creates Kubernetes namespaces and per-namespace resources (service accounts, resource quotas) based on the mapping |
| **Propeller** | Resolves the target namespace when scheduling workflow pods |
| **Operator** | Resolves the target namespace for operator-managed resources |
| **Executor** | Resolves the target namespace for task execution |
| **Flyteadmin** (control plane) | Determines the target namespace when creating V1 executions |

All components must agree on the mapping. The dataplane chart's top-level `namespace_mapping` value is the canonical source that cascades to clusterresourcesync, propeller, operator, and executor automatically. You should **not** set per-service overrides.


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/helm-chart-reference ===

# Helm chart reference

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

A full list of Helm values available for configuration can be found here:

* **Self-managed deployment > Helm chart reference > Page**
* **Self-managed deployment > Helm chart reference > Page**

## Subpages
- **Self-managed deployment > Helm chart reference > Page**
- **Self-managed deployment > Helm chart reference > Page**


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/helm-chart-reference/dataplane ===

Deploys the Union dataplane components to onboard a kubernetes cluster to the Union Cloud.

## Chart info

| | |
|---|---|
| **Chart version** | 2026.3.12 |
| **App version** | 2026.3.9 |
| **Kubernetes version** | `>= 1.28.0-0` |

## Dependencies

| Repository | Name | Version |
|------------|------|---------|
| https://fluent.github.io/helm-charts | fluentbit(fluent-bit) | 0.48.9 |
| https://kubernetes-sigs.github.io/metrics-server/ | metrics-server(metrics-server) | 3.12.2 |
| https://kubernetes.github.io/ingress-nginx | ingress-nginx | 4.12.3 |
| https://nvidia.github.io/dcgm-exporter/helm-charts | dcgm-exporter | 4.7.1 |
| https://opencost.github.io/opencost-helm-chart | opencost | 1.42.0 |
| https://prometheus-community.github.io/helm-charts | monitoring(kube-prometheus-stack) | 80.8.0 |
| https://prometheus-community.github.io/helm-charts | kube-state-metrics | 5.30.1 |
| https://unionai.github.io/helm-charts | knative-operator(knative-operator) | 2025.5.0 |

## Values

| Key | Type | Description | Default |
|-----|------|-------------|---------|
| additionalPodAnnotations | object | Define additional pod annotations for all of the Union pods. | `{}` |
| additionalPodEnvVars | object | Define additional pod environment variables for all of the Union pods. | `{}` |
| additionalPodLabels | object | Define additional pod labels for all of the Union pods. | `{}` |
| additionalPodSpec | object | Define additional PodSpec values for all of the Union pods. | `{}` |
| clusterName | string | Cluster name should be shared with Union for proper functionality. | `"{{ .Values.global.CLUSTER_NAME }}"` |
| clusterresourcesync | object | clusterresourcesync contains the configuration information for the syncresources service. | `(see values.yaml)` |
| clusterresourcesync.additionalTemplates | list | Additional cluster resource templates to create per project namespace. Use this instead of overriding `templates` to avoid accidentally removing the default namespace, service account, and resource quota templates. Each entry has a `key` (filename stem) and `value` (Kubernetes manifest). | `[]` |
| clusterresourcesync.additionalVolumeMounts | list | Appends additional volume mounts to the main container's spec. May include template values. | `[]` |
| clusterresourcesync.additionalVolumes | list | Appends additional volumes to the deployment spec. May include template values. | `[]` |
| clusterresourcesync.affinity | object | affinity configurations for the syncresources pods | `{}` |
| clusterresourcesync.config | object | Syncresources service configuration | `(see values.yaml)` |
| clusterresourcesync.config.clusterResourcesPrivate | object | Additional configuration for the cluster resources service | `{"app":{"isServerless":false}}` |
| clusterresourcesync.config.clusterResourcesPrivate.app | object | Configuration of app serving services. | `{"isServerless":false}` |
| clusterresourcesync.config.cluster_resources.clusterName | string | The name of the cluster.  This should always be the same as the cluster name in the config. | `"{{ include \"getClusterName\" . }}"` |
| clusterresourcesync.config.cluster_resources.refreshInterval | string | How frequently to sync the cluster resources | `"5m"` |
| clusterresourcesync.config.cluster_resources.standaloneDeployment | bool | Start the cluster resource manager in standalone mode. | `true` |
| clusterresourcesync.config.cluster_resources.templatePath | string | The path to the project the templates used to configure project resource quotas. | `"/etc/flyte/clusterresource/templates"` |
| clusterresourcesync.config.union | object | Connection information for the sync resources service to connect to the Union control plane. | `(see values.yaml)` |
| clusterresourcesync.config.union.connection.host | string | Host to connect to | `"dns:///{{ tpl .Values.host . }}"` |
| clusterresourcesync.enabled | bool | Enable or disable the syncresources service | `true` |
| clusterresourcesync.nodeName | string | nodeName constraints for the syncresources pods | `""` |
| clusterresourcesync.nodeSelector | object | nodeSelector constraints for the syncresources pods | `{}` |
| clusterresourcesync.podAnnotations | object | Additional pod annotations for the syncresources service | `{}` |
| clusterresourcesync.podEnv | object | Additional pod environment variables for the syncresources service | `{}` |
| clusterresourcesync.resources | object | Kubernetes resource configuration for the syncresources service | `{"limits":{"cpu":"1","memory":"500Mi"},"requests":{"cpu":"500m","memory":"100Mi"}}` |
| clusterresourcesync.serviceAccount | object | Override service account values for the syncresources service | `{"annotations":{},"name":""}` |
| clusterresourcesync.serviceAccount.annotations | object | Additional annotations for the syncresources service account | `{}` |
| clusterresourcesync.serviceAccount.name | string | Override the service account name for the syncresources service | `""` |
| clusterresourcesync.templates | list | The templates that are used to create and/or update kubernetes resources for Union projects. | `(see values.yaml)` |
| clusterresourcesync.templates[0] | object | Template for namespaces resources | `(see values.yaml)` |
| clusterresourcesync.templates[1] | object | Patch default service account | `(see values.yaml)` |
| clusterresourcesync.tolerations | list | tolerations for the syncresources pods | `[]` |
| clusterresourcesync.topologySpreadConstraints | object | topologySpreadConstraints for the syncresources pods | `{}` |
| config | object | Global configuration settings for all Union services. | `(see values.yaml)` |
| config.admin | object | Admin Client configuration [structure](https://pkg.go.dev/github.com/flyteorg/flytepropeller/pkg/controller/nodes/subworkflow/launchplan#AdminConfig) | `(see values.yaml)` |
| config.catalog | object | Catalog Client configuration [structure](https://pkg.go.dev/github.com/flyteorg/flytepropeller/pkg/controller/nodes/task/catalog#Config) Additional advanced Catalog configuration [here](https://pkg.go.dev/github.com/lyft/flyteplugins/go/tasks/pluginmachinery/catalog#Config) | `(see values.yaml)` |
| config.configOverrides | object | Override any configuration settings. | `{"cache":{"identity":{"enabled":false}}}` |
| config.copilot | object | Copilot configuration | `(see values.yaml)` |
| config.copilot.plugins.k8s.co-pilot | object | Structure documented [here](https://pkg.go.dev/github.com/lyft/flyteplugins@v0.5.28/go/tasks/pluginmachinery/flytek8s/config#FlyteCoPilotConfig) | `(see values.yaml)` |
| config.core | object | Core propeller configuration | `(see values.yaml)` |
| config.core.propeller | object | follows the structure specified [here](https://pkg.go.dev/github.com/flyteorg/flytepropeller/pkg/controller/config). | `(see values.yaml)` |
| config.domain | object | Domains configuration for Union projects. This enables the specified number of domains across all projects in Union. | `(see values.yaml)` |
| config.enabled_plugins.tasks | object | Tasks specific configuration [structure](https://pkg.go.dev/github.com/flyteorg/flytepropeller/pkg/controller/nodes/task/config#GetConfig) | `(see values.yaml)` |
| config.enabled_plugins.tasks.task-plugins | object | Plugins configuration, [structure](https://pkg.go.dev/github.com/flyteorg/flytepropeller/pkg/controller/nodes/task/config#TaskPluginConfig) | `(see values.yaml)` |
| config.enabled_plugins.tasks.task-plugins.enabled-plugins | list | [Enabled Plugins](https://pkg.go.dev/github.com/lyft/flyteplugins/go/tasks/config#Config). Enable sagemaker*, athena if you install the backend plugins | `["container","sidecar","k8s-array","echo","fast-task","connector-service"]` |
| config.k8s | object | Kubernetes specific Flyte configuration | `{"plugins":{"k8s":{"default-cpus":"100m","default-env-vars":[],"default-memory":"100Mi"}}}` |
| config.k8s.plugins.k8s | object | Configuration section for all K8s specific plugins [Configuration structure](https://pkg.go.dev/github.com/lyft/flyteplugins/go/tasks/pluginmachinery/flytek8s/config) | `{"default-cpus":"100m","default-env-vars":[],"default-memory":"100Mi"}` |
| config.logger | object | Logging configuration | `{"level":4,"show-source":true}` |
| config.operator | object | Configuration for the Union operator service | `(see values.yaml)` |
| config.operator.apps | object | Enable app serving | `{"enabled":"{{ .Values.serving.enabled }}"}` |
| config.operator.billing | object | Billing model: None, Legacy, or ResourceUsage. | `{"model":"Legacy"}` |
| config.operator.clusterData | object | Dataplane cluster configuration. | `(see values.yaml)` |
| config.operator.clusterData.appId | string | The client id used to authenticate to the control plane.  This will be provided by Union. | `"{{ tpl .Values.secrets.admin.clientId . }}"` |
| config.operator.clusterData.bucketName | string | The bucket name for object storage. | `"{{ tpl .Values.storage.bucketName . }}"` |
| config.operator.clusterData.bucketRegion | string | The bucket region for object storage. | `"{{ tpl .Values.storage.region . }}"` |
| config.operator.clusterData.cloudHostName | string | The hose name for control plane access. This will be provided by Union. | `"{{ tpl .Values.host . }}"` |
| config.operator.clusterData.gcpProjectId | string | For GCP only, the project id for object storage. | `"{{ tpl .Values.storage.gcp.projectId . }}"` |
| config.operator.clusterData.metadataBucketPrefix | string | The prefix for constructing object storage URLs. | `"{{ include \"storage.metadata-prefix\" . }}"` |
| config.operator.clusterId | object | Set the cluster information for the operator service | `{"organization":"{{ tpl .Values.orgName . }}"}` |
| config.operator.clusterId.organization | string | The organization name for the cluster.  This should match your organization name that you were provided. | `"{{ tpl .Values.orgName . }}"` |
| config.operator.collectUsages | object | Configuration for the usage reporting service. | `{"enabled":true}` |
| config.operator.collectUsages.enabled | bool | Enable usage collection in the operator service. | `true` |
| config.operator.dependenciesHeartbeat | object | Heartbeat check configuration. | `(see values.yaml)` |
| config.operator.dependenciesHeartbeat.prometheus | object | Define the prometheus health check endpoint. | `{"endpoint":"{{ include \"prometheus.health.url\" . }}"}` |
| config.operator.dependenciesHeartbeat.propeller | object | Define the propeller health check endpoint. | `{"endpoint":"{{ include \"propeller.health.url\" . }}"}` |
| config.operator.dependenciesHeartbeat.proxy | object | Define the operator proxy health check endpoint. | `{"endpoint":"{{ include \"proxy.health.url\" . }}"}` |
| config.operator.enableTunnelService | bool | Enable the cloudflare tunnel service for secure communication with the control plane. | `true` |
| config.operator.enabled | bool | Enables the operator service | `true` |
| config.operator.syncClusterConfig | object | Sync the configuration from the control plane. This will overwrite any configuration values set as part of the deploy. | `{"enabled":false}` |
| config.proxy | object | Configuration for the operator proxy service. | `(see values.yaml)` |
| config.proxy.smConfig | object | Secret manager configuration | `(see values.yaml)` |
| config.proxy.smConfig.enabled | string | Enable or disable secret manager support for the Union dataplane. | `"{{ .Values.proxy.secretManager.enabled }}"` |
| config.proxy.smConfig.k8sConfig | object | Kubernetes specific secret manager configuration. | `{"namespace":"{{ include \"proxy.secretsNamespace\" . }}"}` |
| config.proxy.smConfig.type | string | The type of secret manager to use. | `"{{ .Values.proxy.secretManager.type }}"` |
| config.resource_manager | object | Resource manager configuration | `{"propeller":{"resourcemanager":{"type":"noop"}}}` |
| config.resource_manager.propeller | object | resource manager configuration | `{"resourcemanager":{"type":"noop"}}` |
| config.sharedService | object | Section that configures shared union services | `{"features":{"gatewayV2":true},"port":8081}` |
| config.task_logs | object | Section that configures how the Task logs are displayed on the UI. This has to be changed based on your actual logging provider. Refer to [structure](https://pkg.go.dev/github.com/lyft/flyteplugins/go/tasks/logs#LogConfig) to understand how to configure various logging engines | `(see values.yaml)` |
| config.task_logs.plugins.logs.cloudwatch-enabled | bool | One option is to enable cloudwatch logging for EKS, update the region and log group accordingly | `false` |
| config.task_resource_defaults | object | Task default resources configuration Refer to the full [structure](https://pkg.go.dev/github.com/lyft/flyteadmin@v0.3.37/pkg/runtime/interfaces#TaskResourceConfiguration). | `(see values.yaml)` |
| config.task_resource_defaults.task_resources | object | Task default resources parameters | `{"defaults":{"cpu":"100m","memory":"500Mi"},"limits":{"cpu":4096,"gpu":256,"memory":"2Ti"}}` |
| config.union.connection | object | Connection information to the union control plane. | `{"host":"dns:///{{ tpl .Values.host . }}"}` |
| config.union.connection.host | string | Host to connect to | `"dns:///{{ tpl .Values.host . }}"` |
| cost.enabled | bool | Enable or disable the cost service resources.  This does not include the opencost or other compatible monitoring services. | `true` |
| cost.serviceMonitor.matchLabels | object | Match labels for the ServiceMonitor. | `{"app.kubernetes.io/name":"opencost"}` |
| cost.serviceMonitor.name | string | The name of the ServiceMonitor. | `"cost"` |
| databricks | object | Databricks integration configuration | `{"enabled":false,"plugin_config":{}}` |
| dcgm-exporter | object | Dcgm exporter configuration | `(see values.yaml)` |
| dcgm-exporter.enabled | bool | Enable or disable the dcgm exporter | `false` |
| dcgm-exporter.serviceMonitor | object | It's common practice to taint and label  to not run dcgm exporter on all nodes, so we can use node selectors and    tolerations to ensure it only runs on GPU nodes. affinity: {} nodeSelector: {} tolerations: [] | `{"enabled":false}` |
| executor.additionalVolumeMounts | list | Appends additional volume mounts to the main container's spec. May include template values. | `[]` |
| executor.additionalVolumes | list | Appends additional volumes to the deployment spec. May include template values. | `[]` |
| executor.affinity | object | affinity for executor deployment | `{}` |
| executor.config.cluster | string |  | `"{{ tpl .Values.clusterName . }}"` |
| executor.config.evaluatorCount | int |  | `64` |
| executor.config.maxActions | int |  | `2000` |
| executor.config.organization | string |  | `"{{ tpl .Values.orgName . }}"` |
| executor.config.unionAuth.injectSecret | bool |  | `true` |
| executor.config.unionAuth.secretName | string |  | `"EAGER_API_KEY"` |
| executor.config.workerName | string |  | `"worker1"` |
| executor.enabled | bool |  | `true` |
| executor.idl2Executor | bool |  | `false` |
| executor.nodeName | string | nodeName constraints for executor deployment | `""` |
| executor.nodeSelector | object | nodeSelector for executor deployment | `{}` |
| executor.plugins.fasttask | object | Configuration section for all K8s specific plugins [Configuration structure](https://pkg.go.dev/github.com/lyft/flyteplugins/go/tasks/pluginmachinery/flytek8s/config) | `(see values.yaml)` |
| executor.plugins.ioutils.remoteFileOutputPaths.deckFilename | string |  | `"report.html"` |
| executor.plugins.k8s.disable-inject-owner-references | bool |  | `true` |
| executor.podEnv | list | Appends additional environment variables to the executor container's spec. | `[]` |
| executor.podLabels.app | string |  | `"executor"` |
| executor.propeller.node-config.disable-input-file-writes | bool |  | `true` |
| executor.raw_config | object |  | `{}` |
| executor.resources.limits.cpu | int |  | `4` |
| executor.resources.limits.memory | string |  | `"8Gi"` |
| executor.resources.requests.cpu | int |  | `1` |
| executor.resources.requests.memory | string |  | `"1Gi"` |
| executor.serviceAccount.annotations | object |  | `{}` |
| executor.sharedService.metrics.scope | string |  | `"executor:"` |
| executor.sharedService.security.allowCors | bool |  | `true` |
| executor.sharedService.security.allowLocalhostAccess | bool |  | `true` |
| executor.sharedService.security.allowedHeaders[0] | string |  | `"Content-Type"` |
| executor.sharedService.security.allowedOrigins[0] | string |  | `"*"` |
| executor.sharedService.security.secure | bool |  | `false` |
| executor.sharedService.security.useAuth | bool |  | `false` |
| executor.task_logs.plugins.logs.cloudwatch-enabled | bool | One option is to enable cloudwatch logging for EKS, update the region and log group accordingly | `false` |
| executor.task_logs.plugins.logs.dynamic-log-links[0].vscode.displayName | string |  | `"VS Code Debugger"` |
| executor.task_logs.plugins.logs.dynamic-log-links[0].vscode.linkType | string |  | `"ide"` |
| executor.task_logs.plugins.logs.dynamic-log-links[0].vscode.templateUris[0] | string |  | `(see values.yaml)` |
| executor.task_logs.plugins.logs.dynamic-log-links[1].wandb-execution-id.displayName | string |  | `"Weights & Biases"` |
| executor.task_logs.plugins.logs.dynamic-log-links[1].wandb-execution-id.linkType | string |  | `"dashboard"` |
| executor.task_logs.plugins.logs.dynamic-log-links[1].wandb-execution-id.templateUris[0] | string |  | `(see values.yaml)` |
| executor.task_logs.plugins.logs.dynamic-log-links[2].wandb-custom-id.displayName | string |  | `"Weights & Biases"` |
| executor.task_logs.plugins.logs.dynamic-log-links[2].wandb-custom-id.linkType | string |  | `"dashboard"` |
| executor.task_logs.plugins.logs.dynamic-log-links[2].wandb-custom-id.templateUris[0] | string |  | `(see values.yaml)` |
| executor.task_logs.plugins.logs.dynamic-log-links[3].comet-ml-execution-id.displayName | string |  | `"Comet"` |
| executor.task_logs.plugins.logs.dynamic-log-links[3].comet-ml-execution-id.linkType | string |  | `"dashboard"` |
| executor.task_logs.plugins.logs.dynamic-log-links[3].comet-ml-execution-id.templateUris | string |  | `(see values.yaml)` |
| executor.task_logs.plugins.logs.dynamic-log-links[4].comet-ml-custom-id.displayName | string |  | `"Comet"` |
| executor.task_logs.plugins.logs.dynamic-log-links[4].comet-ml-custom-id.linkType | string |  | `"dashboard"` |
| executor.task_logs.plugins.logs.dynamic-log-links[4].comet-ml-custom-id.templateUris | string |  | `(see values.yaml)` |
| executor.task_logs.plugins.logs.dynamic-log-links[5].neptune-scale-run.displayName | string |  | `"Neptune Run"` |
| executor.task_logs.plugins.logs.dynamic-log-links[5].neptune-scale-run.linkType | string |  | `"dashboard"` |
| executor.task_logs.plugins.logs.dynamic-log-links[5].neptune-scale-run.templateUris[0] | string |  | `"https://scale.neptune.ai/{{`{{ .taskConfig.project }}`}}/-/run/?customId={{`{{ .podName }}`}}"` |
| executor.task_logs.plugins.logs.dynamic-log-links[6].neptune-scale-custom-id.displayName | string |  | `"Neptune Run"` |
| executor.task_logs.plugins.logs.dynamic-log-links[6].neptune-scale-custom-id.linkType | string |  | `"dashboard"` |
| executor.task_logs.plugins.logs.dynamic-log-links[6].neptune-scale-custom-id.templateUris[0] | string |  | `(see values.yaml)` |
| executor.task_logs.plugins.logs.kubernetes-enabled | bool |  | `true` |
| executor.tolerations | list | tolerations for executor deployment | `[]` |
| executor.topologySpreadConstraints | object | topologySpreadConstraints for executor deployment | `{}` |
| extraObjects | list |  | `[]` |
| fluentbit | object | Configuration for fluentbit used for the persistent logging feature. FluentBit runs as a DaemonSet and ships container logs to the persisted-logs/ path in the configured object store. The fluentbit-system service account must have write access to the storage bucket.  Grant access using cloud-native identity federation:   AWS (IRSA):     annotations:       eks.amazonaws.com/role-arn: "arn:aws:iam::`<ACCOUNT_ID>`:role/`<ROLE_NAME>`"   Azure (Workload Identity):     annotations:       azure.workload.identity/client-id: "`<CLIENT_ID>`"   GCP (Workload Identity):     annotations:       iam.gke.io/gcp-service-account: "`<GSA_NAME>`@`<PROJECT_ID>`.iam.gserviceaccount.com"  See https://www.union.ai/docs/v1/selfmanaged/deployment/configuration/persistent-logs/ | `(see values.yaml)` |
| flyteagent | object | Flyteagent configuration | `{"enabled":false,"plugin_config":{}}` |
| flyteconnector.additionalContainers | list | Appends additional containers to the deployment spec. May include template values. | `[]` |
| flyteconnector.additionalEnvs | list | Appends additional envs to the deployment spec. May include template values | `[]` |
| flyteconnector.additionalVolumeMounts | list | Appends additional volume mounts to the main container's spec. May include template values. | `[]` |
| flyteconnector.additionalVolumes | list | Appends additional volumes to the deployment spec. May include template values. | `[]` |
| flyteconnector.affinity | object | affinity for flyteconnector deployment | `{}` |
| flyteconnector.autoscaling.maxReplicas | int |  | `5` |
| flyteconnector.autoscaling.minReplicas | int |  | `2` |
| flyteconnector.autoscaling.targetCPUUtilizationPercentage | int |  | `80` |
| flyteconnector.autoscaling.targetMemoryUtilizationPercentage | int |  | `80` |
| flyteconnector.configPath | string | Default glob string for searching configuration files | `"/etc/flyteconnector/config/*.yaml"` |
| flyteconnector.enabled | bool |  | `false` |
| flyteconnector.extraArgs | object | Appends extra command line arguments to the main command | `{}` |
| flyteconnector.image.pullPolicy | string | Docker image pull policy | `"IfNotPresent"` |
| flyteconnector.image.repository | string | Docker image for flyteconnector deployment | `"ghcr.io/flyteorg/flyte-connectors"` |
| flyteconnector.image.tag | string |  | `"py3.13-2.0.0b50.dev3-g695bb1db3.d20260122"` |
| flyteconnector.nodeSelector | object | nodeSelector for flyteconnector deployment | `{}` |
| flyteconnector.podAnnotations | object | Annotations for flyteconnector pods | `{}` |
| flyteconnector.ports.containerPort | int |  | `8000` |
| flyteconnector.ports.name | string |  | `"grpc"` |
| flyteconnector.priorityClassName | string | Sets priorityClassName for datacatalog pod(s). | `""` |
| flyteconnector.prometheusPort.containerPort | int |  | `9090` |
| flyteconnector.prometheusPort.name | string |  | `"metric"` |
| flyteconnector.replicaCount | int | Replicas count for flyteconnector deployment | `2` |
| flyteconnector.resources | object | Default resources requests and limits for flyteconnector deployment | `(see values.yaml)` |
| flyteconnector.service | object | Service settings for flyteconnector | `{"clusterIP":"None","type":"ClusterIP"}` |
| flyteconnector.serviceAccount | object | Configuration for service accounts for flyteconnector | `{"annotations":{},"create":true,"imagePullSecrets":[]}` |
| flyteconnector.serviceAccount.annotations | object | Annotations for ServiceAccount attached to flyteconnector pods | `{}` |
| flyteconnector.serviceAccount.create | bool | Should a service account be created for flyteconnector | `true` |
| flyteconnector.serviceAccount.imagePullSecrets | list | ImagePullSecrets to automatically assign to the service account | `[]` |
| flyteconnector.tolerations | list | tolerations for flyteconnector deployment | `[]` |
| flytepropeller | object | Flytepropeller configuration | `(see values.yaml)` |
| flytepropeller.additionalVolumeMounts | list | Appends additional volume mounts to the main container's spec. May include template values. | `[]` |
| flytepropeller.additionalVolumes | list | Appends additional volumes to the deployment spec. May include template values. | `[]` |
| flytepropeller.affinity | object | affinity for Flytepropeller deployment | `{}` |
| flytepropeller.configPath | string | Default regex string for searching configuration files | `"/etc/flyte/config/*.yaml"` |
| flytepropeller.extraArgs | object | extra arguments to pass to propeller. | `{}` |
| flytepropeller.nodeName | string | nodeName constraints for Flytepropeller deployment | `""` |
| flytepropeller.nodeSelector | object | nodeSelector for Flytepropeller deployment | `{}` |
| flytepropeller.podAnnotations | object | Annotations for Flytepropeller pods | `{}` |
| flytepropeller.podLabels | object | Labels for the Flytepropeller pods | `{}` |
| flytepropeller.replicaCount | int | Replicas count for Flytepropeller deployment | `1` |
| flytepropeller.resources | object | Default resources requests and limits for Flytepropeller deployment | `{"limits":{"cpu":"3","memory":"3Gi"},"requests":{"cpu":"1","memory":"1Gi"}}` |
| flytepropeller.serviceAccount | object | Configuration for service accounts for FlytePropeller | `{"annotations":{},"imagePullSecrets":[]}` |
| flytepropeller.serviceAccount.annotations | object | Annotations for ServiceAccount attached to FlytePropeller pods | `{}` |
| flytepropeller.serviceAccount.imagePullSecrets | list | ImapgePullSecrets to automatically assign to the service account | `[]` |
| flytepropeller.tolerations | list | tolerations for Flytepropeller deployment | `[]` |
| flytepropeller.topologySpreadConstraints | object | topologySpreadConstraints for Flytepropeller deployment | `{}` |
| flytepropellerwebhook | object | Configuration for the Flytepropeller webhook | `(see values.yaml)` |
| flytepropellerwebhook.additionalVolumeMounts | list | Appends additional volume mounts to the main container's spec. May include template values. | `[]` |
| flytepropellerwebhook.additionalVolumes | list | Appends additional volumes to the deployment spec. May include template values. | `[]` |
| flytepropellerwebhook.affinity | object | affinity for webhook deployment | `{}` |
| flytepropellerwebhook.enabled | bool | enable or disable secrets webhook | `true` |
| flytepropellerwebhook.nodeName | string | nodeName constraints for webhook deployment | `""` |
| flytepropellerwebhook.nodeSelector | object | nodeSelector for webhook deployment | `{}` |
| flytepropellerwebhook.podAnnotations | object | Annotations for webhook pods | `{}` |
| flytepropellerwebhook.podEnv | object | Additional webhook container environment variables | `{}` |
| flytepropellerwebhook.podLabels | object | Labels for webhook pods | `{}` |
| flytepropellerwebhook.priorityClassName | string | Sets priorityClassName for webhook pod | `""` |
| flytepropellerwebhook.replicaCount | int | Replicas | `1` |
| flytepropellerwebhook.securityContext | object | Sets securityContext for webhook pod(s). | `(see values.yaml)` |
| flytepropellerwebhook.service | object | Service settings for the webhook | `(see values.yaml)` |
| flytepropellerwebhook.service.port | int | HTTPS port for the webhook service | `443` |
| flytepropellerwebhook.service.targetPort | int | Target port for the webhook service (container port) | `9443` |
| flytepropellerwebhook.serviceAccount | object | Configuration for service accounts for the webhook | `{"imagePullSecrets":[]}` |
| flytepropellerwebhook.serviceAccount.imagePullSecrets | list | ImagePullSecrets to automatically assign to the service account | `[]` |
| flytepropellerwebhook.tolerations | list | tolerations for webhook deployment | `[]` |
| flytepropellerwebhook.topologySpreadConstraints | object | topologySpreadConstraints for webhook deployment | `{}` |
| fullnameOverride | string | Override the chart fullname. | `""` |
| global.CLIENT_ID | string |  | `""` |
| global.CLUSTER_NAME | string |  | `""` |
| global.FAST_REGISTRATION_BUCKET | string |  | `""` |
| global.METADATA_BUCKET | string |  | `""` |
| global.ORG_NAME | string |  | `""` |
| global.UNION_CONTROL_PLANE_HOST | string |  | `""` |
| host | string | Set the control plane host for your Union dataplane installation.  This will be provided by Union. | `"{{ .Values.global.UNION_CONTROL_PLANE_HOST }}"` |
| image.flytecopilot | object | flytecopilot repository and tag. | `{"pullPolicy":"IfNotPresent","repository":"cr.flyte.org/flyteorg/flytecopilot","tag":"v1.14.1"}` |
| image.kubeStateMetrics | object | Kubestatemetrics repository and tag. | `(see values.yaml)` |
| image.union | object | Image repository for the operator and union services | `{"pullPolicy":"IfNotPresent","repository":"public.ecr.aws/p0i0a9q8/unionoperator","tag":""}` |
| imageBuilder.authenticationType | string | "azure" uses az acr login to authenticate to the default registry. Requires Azure Workload Identity to be enabled. | `"noop"` |
| imageBuilder.buildkit.additionalVolumeMounts | list | Additional volume mounts to add to the buildkit container | `[]` |
| imageBuilder.buildkit.additionalVolumes | list | Additional volumes to add to the pod | `[]` |
| imageBuilder.buildkit.autoscaling | object | buildkit HPA configuration | `{"enabled":false,"maxReplicas":2,"minReplicas":1,"targetCPUUtilizationPercentage":60}` |
| imageBuilder.buildkit.autoscaling.targetCPUUtilizationPercentage | int | We can adjust this as needed. | `60` |
| imageBuilder.buildkit.deploymentStrategy | string | deployment strategy for buildkit deployment | `"Recreate"` |
| imageBuilder.buildkit.enabled | bool | Enable buildkit service within this release. | `true` |
| imageBuilder.buildkit.fullnameOverride | string | The name to use for the buildkit deployment, service, configmap, etc. | `""` |
| imageBuilder.buildkit.image.pullPolicy | string | Pull policy | `"IfNotPresent"` |
| imageBuilder.buildkit.image.repository | string | Image name | `"docker.io/moby/buildkit"` |
| imageBuilder.buildkit.image.tag | e.g. "buildx-stable-1" becomes "buildx-stable-1-rootless" | unless the tag already contains "rootless". | `"buildx-stable-1"` |
| imageBuilder.buildkit.log | object | Enable debug logging | `{"debug":false,"format":"text"}` |
| imageBuilder.buildkit.nodeSelector | object | Node selector | `{}` |
| imageBuilder.buildkit.oci | object | Buildkitd service configuration | `{"maxParallelism":0}` |
| imageBuilder.buildkit.oci.maxParallelism | int | maxParalelism limits the number of concurrent builds, default is 0 (unbounded) | `0` |
| imageBuilder.buildkit.pdb.minAvailable | int | Minimum available pods | `1` |
| imageBuilder.buildkit.podAnnotations | object | Pod annotations | `{}` |
| imageBuilder.buildkit.podEnv | list | Appends additional environment variables to the buildkit container's spec. | `[]` |
| imageBuilder.buildkit.replicaCount | int | Replicas count for Buildkit deployment | `1` |
| imageBuilder.buildkit.resources | object | Resource definitions | `{"requests":{"cpu":1,"ephemeral-storage":"20Gi","memory":"1Gi"}}` |
| imageBuilder.buildkit.rootless | bool | kernel >= 5.11 with unprivileged user namespace support. | `true` |
| imageBuilder.buildkit.service.annotations | object | Service annotations | `{}` |
| imageBuilder.buildkit.service.loadbalancerIp | string | Static ip address for load balancer | `""` |
| imageBuilder.buildkit.service.port | int | Service port | `1234` |
| imageBuilder.buildkit.service.type | string | Service type | `"ClusterIP"` |
| imageBuilder.buildkit.serviceAccount | object | Service account configuration for buildkit | `{"annotations":{},"create":true,"imagePullSecret":"","name":"union-imagebuilder"}` |
| imageBuilder.buildkit.tolerations | list | Tolerations | `[]` |
| imageBuilder.buildkitUri | string | E.g. "tcp://buildkitd.buildkit.svc.cluster.local:1234" | `""` |
| imageBuilder.defaultRepository | string | Note, the build-image task will fail unless "registry" is specified or a default repository is provided. | `""` |
| imageBuilder.enabled | bool |  | `true` |
| imageBuilder.targetConfigMapName | string | Should not change unless coordinated with Union technical support. | `"build-image-config"` |
| ingress-nginx.controller.admissionWebhooks.enabled | bool |  | `false` |
| ingress-nginx.controller.allowSnippetAnnotations | bool |  | `true` |
| ingress-nginx.controller.config.annotations-risk-level | string |  | `"Critical"` |
| ingress-nginx.controller.config.grpc-connect-timeout | string |  | `"1200"` |
| ingress-nginx.controller.config.grpc-read-timeout | string |  | `"604800"` |
| ingress-nginx.controller.config.grpc-send-timeout | string |  | `"604800"` |
| ingress-nginx.controller.ingressClassResource.controllerValue | string |  | `"union.ai/dataplane"` |
| ingress-nginx.controller.ingressClassResource.default | bool |  | `false` |
| ingress-nginx.controller.ingressClassResource.enabled | bool |  | `true` |
| ingress-nginx.controller.ingressClassResource.name | string |  | `"dataplane"` |
| ingress-nginx.enabled | bool |  | `false` |
| ingress.dataproxy | object | Dataproxy specific ingress configuration. | `{"annotations":{},"class":"","hostOverride":"","tls":{}}` |
| ingress.dataproxy.annotations | object | Annotations to apply to the ingress resource. | `{}` |
| ingress.dataproxy.class | string | Ingress class name | `""` |
| ingress.dataproxy.hostOverride | string | Ingress host | `""` |
| ingress.dataproxy.tls | object | Ingress TLS configuration | `{}` |
| ingress.enabled | bool |  | `false` |
| ingress.host | string |  | `""` |
| ingress.serving | object | Serving specific ingress configuration. | `{"annotations":{},"class":"","hostOverride":"","tls":{}}` |
| ingress.serving.annotations | object | Annotations to apply to the ingress resource. | `{}` |
| ingress.serving.class | string | Ingress class name | `""` |
| ingress.serving.hostOverride | Optional | Host override for serving ingress rule. Defaults to *.apps.{{ .Values.host }}. | `""` |
| ingress.serving.tls | object | Ingress TLS configuration | `{}` |
| knative-operator.crds.install | bool |  | `true` |
| knative-operator.enabled | bool |  | `false` |
| kube-state-metrics | object | Standalone kube-state-metrics for Union features (cost tracking, pod resource metrics). Metric filtering is handled in the Prometheus static scrape config. | `{}` |
| low_privilege | bool | Scopes the deployment, permissions and actions created into a single namespace | `false` |
| metrics-server.enabled | bool |  | `false` |
| monitoring.alerting.enabled | bool |  | `false` |
| monitoring.alertmanager.enabled | bool |  | `false` |
| monitoring.coreDns.enabled | bool |  | `true` |
| monitoring.crds.enabled | bool |  | `false` |
| monitoring.dashboards.enabled | bool |  | `true` |
| monitoring.dashboards.label | string |  | `"grafana_dashboard"` |
| monitoring.dashboards.labelValue | string |  | `"1"` |
| monitoring.defaultRules.create | bool |  | `true` |
| monitoring.enabled | bool |  | `false` |
| monitoring.fullnameOverride | string |  | `"monitoring"` |
| monitoring.grafana.adminPassword | string |  | `"admin"` |
| monitoring.grafana.enabled | bool |  | `true` |
| monitoring.grafana.fullNameOverride | string |  | `"monitoring-grafana"` |
| monitoring.kube-state-metrics.fullnameOverride | string |  | `"monitoring-kube-state-metrics"` |
| monitoring.kube-state-metrics.nameOverride | string |  | `"monitoring-kube-state-metrics"` |
| monitoring.kubeApiServer.enabled | bool |  | `true` |
| monitoring.kubeControllerManager.enabled | bool |  | `true` |
| monitoring.kubeEtcd.enabled | bool |  | `true` |
| monitoring.kubeProxy.enabled | bool |  | `true` |
| monitoring.kubeScheduler.enabled | bool |  | `true` |
| monitoring.kubeStateMetrics.enabled | bool |  | `true` |
| monitoring.kubelet.enabled | bool |  | `true` |
| monitoring.nameOverride | string |  | `"monitoring"` |
| monitoring.nodeExporter.enabled | bool |  | `true` |
| monitoring.prometheus.agentMode | bool |  | `false` |
| monitoring.prometheus.enabled | bool |  | `true` |
| monitoring.prometheus.prometheusSpec.maximumStartupDurationSeconds | int |  | `600` |
| monitoring.prometheus.prometheusSpec.podMonitorSelectorNilUsesHelmValues | bool |  | `false` |
| monitoring.prometheus.prometheusSpec.resources.limits.cpu | string |  | `"2"` |
| monitoring.prometheus.prometheusSpec.resources.limits.memory | string |  | `"4Gi"` |
| monitoring.prometheus.prometheusSpec.resources.requests.cpu | string |  | `"500m"` |
| monitoring.prometheus.prometheusSpec.resources.requests.memory | string |  | `"1Gi"` |
| monitoring.prometheus.prometheusSpec.retention | string |  | `"7d"` |
| monitoring.prometheus.prometheusSpec.ruleSelectorNilUsesHelmValues | bool |  | `false` |
| monitoring.prometheus.prometheusSpec.serviceMonitorSelectorNilUsesHelmValues | bool |  | `false` |
| monitoring.prometheus.service.port | int |  | `80` |
| monitoring.prometheusOperator.enabled | bool |  | `true` |
| monitoring.prometheusRules.enabled | bool |  | `true` |
| monitoring.serviceMonitors.enabled | bool |  | `true` |
| monitoring.slos.alerting.enabled | bool |  | `false` |
| monitoring.slos.enabled | bool |  | `false` |
| monitoring.slos.targets.availability | float |  | `0.999` |
| monitoring.slos.targets.latencyP99 | int |  | `5` |
| nameOverride | string | Override the chart name. | `""` |
| namespace_mapping | object | Namespace mapping template for mapping Union runs to Kubernetes namespaces. This is the canonical source of truth. All dataplane services (propeller, clusterresourcesync, operator, executor) will inherit this value unless explicitly overridden in their service-specific config sections (config.namespace_config, config.operator.org, executor.raw_config). | `{}` |
| namespaces.enabled | bool |  | `true` |
| nodeobserver | object | nodeobserver contains the configuration information for the node observer service. | `(see values.yaml)` |
| nodeobserver.additionalVolumeMounts | list | Appends additional volume mounts to the main container's spec. May include template values. | `[]` |
| nodeobserver.additionalVolumes | list | Appends additional volumes to the daemonset spec. May include template values. | `[]` |
| nodeobserver.affinity | object | affinity configurations for the pods associated with nodeobserver services | `{}` |
| nodeobserver.enabled | bool | Enable or disable nodeobserver | `false` |
| nodeobserver.nodeName | string | nodeName constraints for the pods associated with nodeobserver services | `""` |
| nodeobserver.nodeSelector | object | nodeSelector constraints for the pods associated with nodeobserver services | `{}` |
| nodeobserver.podAnnotations | object | Additional pod annotations for the nodeobserver services | `{}` |
| nodeobserver.podEnv | list | Additional pod environment variables for the nodeobserver services | `(see values.yaml)` |
| nodeobserver.resources | object | Kubernetes resource configuration for the nodeobserver service | `{"limits":{"cpu":"1","memory":"500Mi"},"requests":{"cpu":"500m","memory":"100Mi"}}` |
| nodeobserver.tolerations | list | tolerations for the pods associated with nodeobserver services | `[{"effect":"NoSchedule","operator":"Exists"}]` |
| nodeobserver.topologySpreadConstraints | object | topologySpreadConstraints for the pods associated with nodeobserver services | `{}` |
| objectStore | object | Union Object Store configuration | `{"service":{"grpcPort":8089,"httpPort":8080}}` |
| opencost.enabled | bool | Enable or disable the opencost installation. | `true` |
| opencost.opencost.exporter.resources.limits.cpu | string |  | `"1000m"` |
| opencost.opencost.exporter.resources.limits.memory | string |  | `"4Gi"` |
| opencost.opencost.exporter.resources.requests.cpu | string |  | `"500m"` |
| opencost.opencost.exporter.resources.requests.memory | string |  | `"1Gi"` |
| opencost.opencost.metrics.serviceMonitor.enabled | bool |  | `false` |
| opencost.opencost.prometheus.external.enabled | bool |  | `true` |
| opencost.opencost.prometheus.external.url | string |  | `"http://union-operator-prometheus.{{.Release.Namespace}}.svc:80/prometheus"` |
| opencost.opencost.prometheus.internal.enabled | bool |  | `false` |
| opencost.opencost.ui.enabled | bool |  | `false` |
| operator.additionalVolumeMounts | list | Appends additional volume mounts to the main container's spec. May include template values. | `[]` |
| operator.additionalVolumes | list | Appends additional volumes to the deployment spec. May include template values. | `[]` |
| operator.affinity | object | affinity configurations for the operator pods | `{}` |
| operator.autoscaling.enabled | bool |  | `false` |
| operator.enableTunnelService | bool |  | `true` |
| operator.imagePullSecrets | list |  | `[]` |
| operator.nodeName | string | nodeName constraints for the operator pods | `""` |
| operator.nodeSelector | object | nodeSelector constraints for the operator pods | `{}` |
| operator.podAnnotations | object |  | `{}` |
| operator.podEnv | object |  | `{}` |
| operator.podLabels | object |  | `{}` |
| operator.podSecurityContext | object |  | `{}` |
| operator.priorityClassName | string |  | `""` |
| operator.replicas | int |  | `1` |
| operator.resources.limits.cpu | string |  | `"2"` |
| operator.resources.limits.memory | string |  | `"3Gi"` |
| operator.resources.requests.cpu | string |  | `"1"` |
| operator.resources.requests.memory | string |  | `"1Gi"` |
| operator.secretName | string |  | `"union-secret-auth"` |
| operator.securityContext | object |  | `{}` |
| operator.serviceAccount.annotations | object |  | `{}` |
| operator.serviceAccount.create | bool |  | `true` |
| operator.serviceAccount.name | string |  | `"operator-system"` |
| operator.tolerations | list | tolerations for the operator pods | `[]` |
| operator.topologySpreadConstraints | object | topologySpreadConstraints for the operator pods | `{}` |
| orgName | string | Organization name should be provided by Union. | `"{{ .Values.global.ORG_NAME }}"` |
| prometheus | object | Union features Prometheus configuration. Deploys a static Prometheus instance (no Prometheus Operator required) for Union features like cost tracking and task-level monitoring. | `(see values.yaml)` |
| prometheus.affinity | object | Affinity rules for the Prometheus pod. | `{}` |
| prometheus.nodeSelector | object | Node selector for the Prometheus pod. | `{}` |
| prometheus.priorityClassName | string | Priority class for the Prometheus pod. | `"system-cluster-critical"` |
| prometheus.resources | object | Resource limits and requests. | `{"limits":{"cpu":"3","memory":"3500Mi"},"requests":{"cpu":"1","memory":"1Gi"}}` |
| prometheus.retention | string | Data retention period. | `"3d"` |
| prometheus.routePrefix | string | Route prefix for Prometheus web UI and API. | `"/prometheus/"` |
| prometheus.serviceAccount | object | Service account configuration. | `{"annotations":{},"create":true}` |
| prometheus.tolerations | list | Tolerations for the Prometheus pod. | `[]` |
| proxy | object | Union operator proxy configuration | `(see values.yaml)` |
| proxy.additionalVolumeMounts | list | Appends additional volume mounts to the main container's spec. May include template values. | `[]` |
| proxy.additionalVolumes | list | Appends additional volumes to the deployment spec. May include template values. | `[]` |
| proxy.affinity | object | affinity configurations for the proxy pods | `{}` |
| proxy.nodeName | string | nodeName constraint for the proxy pods | `""` |
| proxy.nodeSelector | object | nodeSelector constraints for the proxy pods | `{}` |
| proxy.secretManager.namespace | string | Set the namespace for union managed secrets created through the native Kubernetes secret manager. If the namespace is not set, the release namespace will be used. | `""` |
| proxy.tolerations | list | tolerations for the proxy pods | `[]` |
| proxy.topologySpreadConstraints | object | topologySpreadConstraints for the proxy pods | `{}` |
| resourcequota | object | Create global resource quotas for the cluster. | `{"create":false}` |
| scheduling | object | Global kubernetes scheduling constraints that will be applied to the pods.  Application specific constraints will always take precedence. | `{"affinity":{},"nodeName":"","nodeSelector":{},"tolerations":[],"topologySpreadConstraints":{}}` |
| scheduling.affinity | object | See https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node | `{}` |
| scheduling.nodeSelector | object | See https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node | `{}` |
| scheduling.tolerations | list | See https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration | `[]` |
| scheduling.topologySpreadConstraints | object | See https://kubernetes.io/docs/concepts/scheduling-eviction/topology-spread-constraints | `{}` |
| secrets | object | Connection secrets for the Union control plane services. | `{"admin":{"clientId":"dataplane-operator","clientSecret":"","create":true,"enable":true}}` |
| secrets.admin.clientId | string | The client id used to authenticate to the control plane.  This will be provided by Union. | `"dataplane-operator"` |
| secrets.admin.clientSecret | string | The client secret used to authenticate to the control plane.  This will be provided by Union. | `""` |
| secrets.admin.create | bool | Create the secret resource containing the client id and secret.  If set to false the user is responsible for creating the secret before the installation. | `true` |
| secrets.admin.enable | bool | Enable or disable the admin secret.  This is used to authenticate to the control plane. | `true` |
| serving | object | Configure app serving and knative. | `(see values.yaml)` |
| serving.auth | object | Union authentication and authorization configuration. | `{"enabled":true}` |
| serving.auth.enabled | bool | Disabling is common if not leveraging Union Cloud SSO. | `true` |
| serving.enabled | bool | Enables the serving components. Installs Knative Serving. Knative-Operator must be running in the cluster for this to work. Enables app serving in operator. | `false` |
| serving.extraConfig | object | Additional configuration for Knative serving | `{}` |
| serving.metrics | bool | Enables scraping of metrics from the serving component | `true` |
| serving.replicas | int | The number of replicas to create for all components for high availability. | `2` |
| serving.resources | object | Resources for serving components | `(see values.yaml)` |
| sparkoperator.enabled | bool |  | `false` |
| sparkoperator.plugin_config | object |  | `{}` |
| storage | object | Object storage configuration used by all Union services. | `(see values.yaml)` |
| storage.accessKey | string | The access key used for object storage. | `""` |
| storage.authType | string | The authentication type.  Currently supports "accesskey" and "iam". | `"accesskey"` |
| storage.bucketName | string | The bucket name used for object storage. | `"{{ .Values.global.METADATA_BUCKET }}"` |
| storage.cache | object | Cache configuration for objects retrieved from object storage. | `{"maxSizeMBs":0,"targetGCPercent":70}` |
| storage.custom | object | Define custom configurations for the object storage.  Only used if the provider is set to "custom". | `{}` |
| storage.disableSSL | bool | Disable SSL for object storage.  This should only used for local/sandbox installations. | `false` |
| storage.endpoint | string | Define or override the endpoint used for the object storage service. | `""` |
| storage.fastRegistrationBucketName | string | The bucket name used for fast registration uploads. | `"{{ .Values.global.FAST_REGISTRATION_BUCKET }}"` |
| storage.fastRegistrationURL | string | Override the URL for signed fast registration uploads.  This is only used for local/sandbox installations. | `""` |
| storage.gcp | object | Define GCP specific configuration for object storage. | `{"projectId":""}` |
| storage.injectPodEnvVars | bool | Injects the object storage access information into the pod environment variables.  Needed for providers that only support access and secret key based authentication. | `true` |
| storage.limits | object | Internal service limits for object storage access. | `{"maxDownloadMBs":1024}` |
| storage.metadataPrefix | string | Example for Azure: "abfs://my-container@mystorageaccount.dfs.core.windows.net" | `""` |
| storage.provider | string | The storage provider to use.  Currently supports "compat", "aws", "oci", and "custom". | `"compat"` |
| storage.region | string | The bucket region used for object storage. | `"us-east-1"` |
| storage.s3ForcePathStyle | bool | Use path style instead of domain style urls to access the object storage service. | `true` |
| storage.secretKey | string | The secret key used for object storage. | `""` |
| userRoleAnnotationKey | string | This is the annotation key that is added to service accounts.  Used with GCP and AWS. | `"eks.amazonaws.com/role-arn"` |
| userRoleAnnotationValue | string | This is the value of the annotation key that is added to service accounts. Used with GCP and AWS. | `"arn:aws:iam::ACCOUNT_ID:role/flyte_project_role"` |


=== PAGE: https://www.union.ai/docs/v2/union/deployment/selfmanaged/helm-chart-reference/knative-operator ===

Deploys Knative Operator

## Chart info

| | |
|---|---|
| **Chart version** | 2025.6.3 |
| **App version** | 1.16.0 |
| **Kubernetes version** | `>= 1.28.0-0` |

## Values

| Key | Type | Description | Default |
|-----|------|-------------|---------|
| crds.install | bool |  | `true` |


=== PAGE: https://www.union.ai/docs/v2/union/deployment/terraform ===

# Managing Union with Terraform

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

Union provides a Terraform provider that enables infrastructure-as-code management of your Union deployment. With the Union Terraform provider, you can define, deploy, and manage Union resources using declarative configuration files.

## Overview

The Union Terraform provider allows you to manage Union resources programmatically, including:

- **Projects**: Create and manage Union projects
- **Access Control**: Configure users, roles, and policies
- **API Keys**: Generate and manage API keys for automation
- **OAuth Applications**: Set up OAuth applications for external integrations
- **Access Assignments**: Assign users and applications to resources

## Why use Terraform?

Using Terraform to manage Union provides several benefits:

- **Version Control**: Track changes to your Union configuration over time
- **Reproducibility**: Easily replicate configurations across environments
- **Automation**: Integrate Union management into your CI/CD pipelines
- **Consistency**: Ensure consistent configuration across your organization
- **Documentation**: Your Terraform files serve as living documentation

## Getting Started

To get started with the Union Terraform provider:

1. **Installation**: Set up the Terraform provider in your environment
2. **Management**: Learn about the available resources and data sources for managing Union

### **Managing Union with Terraform > Installing the Union Terraform Provider**

Install and configure the Union Terraform provider

### **Managing Union with Terraform > Managing Union Resources with Terraform**

Learn about available resources and data sources

### **Managing Union with Terraform > Security Best Practices**

Securely manage API keys and credentials

## Requirements

- Terraform >= 1.0
- Union API key (generated using the **Flyte CLI > flyte > flyte create > flyte create config**)
- Access to a Union deployment

## Subpages
- **Managing Union with Terraform > Installing the Union Terraform Provider**
- **Managing Union with Terraform > Managing Union Resources with Terraform**
- **Managing Union with Terraform > Security Best Practices**


=== PAGE: https://www.union.ai/docs/v2/union/deployment/terraform/installation ===

# Installing the Union Terraform Provider

Documentation for installing and configuring the Union Terraform provider is coming soon.

In the meantime, you can find the latest information about the provider in the [Terraform Registry](https://registry.terraform.io/providers/unionai/unionai/latest/docs).

## Quick Start

To use the Union Terraform provider, add it to your Terraform configuration:

```hcl
terraform {
  required_providers {
    unionai = {
      source  = "unionai/unionai"
      version = "~> 1.0"
    }
  }
}

provider "unionai" {
  api_key = var.unionai_api_key
}
```

> **Security Note:** Never hardcode API keys in your Terraform files. See [Security Best Practices](./security) for recommended approaches to securely manage your API keys.

## Versioning

To choose the appropriate version of the provider (likely you should choose latest):

1. Visit the Provider Registry site and observe the latest version number
2. Use that version number in the provider declaration above

For detailed installation instructions, please refer to the [Terraform Registry documentation](https://registry.terraform.io/providers/unionai/unionai/latest/docs).


=== PAGE: https://www.union.ai/docs/v2/union/deployment/terraform/management ===

# Managing Union Resources with Terraform

The Union Terraform provider enables you to manage Union resources using infrastructure-as-code principles. This page provides an overview of the provider's capabilities, including authentication, available resources, and data sources.

## Provider Configuration

### Basic Configuration

Configure the Union provider in your Terraform configuration:

```hcl
terraform {
  required_providers {
    unionai = {
      source  = "unionai/unionai"
      version = "~> 1.0"
    }
  }
}

provider "unionai" {
  api_key      = var.unionai_api_key
  allowed_orgs = ["your-org-name"]
}
```

### Configuration Parameters

- **`api_key`** (Required): Your Union API key for authentication
- **`allowed_orgs`** (Optional): List of organization names to restrict operations to, preventing unintended operations across multiple organizations

## Authentication

The Union Terraform provider uses API key authentication. You can provide your API key in two ways:

### 1. Provider Configuration

Specify the API key directly in the provider block (use variables to avoid hardcoding):

```hcl
provider "unionai" {
  api_key = var.unionai_api_key
}
```

### 2. Environment Variable

Set the `UNIONAI_API_KEY` environment variable:

```bash
export UNIONAI_API_KEY="your-api-key"
```

### Generating an API Key

Create an API key using the Flyte CLI:

```bash
union create api-key admin --name "terraform-api-key"
```

For more information on creating API keys, see the [Flyte CLI documentation](../../api-reference/flyte-cli#flyte-create-config).

Save the generated key securely, as it will be used to authenticate all Terraform operations against your Union deployment.

## Available Resources

The Union Terraform provider supports the following resources for managing your Union deployment:

### Projects

Create and manage Union projects:

```hcl
resource "unionai_project" "example" {
  name        = "my-project"
  description = "Example project managed by Terraform"
}
```

Projects are the primary organizational unit in Union, containing workflows, tasks, and executions.

### Users

Manage user accounts:

```hcl
resource "unionai_user" "example" {
  email      = "user@example.com"
  first_name = "John"
  last_name  = "Doe"
}
```

### Roles

Define custom roles for access control:

```hcl
resource "unionai_role" "example" {
  name        = "custom-role"
  description = "Custom role with specific permissions"
}
```

### Policies

Create access policies that define permissions:

```hcl
resource "unionai_policy" "example" {
  name        = "project-access-policy"
  description = "Policy for project access"
  # Policy configuration details
}
```

### API Keys

Generate and manage API keys programmatically:

```hcl
resource "unionai_api_key" "example" {
  name        = "automation-key"
  description = "API key for CI/CD automation"
}
```

### OAuth Applications

Configure OAuth applications for external integrations:

```hcl
resource "unionai_oauth_application" "example" {
  name         = "external-app"
  redirect_uri = "https://example.com/callback"
}
```

### Access Assignments

Assign users and applications to resources with specific roles:

```hcl
resource "unionai_user_access" "example" {
  user_id    = unionai_user.example.id
  project_id = unionai_project.example.id
  role_id    = unionai_role.example.id
}

resource "unionai_application_access" "example" {
  application_id = unionai_oauth_application.example.id
  project_id     = unionai_project.example.id
  role_id        = unionai_role.example.id
}
```

## Available Data Sources

Data sources allow you to query existing Union resources for use in your Terraform configuration.

### Projects

Query existing projects:

```hcl
data "unionai_project" "existing" {
  name = "existing-project"
}
```

### Users

Look up user information:

```hcl
data "unionai_user" "existing" {
  email = "user@example.com"
}
```

### Roles

Reference existing roles:

```hcl
data "unionai_role" "admin" {
  name = "admin"
}
```

### Policies

Query existing policies:

```hcl
data "unionai_policy" "existing" {
  name = "default-policy"
}
```

### API Keys

Reference existing API keys:

```hcl
data "unionai_api_key" "existing" {
  name = "existing-key"
}
```

### Applications

Look up OAuth applications:

```hcl
data "unionai_application" "existing" {
  name = "existing-app"
}
```

### Data Plane Information

Query information about the data plane:

```hcl
data "unionai_dataplane" "current" {
  id = "dataplane-id"
}
```

### Control Plane Information

Access control plane details:

```hcl
data "unionai_controlplane" "current" {
  # Control plane data source
}
```

### Data Plane Listings

List all available data planes:

```hcl
data "unionai_dataplanes" "all" {
  # Returns list of all data planes
}
```

## Best Practices

### Use Variables for Sensitive Data

Never hardcode sensitive information like API keys in your Terraform files:

```hcl
variable "unionai_api_key" {
  description = "Union API key"
  type        = string
  sensitive   = true
}

provider "unionai" {
  api_key = var.unionai_api_key
}
```

### Organize Resources with Modules

Structure your Terraform code using modules for reusability:

```
terraform/
├── modules/
│   ├── project/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── outputs.tf
│   └── access-control/
│       ├── main.tf
│       ├── variables.tf
│       └── outputs.tf
└── main.tf
```

### Use Organization Restrictions

Prevent accidental operations across multiple organizations:

```hcl
provider "unionai" {
  api_key      = var.unionai_api_key
  allowed_orgs = ["production-org"]
}
```

### Version Control Your Configuration

Store your Terraform configuration in version control to track changes over time, but ensure sensitive files are excluded:

```gitignore
# .gitignore
*.tfvars
*.tfstate
*.tfstate.backup
.terraform/
```

### Use Remote State

For team environments, use remote state storage:

```hcl
terraform {
  backend "s3" {
    bucket = "my-terraform-state"
    key    = "union/terraform.tfstate"
    region = "us-west-2"
  }
}
```

## Example: Complete Setup

Here's a complete example that creates a project with access control:

```hcl
terraform {
  required_providers {
    unionai = {
      source  = "unionai/unionai"
      version = "~> 1.0"
    }
  }
}

provider "unionai" {
  api_key      = var.unionai_api_key
  allowed_orgs = ["my-organization"]
}

# Create a project
resource "unionai_project" "ml_pipeline" {
  name        = "ml-pipeline"
  description = "Machine learning pipeline project"
}

# Create a custom role
resource "unionai_role" "ml_engineer" {
  name        = "ml-engineer"
  description = "Role for ML engineers"
}

# Create a user
resource "unionai_user" "data_scientist" {
  email      = "data.scientist@example.com"
  first_name = "Jane"
  last_name  = "Smith"
}

# Assign user to project with role
resource "unionai_user_access" "scientist_access" {
  user_id    = unionai_user.data_scientist.id
  project_id = unionai_project.ml_pipeline.id
  role_id    = unionai_role.ml_engineer.id
}

# Create API key for automation
resource "unionai_api_key" "ci_cd" {
  name        = "ci-cd-pipeline"
  description = "API key for CI/CD automation"
}
```

## Additional Resources

- [Union Terraform Provider Documentation](https://registry.terraform.io/providers/unionai/unionai/latest/docs)
- [Terraform Documentation](https://www.terraform.io/docs)
- [Flyte CLI Documentation](../../api-reference/flyte-cli)

## Requirements

- **Terraform**: >= 1.0
- **Union API Key**: Generated via Flyte CLI
- **Go**: >= 1.24 (for development only)

## Support and Contributions

The Union Terraform provider is open source and licensed under the Mozilla Public License 2.0. For the complete provider documentation, visit the [Terraform Registry](https://registry.terraform.io/providers/unionai/unionai/latest/docs).


=== PAGE: https://www.union.ai/docs/v2/union/deployment/terraform/security ===

# Security Best Practices

**Never hardcode API keys directly in your Terraform configuration files.** API keys are sensitive credentials that should be stored securely and never committed to version control.

## Recommended Approaches

### 1. Use Cloud Secret Managers

Store your Union API key in a cloud-based secret manager and retrieve it dynamically:

#### AWS Secrets Manager

```hcl
data "aws_secretsmanager_secret" "unionai_api_key" {
  name = "unionai/terraform-api-key"
}

data "aws_secretsmanager_secret_version" "unionai_api_key" {
  secret_id = data.aws_secretsmanager_secret.unionai_api_key.id
}

provider "unionai" {
  api_key = data.aws_secretsmanager_secret_version.unionai_api_key.secret_string
}
```

#### Google Cloud Secret Manager

```hcl
data "google_secret_manager_secret_version" "unionai_api_key" {
  secret  = "unionai-terraform-api-key"
  project = "your-project-id"
}

provider "unionai" {
  api_key = data.google_secret_manager_secret_version.unionai_api_key.secret_data
}
```

#### Azure Key Vault

```hcl
data "azurerm_key_vault" "main" {
  name                = "your-keyvault-name"
  resource_group_name = "your-resource-group"
}

data "azurerm_key_vault_secret" "unionai_api_key" {
  name         = "unionai-api-key"
  key_vault_id = data.azurerm_key_vault.main.id
}

provider "unionai" {
  api_key = data.azurerm_key_vault_secret.unionai_api_key.value
}
```

### 2. Use HashiCorp Vault

For multi-cloud or on-premises deployments, HashiCorp Vault provides centralized secret management:

```hcl
data "vault_generic_secret" "unionai_api_key" {
  path = "secret/terraform/unionai"
}

provider "unionai" {
  api_key = data.vault_generic_secret.unionai_api_key.data["api_key"]
}
```

### 3. Use Environment Variables

For local development or CI/CD pipelines, use environment variables:

```bash
export UNIONAI_API_KEY="your-api-key-here"
```

The provider will automatically read from the `UNIONAI_API_KEY` environment variable:

```hcl
provider "unionai" {
  # api_key is read from UNIONAI_API_KEY environment variable
}
```

### 4. Use Terraform Variables with `.tfvars` Files

If using variable files, ensure they are excluded from version control:

```hcl
# variables.tf
variable "unionai_api_key" {
  description = "Union API key"
  type        = string
  sensitive   = true
}

# main.tf
provider "unionai" {
  api_key = var.unionai_api_key
}
```

Create a `terraform.tfvars` file (add to `.gitignore`):

```hcl
unionai_api_key = "your-api-key-here"
```

## Additional Security Measures

### Encrypt Terraform State

Always use encrypted remote state backends to protect sensitive data:

```hcl
terraform {
  backend "s3" {
    bucket         = "my-terraform-state"
    key            = "union/terraform.tfstate"
    region         = "us-west-2"
    encrypt        = true
    dynamodb_table = "terraform-state-lock"
  }
}
```

### Use State Locking

Enable state locking to prevent concurrent modifications:

- **AWS S3**: Use DynamoDB for state locking
- **Google Cloud Storage**: Automatic state locking
- **Azure Blob Storage**: Automatic state locking

### Rotate API Keys Regularly

Implement a rotation schedule for your API keys:

1. Generate a new API key using the Flyte CLI
2. Update the key in your secret manager
3. Verify Terraform can authenticate with the new key
4. Delete the old API key

### Restrict Provider Permissions

Use the `allowed_orgs` parameter to limit which organizations the provider can access:

```hcl
provider "unionai" {
  api_key      = var.unionai_api_key
  allowed_orgs = ["production-org"]
}
```

This prevents accidental operations on the wrong organization.

### Use Separate API Keys per Environment

Create different API keys for each environment (development, staging, production):

```hcl
# Development
provider "unionai" {
  alias   = "dev"
  api_key = var.dev_api_key
}

# Production
provider "unionai" {
  alias   = "prod"
  api_key = var.prod_api_key
}
```

## Security Checklist

- ✅ Store API keys in a secret manager or secure vault
- ✅ Use environment variables for local development
- ✅ Mark variables containing secrets as `sensitive = true`
- ✅ Add `*.tfvars`, `*.tfstate`, and `*.tfstate.backup` to `.gitignore`
- ✅ Use remote state backends with encryption enabled
- ✅ Enable state locking to prevent concurrent modifications
- ✅ Rotate API keys regularly
- ✅ Use separate API keys per environment
- ✅ Restrict provider access with `allowed_orgs`
- ✅ Review Terraform plans before applying changes
- ❌ Never commit API keys to version control
- ❌ Never hardcode API keys in `.tf` files
- ❌ Never share API keys in plain text (chat, email, etc.)
- ❌ Never use production API keys in development environments

## CI/CD Pipeline Security

When using Terraform in CI/CD pipelines:

### GitHub Actions

```yaml
name: Terraform

on:
  push:
    branches: [main]

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2

      - name: Terraform Init
        env:
          UNIONAI_API_KEY: ${{ secrets.UNIONAI_API_KEY }}
        run: terraform init

      - name: Terraform Apply
        env:
          UNIONAI_API_KEY: ${{ secrets.UNIONAI_API_KEY }}
        run: terraform apply -auto-approve
```

### GitLab CI

```yaml
terraform:
  image: hashicorp/terraform:latest
  variables:
    UNIONAI_API_KEY: $UNIONAI_API_KEY
  script:
    - terraform init
    - terraform apply -auto-approve
  only:
    - main
```

### Best Practices for CI/CD

- Store API keys as encrypted secrets in your CI/CD platform
- Use separate API keys for CI/CD (not personal keys)
- Implement approval gates for production deployments
- Enable audit logging for all Terraform operations
- Restrict who can view/modify CI/CD secrets

## Additional Resources

- [Terraform Security Best Practices](https://developer.hashicorp.com/terraform/tutorials/configuration-language/sensitive-variables)
- [HashiCorp Vault Documentation](https://developer.hashicorp.com/vault/docs)
- [Flyte CLI Documentation](../../api-reference/flyte-cli)


=== PAGE: https://www.union.ai/docs/v2/union/security ===

# Security

Union.ai provides a production-grade workflow orchestration platform built on Flyte, designed for AI/ML and data-intensive workloads.
Security is foundational to Union.ai’s architecture, not an afterthought.
This document provides a comprehensive overview of Union.ai’s security practices, architecture, and compliance posture for enterprise security professionals evaluating the platform.

Union.ai’s security model is built on several core principles:

* **Data residency:** Customer data is stored and computed only within the customer's data plane. The Union.ai control plane stores only orchestration metadata—no task inputs, outputs, code, logs, secrets, or container images.
* **Architectural isolation:** A strict separation between the Union-hosted control plane and the customer-hosted data plane ensures that the blast radius of any control plane compromise does not extend to customer data.
* **Outbound only connectivity:** The Cloudflare Tunnel connecting the control plane to the data plane is outbound-only from the customer’s network, requiring no inbound firewall rules. All communication uses mutual TLS (mTLS) and is authenticated using the customer's Auth / SSO.
* **Compliance:** Union.ai is SOC 2 Type II certified for Security, Availability, and Integrity, with practices aligned to ISO 27001 and GDPR standards. Union is designed to meet HIPAA compliance requirements for handling Protected Health Information (PHI) and maintains CIS 1.4 AWS certification while pursuing CIS 3.0 certification (in progress). The Union.ai trust portal can be found at [trust.union.ai](https://trust.union.ai)
* **Defense in depth:** Multiple layers of encryption, authentication, authorization, and network segmentation protect data throughout its lifecycle.
* **Human / operational isolation:** Union.ai personnel access the customer's control plane UI only through authenticated, RBAC-controlled channels. Personnel do not have IAM credentials for customer cloud accounts and cannot directly access customer data stores, secrets, or compute infrastructure. In BYOC deployments, Union.ai additionally has **BYOC deployment differences > Human access to customer environments**.

## Deployment models

Union.ai offers two deployment models, both sharing the same control plane / data plane architecture and security controls described in this document.

In **Self-Managed** deployments, the customer operates their data plane independently; Union.ai has zero access to the customer’s infrastructure, with the Cloudflare tunnel as the only connection.

In **BYOC** deployments, Union.ai manages the Kubernetes cluster in the customer’s cloud account via private connectivity (PrivateLink/PSC), handling upgrades, monitoring, and provisioning while maintaining strict separation from customer data, secrets, and logs.

The core security architecture—encryption, RBAC, tenant isolation, presigned URL data access, and audit logging—is identical across both models. Sections where operational responsibilities differ are noted inline. **BYOC deployment differences** provides a detailed comparison.

## Subpages
- **Security architecture**
- **Data protection**
- **Identity and access management**
- **Secrets management**
- **Infrastructure security**
- **Logging, monitoring, and audit**
- **Compliance and certifications**
- **Workflow execution security**
- **Multi-cloud and region support**
- **Organizational \and physical security practices**
- **Compute and control plane components**
- **Vulnerability and risk management**
- **BYOC deployment differences**
- **Data residency summary**
- **Presigned URL data types**
- **Kubernetes RBAC: Control plane**
- **Kubernetes RBAC: Data plane**
- **AWS IAM roles**


=== PAGE: https://www.union.ai/docs/v2/union/security/security-architecture ===

# Security architecture

Union.ai’s security architecture is founded on the principle of strict separation between orchestration (control plane) and execution (data plane).
This architectural decision ensures that customer data remains within the customer’s own cloud infrastructure at all times.

## Control plane / data plane separation

The control plane and data plane serve fundamentally different purposes and handle different types of data:

### Control plane (Union.ai hosted)

The control plane is responsible for workflow orchestration, user management, and providing the web interface.
It runs within Union.ai’s AWS account and stores only orchestration metadata in a managed PostgreSQL database.
This metadata includes task definitions (image references, resource requirements, typed interfaces), run and action metadata (identifiers, phase, timestamps, error information), user identity and RBAC records, cluster configuration and health records, and trigger/schedule definitions.
The control plane never stores customer data payloads.
It stores only references (URIs) to data in the customer’s object store, no data.
When data must be surfaced to a client, the control plane either proxies a signing request to generate a presigned URL or relays a data stream from the data plane without persisting it.

**See comprehensive list of control plane roles and permissions in [Kubernetes RBAC: control plane](./kubernetes-rbac-control-plane).**

### Data plane (customer hosted)

The data plane runs inside the customer’s own cloud account on their own Kubernetes cluster.
All customer data resides here, including:

| Data Type | Storage Technology | Access Pattern |
| --- | --- | --- |
| Task inputs/outputs | Object Store | Read/write by task pods via IAM roles |
| Code bundles (TGZ) | Object Store (fast-registration bucket) | Write via presigned URL; read by task pods and presigned URL by the browser |
| Container images | Container Registry | Built on-cluster; pulled by K8s |
| Task logs | Cloud Log Aggregator + live K8s API | Streamed via tunnel (never stored in CP) |
| Secrets | K8s Secrets, Vault, or Cloud Secrets Manager | Injected into pods at runtime |
| Observability metrics | Prometheus (in-cluster / customer managed) | Proxied queries via DataProxy |
| Reports (HTML) | Object Store (S3/GCS/Azure Blob) | Accessed by the browser via presigned URL |
| Cluster events | K8s API (ephemeral) | Live from K8s API |

**See comprehensive list of data plane roles and permissions in [Kubernetes RBAC: data plane](./kubernetes-rbac-data-plane).**

## Network architecture

Network security is enforced through multiple layers:

![Network security](../_static/images/security/network-security.png)

> [!NOTE]
> In BYOC deployments, Union.ai additionally maintains a private management connection to the customer's K8s cluster. See [BYOC deployment differences: Network architecture](./byoc-differences#network-architecture) for details.

### Cloudflare tunnel (outbound-only)

The data plane connects to the control plane via a Cloudflare Tunnel—an outbound-only encrypted connection initiated from the customer’s cluster.
This architecture provides several critical security benefits:

* No inbound firewall rules are required on the customer’s network
* All traffic through the tunnel uses mutual TLS (mTLS) encryption
* The Tunnel Service performs periodic health checks and state reconciliation
* Connection is initiated outward to Cloudflare’s edge network, from the data plane, which then connects to the control plane

### Control plane tunnel (outbound only)

The data plane reaches out to the control plane to establish a bidirectional, encrypted and authenticated, outbound-only tunnel.
Union.ai operates regional control plane endpoints:

| Area | Region | Endpoint |
| --- | --- | --- |
| US | us-east-2 | hosted.unionai.cloud |
| US | us-west-2 | us-west-2.unionai.cloud |
| Europe | eu-west-1 | eu-west-1.unionai.cloud |
| Europe | eu-west-2 | eu-west-2.unionai.cloud |
| Europe | eu-central-1 | eu-central-1.unionai.cloud |

In locked-down environments, networking teams can limit egress access to published Cloudflare CIDR blocks, and further restrict to specific regions in coordination with the Union networking team.

### Communication paths

| Communication Path | Protocol | Encryption |
| --- | --- | --- |
| Client → Control Plane | ConnectRPC (gRPC-Web) over HTTPS | TLS 1.2+ |
| Control Plane ↔ Data Plane | Cloudflare Tunnel (outbound-initiated) | mTLS |
| Client → Object Store (presigned URL) | HTTPS | TLS 1.2+ (cloud provider enforced) |
| Fluent Bit → Log Aggregator | Cloud provider SDK | TLS (cloud-native) |
| Task Pods → Object Store | Cloud provider SDK | TLS (cloud-native) |

> [!NOTE]
> BYOC deployments add a PrivateLink/PSC management path between Union.ai and the customer's K8s API. See [BYOC deployment differences: Network architecture](./byoc-differences#network-architecture).

## Data flow architecture

Union.ai implements two primary data access patterns, both designed to keep customer data out of the control plane:

### Presigned URL pattern

For task inputs, outputs, code bundles, and reports, the control plane proxies signing requests to the data plane, which generates time-limited presigned URLs using customer-managed credentials.
The client fetches data directly from the customer’s object store—the data never transits the control plane.
Presigned URLs generated on the data plane are single-object scope, operation-specific (GET or PUT), time-limited (default 1 hour maximum), and transport-encrypted at every hop.

Union.ai applies several controls:

* **TTL enforcement** — URLs expire after a configurable window (default 1 hour, configurable shorter)
* **Single-object scope** — each URL grants access to exactly one object, not a bucket or prefix
* **Operation specificity** — each URL is locked to a single operation (GET or PUT)
* **Transport encryption** — URLs are transmitted only over TLS-encrypted channels
* **No URL logging** — presigned URLs are not persisted in control plane logs or databases

Organizations with stricter requirements can configure shorter TTLs. The presigned URL model was chosen because it eliminates the need for the control plane to hold persistent cloud IAM credentials, which would represent a larger and more persistent attack surface than time-limited bearer URLs.

### Streaming relay pattern

For logs and observability metrics, the control plane acts as a stateless relay—streaming data from the data plane through the Cloudflare tunnel to the client in real time.
The data passes through the control plane’s memory as a TLS encrypted stream with a termination point in the cloud.
It is never written to disk, cached, or stored.

### Execution flow diagram

![Execution flow](../_static/images/security/execution-flow.png)

### Data in the UI

| Field | What is it? | Where is it stored? | How is it retrieved? |
| --- | --- | --- | --- |
| Task names | Python function and module names | Control Plane | CP API |
| Users’ names | First and last names of users on the platform | IDP | Cached in memory in CP, otherwise retrieved directly from IDP |
| Inputs/Outputs | Primitive inputs/outputs returned by tasks (e.g. return 5) | Dataplane’s S3 bucket | Cloudflare Tunnel |
| Logs | Runtime logs written by the task code/SDK | Dataplane K8s for live logs, dataplane S3/Cloudwatch/Stackdriver for persistent logs | Cloudflare Tunnel |
| K8s Events | Pod autoscaling events explaining whether a node is found or the cluster needs to scale up… etc. | Dataplane K8s | Cloudflare Tunnel |
| Report | Reports produced by the task code in HTML | Dataplane’s S3 bucket | A signed URL is generated through the tunnel, then the browser renders it in iframe |
| Code explorer | Code bundled when the task was kicked off, that contains the task code and surrounding dependencies/functions it calls| Dataplane’s S3 bucket | A signed URL is generated through the tunnel, then JS in the browser downloads and unzips the bundle to render |
| Timeline timestamps | Showing when did a task start, when it moved from queued to running to completed | Control Plane | CP API |
| Errors | Showing the failure message written into stderr or raised exceptions for a task attempt | Control Plane | CP API |


=== PAGE: https://www.union.ai/docs/v2/union/security/data-protection ===

# Data protection

## Data classification

Union.ai maintains a rigorous data classification framework.
Every data type handled by the platform is classified by residency and access pattern:

| Data Type | Classification | Residency | Transits Control Plane? |
| --- | --- | --- | --- |
| Task inputs/outputs | Customer Data | Customer object store | No — direct via presigned URL |
| Code bundles | Customer Data | Customer object store | No — direct via presigned URL |
| Container images | Customer Data | Customer registry | No — stays in customer infra |
| Reports (HTML) | Customer Data | Customer object store | No — direct via presigned URL |
| Task logs | Customer Data | Customer log aggregator | Relayed in-memory (not stored) |
| Secrets | Customer Data | Customer secrets backend | Relayed during create (not stored) |
| Observability metrics | Customer Data | Customer data plane | Relayed in-memory (not stored) |
| Task definitions | Orchestration Metadata | Control plane DB | Yes — metadata only |
| Run/action metadata | Orchestration Metadata | Control plane DB | Yes |
| User identity/RBAC | Platform Metadata | Control plane DB | Yes |
| Cluster records | Platform Metadata | Control plane DB | Yes |

## Encryption at rest

All data at rest is encrypted using cloud-provider native encryption:

| Storage | Encryption Standard | Key Management |
| --- | --- | --- |
| Object Store (S3/GCS/Azure Blob) | Cloud-provider default (SSE-S3, Google-managed, Azure SSE) | Cloud provider managed; CMK supported |
| Container Registry | Cloud-provider encryption | Cloud provider managed |
| Secrets Backend (cloud) | Cloud-provider encryption | Cloud secrets manager |
| Secrets Backend (K8s) | `etcd` encryption | K8s cluster-level encryption |
| ClickHouse | Encrypted EBS/persistent disk | Cloud provider managed |
| Control Plane PostgreSQL | AWS RDS encryption | AES-256; AWS KMS managed |

## Encryption in transit

Union.ai enforces encryption for all data in transit.
No unencrypted communication paths exist in the platform architecture.

- All client-to-control-plane communication uses TLS 1.2 or higher.
- All control-plane-to-data-plane communication uses mutual TLS via Cloudflare Tunnel.
- All client-to-object-store communication (via presigned URLs) uses HTTPS, enforced by cloud providers.
- All internal data plane communication uses cloud-native TLS.

## Data residency and sovereignty

Union.ai’s architecture provides strong data residency guarantees:

### Data plane

* All customer data resides in the customer’s own cloud account and region
* Customers choose the region for their data plane deployment

### Control plane

* Union.ai hosts your control plane in these supported regions: US West, US East, EU West-1 (Ireland), EU West-2 (London), EU Central, with more being added
* No customer data is replicated to or cached in Union.ai infrastructure. See **Data protection > Data classification** for more detail on data classification and handling.

For organizations operating under GDPR or other data residency regulations, Union.ai’s EU-region data planes ensure all customer data remains within the European Union.


=== PAGE: https://www.union.ai/docs/v2/union/security/identity-and-access-management ===

# Identity and access management

## Authentication

Union.ai supports three authentication methods to accommodate different usage patterns:

| Method | Identity Type | Credentials | Use Case |
| --- | --- | --- | --- |
| OIDC (Okta) | Human user | Browser SSO | UI access, initial CLI login |
| API Keys | Human user (delegated) | Static bearer token | CI/CD scripts, simple automation |
| Service Accounts | Application identity | OAuth2 client_id + client_secret → short-lived token | Production pipelines, multi-service systems |

API keys are issued per user and inherit the user’s RBAC permissions.
They can be created and revoked via the UI or CLI.
Service accounts are provisioned through the Identity Service, creating OAuth2 applications with distinct, auditable identities independent of any human user.

## Authorization (RBAC)

Union.ai implements a policy-based Role-Based Access Control (RBAC) system with three built-in role types.

| Role | Capabilities | Typical Assignment |
| --- | --- | --- |
| Admin | Full access: manage users, clusters, secrets, projects, and all runs | Platform administrators, security team leads |
| Contributor | Create/abort runs, register tasks, manage secrets within assigned projects | ML engineers, data scientists, DevOps |
| Viewer | Read-only access to runs, actions, logs, reports | Stakeholders, auditors, read-only consumers |
| Custom Policies | Custom policies bind roles (built-in or custom) to resources scoped at org-wide, domain, or project+domain level using composable YAML bindings via `uctl` | Giving contributor access to a specific project's development and staging domains, but only viewer access in production |

RBAC policies are enforced at the service layer.
Every API request is authenticated and authorized against the user’s role assignments before any data access occurs.
Users have the ability to create custom policies to further refine access control.

## Organization isolation

Union.ai enforces tenant isolation at multiple architectural layers to ensure that no customer can access another customer's data or metadata, even within the shared control plane.

### Database-layer isolation

Every record in the control plane PostgreSQL database is scoped by organization (org). The org identifier is part of the primary key or unique index on all tenant-scoped tables, including actions, tasks, runs, executions, and RBAC bindings. All database queries are gated by the org context extracted from the caller's authenticated token at the service layer, before any SQL is executed. This ensures that a query can only return records belonging to the caller's organization. Cross-organization access is explicitly denied: there is no API or internal path that permits querying across org boundaries. While Union.ai does not currently use PostgreSQL row-level security (RLS) policies, the application-layer enforcement is uniform and independently verifiable through the SOC 2 Type II audit.

### Data plane isolation

Each customer's data plane runs in a dedicated Kubernetes cluster within the customer's own cloud account. There is no shared compute infrastructure between customers. Customer workloads, data, secrets, container images, and logs are physically isolated in separate cloud accounts with separate IAM boundaries. No other customer's workloads can execute on or access another customer's cluster.

### Control plane service isolation

Within the control plane, all service-to-service calls carry the authenticated org context. The identity service extracts org membership from the OIDC token, and this context is propagated through every downstream service call via request headers. Kubernetes namespaces on the data plane are provisioned per-project within each org, providing namespace-level resource isolation (resource quotas, RBAC bindings, network policies) even within a single customer's cluster.

### Isolation verification

Tenant isolation controls are covered by Union.ai's SOC 2 Type II audit scope. The combination of org-scoped primary keys, service-layer query gating, and physically separate data planes provides defense-in-depth against cross-tenant data access.

## Human access to customer environments

Union.ai maintains controls governing how its personnel interact with customer environments.

### Current access model

Union.ai support and engineering personnel may access a customer's Union.ai tenant (the control plane UI and API for that organization) for the purposes of onboarding, troubleshooting, and operational support. This access is authenticated through the same OIDC/SSO mechanisms as customer users and is subject to RBAC policies. Personnel access the customer's tenant, not the customer's data plane infrastructure directly. Union.ai personnel do not have IAM credentials for the customer's cloud account and cannot directly access the customer's object stores, secrets backends, or container registries.

> [!NOTE]
> In BYOC deployments, Union.ai personnel additionally have K8s cluster management access. See [BYOC deployment differences: Human access](./byoc-differences#human-access-to-customer-environments) for details.

### Access scope and limitations

When Union.ai personnel access a customer's tenant, they can view orchestration metadata (workflow definitions, run status, scheduling configuration), view logs relayed through the tunnel (but cannot access the customer's log aggregator directly), and perform administrative operations (cluster configuration, namespace provisioning) as authorized by the customer's RBAC policy. Personnel cannot read secret values (the API is write-only for values), cannot access raw data in the customer's object stores (presigned URLs are generated per-request and are not retained), and cannot access the customer's cloud account or IAM roles. In BYOC deployments, administrative operations [extend to direct K8s cluster management](./byoc-differences#human-access-to-customer-environments).

### Audit trail

All access by Union.ai personnel to customer tenants is authenticated and logged. API requests include the identity of the caller, the operation performed, and a timestamp.

> [!NOTE]
> In BYOC deployments, Union.ai personnel have additional K8s cluster access for operational management. See [BYOC deployment differences: Human access](./byoc-differences#human-access-to-customer-environments) for full details.

## Least privilege principle

Union.ai enforces the principle of least privilege across all system components:

* IAM roles on the data plane are scoped to minimum required permissions
* Two IAM roles per data plane: admin role (for platform services) and user role (for task pods)
* IAM roles are bound to Kubernetes service accounts via cloud-native workload identity federation
* Presigned URLs grant single-object, operation-specific, time-limited access
* Service accounts receive only the permissions needed for their specific function


=== PAGE: https://www.union.ai/docs/v2/union/security/secrets-management ===

# Secrets management

Union.ai provides enterprise-grade secrets management with a security-first design that ensures secret values never leave the customer’s infrastructure during normal operations.

## Secrets architecture

The data plane supports four configurable secrets backends:

| Backend | Storage Location | Default? |
| --- | --- | --- |
| Kubernetes Secrets | K8s `etcd` on the customer cluster | Yes (default for self-managed) |
| AWS Secrets Manager | AWS-managed service | Optional |
| GCP Secret Manager | GCP-managed service | Optional |
| Azure Key Vault | Azure-managed service | Optional |

In all cases, secrets are stored within the customer’s infrastructure.
The choice of backend is a deployment configuration on the data plane operator.

> [!NOTE]
> In BYOC deployments, the default secrets backend differs. See [BYOC deployment differences: Secrets management](./byoc-differences#secrets-management).

## Secret lifecycle

### Creation

When a user creates a secret via the UI or CLI, the request is relayed through the Cloudflare tunnel to the data plane’s secrets backend.
The secret value transits the control plane in-memory during this relay but is never written to disk or database on the control plane.

### Consumption

When a task pod is created, the Executor configures it to mount the requested secrets from the secrets backend (as environment variables or files).
The secret value is read by the data plane’s secrets backend and injected into the pod—it never leaves the customer’s infrastructure during this process.

### Write-only API

> [!NOTE]
> Security by Design: There is no API to read back secret values. The GetSecret RPC returns only the secret’s metadata (name, scope, creation time, cluster presence status)—never the value itself. Secret values can only be consumed by task pods at runtime. This eliminates an entire class of secret exfiltration attacks.

## Secret scoping

Secrets can be scoped at multiple levels (organization, project, domain) to provide granular access control.
Only task pods running within the appropriate scope can access the corresponding secrets.


=== PAGE: https://www.union.ai/docs/v2/union/security/infrastructure-security ===

# Infrastructure security

## Kubernetes security

The data plane runs on customer-managed Kubernetes clusters. Union supports the following security measures:

> [!NOTE]
> In BYOC deployments, Union.ai manages the K8s cluster. See [BYOC deployment differences: Infrastructure management](./byoc-differences#infrastructure-management).

* Workload identity federation for pod-level IAM role binding (no static credentials)
* Kubernetes RBAC for service account permissions within the cluster
* Network policies for pod-to-pod communication isolation
* Resource quotas and limit ranges to prevent resource abuse
* Pod security contexts enforcing non-root execution where applicable

A complete list of data plane permissions appears in **[Kubernetes RBAC: data plane](./kubernetes-rbac-data-plane)**

## Container security

Union.ai’s container security model ensures that code execution is isolated and controlled:

* Image Builder runs on the customer’s cluster using Buildkit, ensuring source code and built images never leave customer infrastructure
* Base images are pulled from customer-approved registries (public or private)
* Built images are pushed to the customer’s container registry (ECR/GCR/ACR)
* Task pods mount code bundles via presigned URLs with limited TTL
* Container images follow customer-defined tagging and scanning policies

## IAM and workload identity

Two IAM roles are provisioned per data plane, each with narrowly scoped permissions. In BYOC deployments, [Union.ai provisions these roles](./byoc-differences#iam-role-provisioning); in self-managed, the customer provisions them.

| Role | Permissions | Assumed By | Mechanism |
| --- | --- | --- | --- |
| Admin Role (`adminflyterole`) | R/W to object store buckets, secrets manager access, persisted logs read | Platform services: Executor, Object Store Service, DataProxy | Workload identity federation |
| User Role (`userflyterole`) | R/W to object store buckets | Task pods (user workloads) | Workload identity via K8s service account annotation |

These roles use cloud-native workload identity federation (IAM Roles for Service Accounts on AWS, Workload Identity on GCP, Azure Workload Identity on Azure), eliminating the need for static credential storage.

## Control plane infrastructure

The Union.ai control plane is hosted on AWS with enterprise-grade infrastructure security:

* Managed PostgreSQL (AWS RDS) with AES-256 encryption at rest
* Network isolation via VPC with restricted security groups
* TLS termination at the edge for all incoming connections
* Automated backups and disaster recovery procedures
* Infrastructure-as-code deployment with version-controlled configurations
* Automated patch management and security updates

## Availability, response time, and resilience

Union.ai's architecture separates the availability characteristics of the control plane and data plane, providing resilience even during partial outages.

### Control plane availability

The Union.ai control plane runs on AWS with multi-AZ redundancy, managed PostgreSQL (RDS) with automated failover, and continuous monitoring. Union.ai's SOC 2 Type II audit covers availability as a trust service criterion. The control plane is designed for high availability, with automated recovery and health monitoring. Specific SLA targets are defined in customer contracts and are available upon request.

### Data plane resilience during control plane outages

Because the data plane runs entirely within the customer's Kubernetes cluster, in-flight workflows continue executing even if the control plane becomes temporarily unavailable. The Executor, which manages pod lifecycle, operates as a Kubernetes controller on the customer's cluster and does not require real-time connectivity to the control plane to continue running pods that have already been scheduled. State transitions will be reconciled when connectivity is restored. However, new workflow submissions and scheduling operations require control plane availability.

The customer is solely responsible for data plane availability, including Kubernetes cluster operations, node pool management, upgrades, and monitoring. Union.ai's availability commitment covers only the control plane. In-flight workflows continue executing independently during control plane outages.

> [!NOTE]
> In BYOC deployments, availability responsibilities shift — Union.ai manages data plane cluster availability. See [BYOC deployment differences: Availability and resilience](./byoc-differences#availability-and-resilience).


=== PAGE: https://www.union.ai/docs/v2/union/security/logging-monitoring-and-audit ===

# Logging, monitoring, and audit

## Task logging

Logs are collected by `fluentbit` (deployed as a `DaemonSet` on the data plane) and shipped to the customer’s cloud-native log service:

| Cloud Provider | Log Service | Integration |
| --- | --- | --- |
| AWS | CloudWatch Logs | Fluent Bit → CloudWatch |
| GCP | Cloud Logging (Stackdriver) | Fluent Bit → Cloud Logging |
| Azure | Azure Monitor / Log Analytics | Fluent Bit → Azure Monitor |

The data plane log provider serves logs from two sources: live logs streamed directly from the Kubernetes API while a task is running, and persisted logs read from the cloud log aggregator after a pod terminates.
Log data is never stored in the control plane—it is streamed from the customer’s data plane through the Cloudflare tunnel and relayed to the client as a stateless pass-through.

## Observability metrics

A per-cluster instance (Prometheus and/or ClickHouse) stores time-series observability metrics including resource utilization and cost data.
Queries are proxied through the DataProxy service to the customer’s instance.
Metrics data never leaves the customer’s infrastructure. In BYOC deployments, Union.ai [deploys and manages the monitoring stack](./byoc-differences#infrastructure-management).

## Audit trail

Union.ai maintains comprehensive audit capabilities:

* Every API request is authenticated, and the identity context is captured
* Run and action lifecycle events are recorded with timestamps, phases, and responsible identities
* RBAC changes and user management operations are logged
* Secret creation and management operations are tracked (values are never logged)
* Cluster state changes and tunnel health events are recorded
* Error information is preserved per attempt, enabling forensic analysis of failures

## Incident response

Union.ai maintains documented incident response procedures aligned with SOC 2 Type II requirements.
These include defined escalation paths, communication protocols, containment procedures, and post-incident review processes.
The control plane’s stateless handling of customer data limits the potential impact of any control plane incident.


=== PAGE: https://www.union.ai/docs/v2/union/security/compliance-and-certifications ===

# Compliance and certifications

## Certifications overview

Union.ai maintains a rigorous certification program validated by independent third-party auditors.
Full details at the [Union.ai Trust Center](https://trust.union.ai/).

| Standard | Certification | Status |
| --- | --- | --- |
| SOC 2 Type II | Security, Availability, Integrity | Certified |
| SOC 2 Type I | Security, Availability, Integrity |  Certified |
| HIPAA | Health data privacy and security |  Compliant* |
| CIS 1.4 AWS | Restricted access benchmark |  Certified |
| CIS 3.0 | Security benchmark | In progress |

- * Union is designed to meet HIPAA compliance requirements for handling Protected Health Information (PHI).
- The SOC 2 Type II audit was conducted over a 12-week period and is available upon request.
Key areas covered include protection against unauthorized access (Security), system availability commitments and disaster recovery (Availability), and complete, valid, accurate, and timely processing (Processing Integrity).
- Union.ai uses Vanta for continuous compliance monitoring and automated control assessments.

## Standards compliance

In addition to certifications, Union.ai complies with the following standard control frameworks through its private data plane architecture:

| Framework | Control | Description |
| --- | --- | --- |
| ISO 27001 A.5.15 | Access control | Restricts access to network services and management interfaces; management endpoints not exposed to public Internet |
| ISO 27001 A.8.20 | Network security | Segregation and protection of networks; management interfaces on dedicated, private channels |
| ISO 27001 A.8.28 | Secure configuration | Minimizes public exposure of management plane by default |
| ISO 27001 A.8.21 | Cryptography | TLS encryption with minimized exposure of sensitive channels |
| ISO 27001 A.5.23 | Cloud service security | Cloud services configured securely with mitigated public exposure risks |
| CIS v8 4.4 | Administrative access | Administrative interfaces not exposed to Internet; VPN/bastion required |
| CIS v8 12.11 | Segment admin interfaces | Separation of administrative interfaces from public access |
| CIS v8 13.2 | Boundary protections | Management plane endpoints behind strong network segmentation |

## HIPAA compliance

Union.ai is designed to support HIPAA compliance requirements, enabling healthcare and life sciences organizations to process protected health information (PHI) within their data planes.
Because all customer data—including any PHI—remains exclusively in the customer’s own cloud infrastructure, Union.ai’s architecture inherently supports HIPAA’s data protection requirements.
The control plane stores only orchestration metadata and never persists PHI.

## GDPR alignment

Union.ai’s architecture inherently supports GDPR through its data residency model.
For EU-region data planes, all customer data remains within the European Union.
The control plane stores only orchestration metadata, and where error messages may contain user-generated content, this is documented and scoped.

## Trust Center

Union.ai maintains a public Trust Center at trust.union.ai (powered by Vanta), providing real-time transparency into the company’s security controls, compliance status, and security practices.
The Trust Center provides up-to-date information on certifications, downloadable resources (SOC 2 reports upon request), and over 70 verified security controls organized across five categories:

| Control Category | Controls | Key Controls Include |
| --- | --- | --- |
| Infrastructure Security | 17 controls | Encryption key access restricted, unique account authentication enforced, production application/database/OS/network access restricted, intrusion detection, log management, network segmentation, firewalls reviewed and utilized, network hardening standards |
| Organizational Security | 13 controls | Asset disposal procedures, production inventory, portable media encryption, anti-malware, code of conduct, confidentiality agreements, password policy, MDM, security awareness training |
| Product Security | 5 controls | Data encryption at rest, control self-assessments, penetration testing, data transmission encryption, vulnerability/system monitoring |
| Internal Security Procedures | 35 controls | BC/DR plans established and tested, cybersecurity insurance, change management, SDLC, incident response tested, risk assessments, vendor management, board oversight, whistleblower policy |
| Data and Privacy | 3 controls | Data retention procedures, customer data deleted upon leaving, data classification policy |

## Shared responsibility model

Union.ai operates under a shared responsibility model:

| Responsibility Area | Union.ai | Customer |
| --- | --- | --- |
| Control plane security | Full ownership | N/A |
| Data plane infrastructure | Guidance and tooling | Provisioning and maintenance |
| Data encryption at rest | Default cloud encryption | Optional CMK configuration |
| Network security (tunnel) | Tunnel management | Firewall and VPC configuration |
| IAM roles and policies | Role templates and documentation | Role creation and binding |
| Secrets management | API and relay infrastructure | Backend selection and secret values |
| Application-level access control | RBAC framework | Role assignment and policy |
| Compliance documentation | SOC 2 report, Trust Center | Customer-specific attestations |

> [!NOTE]
> In BYOC deployments, shared responsibilities shift for data plane infrastructure and IAM roles. See [BYOC deployment differences: Shared responsibility model](./byoc-differences#shared-responsibility-model).


=== PAGE: https://www.union.ai/docs/v2/union/security/workflow-execution-security ===

# Workflow execution security

This section traces the security controls applied at each stage of a workflow’s lifecycle, from registration through execution and result retrieval.

## Task registration

* SDK serializes the task specification (container image reference, resource requirements, typed interface) into a protobuf message
* Code bundle is uploaded directly to the customer’s object store via presigned PUT URL—the code never touches the control plane
* Only the specification metadata (including the object store URI) is stored in the control plane database

## Run creation and execution

* Input data is serialized and uploaded to the customer’s object store; only the input URI is stored in the control plane
* The control plane enqueues the action to the data plane via the Cloudflare tunnel
* The Executor (a Kubernetes controller on the data plane) creates a pod that reads inputs from the customer’s object store and writes outputs back to it
* Secrets are injected into pods from the customer’s secrets backend—they never traverse the control plane during runtime

## Result retrieval

* Outputs, reports, and code bundles are accessed via presigned URLs—the data flows directly from the customer’s object store to the client
* Logs are streamed from the data plane through the Cloudflare tunnel as a stateless relay
* Metadata (run status, phase, errors) is served from the control plane database

## Data flow summary

> [!NOTE]
> At every stage of the workflow lifecycle, customer data (code, inputs, outputs, images, secrets) stays within the customer’s infrastructure or travels directly between the client and the customer’s object store. Logs are relayed through the tunnel but never stored. The control plane handles only orchestration metadata.


=== PAGE: https://www.union.ai/docs/v2/union/security/multi-cloud-and-region-support ===

# Multi-cloud and region support

Union.ai supports data plane deployments across multiple cloud providers and regions, ensuring that organizations can meet their specific infrastructure and regulatory requirements.

## Supported cloud providers

| Cloud Provider | Object Store | Secrets Backend | Log Aggregator | Container Registry |
| --- | --- | --- | --- | --- |
| AWS | S3 | K8s Secrets / AWS Secrets Manager | CloudWatch Logs | ECR |
| GCP | GCS | K8s Secrets / GCP Secret Manager | Cloud Logging | GCR / Artifact Registry |
| Azure | Azure Blob Storage | K8s Secrets / Azure Key Vault | Azure Monitor | ACR |

Union Implementation Services supports additional cloud providers and on-premises deployments through a case-by-case engagement.

## Supported regions

Union.ai currently operates control planes in the following regions, with additional regions being added: **US West, US East, EU West, and EU Central**.
Customers choose the region for their data plane deployment, ensuring that all customer data remains within the selected geographic region.

## Consistent security across clouds

Regardless of the cloud provider selected, Union.ai enforces consistent security guarantees through its architecture: the same control plane/data plane separation, the same presigned URL model, the same tunnel-based connectivity, the same RBAC framework, and the same encryption standards.
Cloud-specific implementations (IAM roles, encryption services, log aggregators) are abstracted by the platform while maintaining native integration with each provider’s security services.


=== PAGE: https://www.union.ai/docs/v2/union/security/organizational-security-practices ===

# Organizational \and physical security practices

Union.ai maintains organizational security controls to protect people, facilities, and endpoint devices.
These controls are independently verified through SOC 2 Type II audits and continuously monitored via the Vanta Trust Center (trust.union.ai).

## Employee security lifecycle

**Verified controls** (source: Trust Center, SOC 2 Type II audit)

| Control | Description | Verification |
| --- | --- | --- |
| Background checks | All employees with access to production systems undergo background checks prior to onboarding | SOC 2 Type II |
| Security awareness training | Required within 30 days of hire and annually thereafter for all employees | Trust Center (passing) |
| Confidentiality agreements | Signed by all employees and contractors during onboarding | Trust Center (passing) |
| Code of conduct | Acknowledged by all employees and contractors; violations subject to disciplinary action | Trust Center (passing) |
| Access provisioning | Documented procedures for granting, modifying, and revoking user access | Trust Center (passing) |
| Termination checklists | Access revoked for terminated employees via formal checklist process | Trust Center (passing) |
| Performance evaluations | Managers complete evaluations for direct reports at least annually | Trust Center (passing) |
| Least-privilege access | Internal systems follow least-privilege; regular access reviews conducted | SOC 2 Type II |

## Governance & organizational controls

| Control | Description | Verification |
| --- | --- | --- |
| Defined security roles | Formal roles and responsibilities for design, implementation, and monitoring of security controls | Trust Center (passing) |
| Organizational structure | Documented org chart with reporting relationships | Trust Center (passing) |
| Board-level oversight | Board or relevant subcommittee briefed by senior management on security and risk at least annually | Trust Center (passing) |
| Information security policies | Policies and procedures documented and reviewed at least annually | Trust Center (passing) |
| Whistleblower policy | Formalized policy with anonymous communication channel for reporting violations | Trust Center (passing) |
| Vendor management | Third-party vendors and sub-processors evaluated and monitored; sub-processor list available via Trust Center | SOC 2 Type II |
| Business continuity | BC/DR plans aligned with SOC 2 | SOC 2 Type II |

## Security development lifecycle

* **Secure coding:** Guidelines enforced through mandatory code review processes
* **Automated security testing:** Integrated into CI/CD pipelines
* **Dependency scanning:** Vulnerability scanning and management for all software dependencies
* **Infrastructure-as-code:** Version-controlled security configurations
* **Penetration testing:** Regular third-party security assessments
* **Incident response:** Documented procedures aligned with SOC 2 Type II, including defined escalation paths and post-incident review

> [!NOTE]
> All controls marked as “passing” are continuously monitored via Vanta and verified through the Union.ai Trust Center at trust.union.ai. The SOC 2 Type II audit report is available upon request.


=== PAGE: https://www.union.ai/docs/v2/union/security/components-architecture ===

# Compute and control plane components

This section provides a detailed reference for each security-relevant component running on the data plane and/or control plane.
Understanding these components is essential for enterprise security teams conducting architecture reviews.

## Component architecture

The diagram below shows the major components in both planes and how they communicate.
All cross-plane traffic flows through the Cloudflare Tunnel—an outbound-only, mTLS-encrypted connection initiated from the data plane.
No inbound ports are opened on the customer’s cluster.

```mermaid
graph TB
    subgraph CP["Control plane (Union.ai hosted — AWS)"]
        Admin["Admin<br/>(UI &amp; API gateway)"]
        QueueSvc["Queue Service<br/>(schedules TaskActions)"]
        StateSvc["State Service<br/>(receives state transitions)"]
        ClusterSvc["Cluster Service<br/>(cluster health &amp; DNS reconciliation)"]
        DataProxy["DataProxy<br/>(streaming relay for logs &amp; metrics)"]
    end

    subgraph Tunnel["Cloudflare Tunnel (outbound-only, mTLS)"]
        direction LR
        TunnelEdge(["Cloudflare edge"])
    end

    subgraph DP["Data plane (customer hosted — customer cloud account)"]
        TunnelSvc["Tunnel Service<br/>(maintains outbound tunnel connection)"]
        Executor["Executor<br/>(Kubernetes controller — runs task pods)"]
        ObjStore["Object Store Service<br/>(presigned URL generation)"]
        LogProvider["Log Provider<br/>(live K8s logs + cloud log aggregator)"]
        ImageBuilder["Image Builder<br/>(Buildkit — on-cluster image builds)"]

        subgraph Apps["Apps &amp; Serving"]
            Kourier["Kourier gateway<br/>(Envoy — auth + routing)"]
            Knative["Knative Services<br/>(app containers)"]
        end

        Executor -->|"submit and watch"| Pods["Task pods<br/>(customer workloads)"]
        Pods -->|"read/write via IAM"| ObjBucket[("Object store<br/>(metadata + fast-reg buckets)")]
        ObjStore -->|"signs URLs using admin IAM role"| ObjBucket
        LogProvider -->|"live: K8s API<br/>completed: CloudWatch / Cloud Logging / Azure Monitor"| Pods
        Kourier --> Knative
    end

    Admin -->|"ConnectRPC / HTTPS"| User(["Client<br/>(browser / CLI / SDK)"])
    User -->|"presigned URL — direct fetch"| ObjBucket

    CP <-->|"Cloudflare Tunnel"| TunnelEdge
    TunnelEdge <-->|"outbound-initiated from data plane"| TunnelSvc
    TunnelSvc --- Executor
    TunnelSvc --- ObjStore
    TunnelSvc --- LogProvider
    TunnelSvc --- Apps

    QueueSvc -->|"TaskAction"| Executor
    Executor -->|"state transitions (ConnectRPC)"| StateSvc
    LogProvider -->|"streamed relay — never persisted"| DataProxy
    ClusterSvc -->|"health checks &amp; DNS"| TunnelSvc
```

**Key relationships:**

| From | To | What flows |
| --- | --- | --- |
| Queue Service | Executor | TaskAction custom resources (orchestration instructions) |
| Executor | State Service | Phase transitions (Queued → Running → Succeeded/Failed) |
| Executor | Task pods | Pod lifecycle management |
| Task pods | Object store | Task inputs/outputs via IAM role (workload identity) |
| Object Store Service | Object store | Presigned URL generation using admin IAM role |
| Log Provider | DataProxy | Log streams relayed in memory — optionally persisted on customer storage |
| Cluster Service | Tunnel Service | Health checks and DNS record reconciliation |
| Tunnel Service | Cloudflare edge | Single outbound-only mTLS connection covering all data-plane services |

## Executor

The Executor is a Kubernetes controller that runs on the customer’s data plane.
It is the core component responsible for translating orchestration instructions into actual workload execution.
The Executor watches for `TaskAction` custom resources created by the Queue Service, reconciles each `TaskAction` through its lifecycle (`Queued`, `Initializing`, `Running`, `Succeeded`/`Failed`), reports state transitions back to the control plane’s State Service via `ConnectRPC` through the Cloudflare tunnel, and creates and manages Kubernetes pods for task execution.

The Executor runs entirely within the customer’s cluster.
It accesses the customer’s object store and secrets using IAM roles bound to its Kubernetes service account via workload identity federation.
At no point does the Executor communicate directly with external services outside the customer’s cloud account (except through the Cloudflare tunnel to the control plane).

## Apps and serving

- Apps and Serving enables customers to deploy long-running web applications — Streamlit dashboards, FastAPI services, notebooks, and inference endpoints — directly on the customer's data plane.
- Apps run as Knative Services within tenant-scoped Kubernetes namespaces, with the Union Operator managing the full lifecycle including autoscaling and scale-to-zero.
- No application code, data, or serving traffic passes through the Union control plane.
- Inbound traffic routes through Cloudflare for DDoS protection to a Kourier gateway (Union's Envoy fork) running on the customer's cluster, which enforces authentication against the control plane before forwarding to the app container.
- Browser access uses SSO; programmatic access requires a Union API key.
- All endpoints require authentication by default, with optional per-app anonymous access.
- Union's RBAC controls which users can deploy and access apps per project, and resource quotas constrain consumption.
- The load balancer, serving infrastructure, and app containers all run within the customer's cluster, maintaining the same data residency guarantees as workflow execution.
- In BYOC deployments, Union.ai manages the [serving infrastructure lifecycle](./byoc-differences#infrastructure-management).

## Object store service

The Object Store Service runs on the data plane and provides the signing capabilities that enable the presigned URL security model.
Its key operations include:
- `CreateSignedURL` (generates presigned URLs using the customer’s IAM credentials via the admin role).
- `CreateUploadLocation` (generates presigned `PUT` URLs for fast registration with `Content-MD5` integrity verification)
- `Presign` (generic presigning for arbitrary object store keys)
- `Get`/`Put` (direct object store read/write used internally by platform services).

Two object store buckets are provisioned per data plane cluster: a metadata bucket for task inputs, outputs, reports, and intermediate data, and a "fast-registration" bucket for code bundles uploaded during task registration.
Object layout follows a hierarchical pattern: org/project/domain/run-name/action-name, providing natural namespace isolation.

## Log provider

The Log Provider runs on the data plane and serves task logs from two sources.
For live tasks, logs are streamed directly from the Kubernetes API (pod stdout/stderr) in real time.
For completed tasks, logs are read from the cloud log aggregator (CloudWatch, Cloud Logging, or Azure Monitor) after pod termination.
Union also supports persisting logs in object storage.
Log lines include structured metadata: timestamp, message content, and originator classification (user vs. system).
This structured approach enables security teams to distinguish between application-generated logs and platform-generated logs for audit purposes.

## Image builder

When enabled, the Image Builder runs on the data plane and uses Buildkit to construct container images without exposing source code or built artifacts outside the customer’s infrastructure.
The build process pulls the base image from a customer-approved registry (public or private), accesses user code via a presigned URL with a limited time-to-live, builds the container image with specified layers (pip packages, apt packages, custom commands, UV/Poetry projects), and pushes the built image to the customer’s container registry (ECR, GCR, ACR, or others).
Source code and built images never leave the customer’s infrastructure during the build process.

## Tunnel service

The Tunnel Service maintains the Cloudflare Tunnel connection between the data plane and control plane.
It is responsible for initiating and maintaining the outbound-only encrypted connection, performing periodic health checks and heartbeats, and reconnecting automatically in case of network disruption.
The Cluster Service on the control plane performs periodic reconciliation to ensure tunnel health and DNS records are current.


=== PAGE: https://www.union.ai/docs/v2/union/security/vulnerability-and-risk-management ===

# Vulnerability and risk management

## Vulnerability assessment

Union.ai maintains a comprehensive vulnerability management program that includes dependency analysis and automated alerts for known CVEs in software dependencies, container image scanning for both platform and customer-facing components, and periodic third-party penetration testing to identify potential attack vectors.

## Patch management

Union.ai follows a risk-based approach to patch management.
Critical vulnerabilities (CVSS 9.0+) are prioritized for immediate remediation, while high-severity vulnerabilities are addressed within defined SLA windows.
The control plane is updated independently of customer data planes, ensuring that security patches can be applied rapidly without requiring customer-side changes. The customer is responsible for data plane patching (K8s version, platform components, monitoring stack).

> [!NOTE]
> In BYOC deployments, Union.ai manages data plane patching. See [BYOC deployment differences: Data plane patching](./byoc-differences#data-plane-patching).

## Threat modeling

Union.ai’s architecture has been designed with the following threat model considerations:

### Control plane compromise

In the event of a control plane compromise, an attacker would gain access to orchestration metadata only.
They would not obtain customer data payloads, secret values, code bundles, container images, or log content.
The attacker could not initiate connections to customer data planes (outbound-only tunnel).
Presigned URLs are generated on the data plane, so the attacker could not generate data access URLs.

### Tunnel interception

The Cloudflare Tunnel uses mTLS, making man-in-the-middle attacks infeasible.
Even if an attacker could intercept tunnel traffic, customer data flowing through the tunnel (logs, secret creation requests) is encrypted in transit and is not cached or stored at any intermediate point.

### Presigned URL leakage

If a presigned URL were leaked, the exposure is limited to a single object for a maximum of one hour (default configuration).
URLs grant only the specific operation requested (GET or PUT) and cannot be used to enumerate or access other objects.
Organizations can configure shorter expiration times to further reduce this risk window.
Because presigned URLs are bearer tokens—possession alone grants access with no additional auth—Union.ai recommends that customers treat presigned URLs with the same care as short-lived credentials and configure the shortest practical TTL for their use case.

## Security architecture benefits

Union.ai’s architectural decisions provide inherent security benefits that reduce overall risk exposure:

| Architectural Decision | Security Benefit | Risk Mitigated |
| --- | --- | --- |
| Control plane stores no customer data | Minimizes blast radius of CP compromise | Data breach from CP attack |
| Outbound-only tunnel | No inbound attack surface on customer network | Network intrusion via open ports |
| Presigned URLs for data access | No persistent data access credentials | Credential theft / lateral movement |
| Write-only secrets API | Cannot exfiltrate secrets via API | Secret leakage via API abuse |
| Workload identity federation | No static credentials on data plane | Static credential compromise |
| Per-org database scoping | Enforces tenant isolation at data layer | Cross-tenant data access |
| Cloud-native encryption | Leverages provider-managed encryption | Data at rest exposure |

## Third-party dependency risk

Union.ai's architecture depends on a set of core third-party services. This section provides a risk-tier classification of these dependencies and the mitigations in place for each.

| Dependency | Tier | Role | Mitigation |
| --- | --- | --- | --- |
| Cloudflare | Critical | Tunnel connectivity between control plane and data plane | mTLS encryption, outbound-only architecture, health monitoring, automatic reconnection |
| AWS (control plane) | Critical | Hosts control plane infrastructure (RDS, EKS, S3) | Multi-AZ redundancy, automated failover, encryption at rest and in transit |
| Customer cloud provider | Critical | Hosts data plane infrastructure | Customer-managed; Union.ai provides guidance and tooling |
| Vanta | Operational | Continuous compliance monitoring | Independent SOC 2 audit validates controls |
| Okta | Operational | Identity provider for OIDC authentication | Standard OAuth2/OIDC; API keys and service accounts provide fallback |

Union.ai's vendor management program, covered under the SOC 2 Type II audit, includes periodic evaluation of third-party providers. A formal dependency risk assessment document is available upon request for customers conducting in-depth supply chain reviews.

The customer owns all data plane dependencies. Union.ai's dependency risk scope is limited to the control plane and Cloudflare tunnel.

> [!NOTE]
> In BYOC deployments, Union.ai assumes responsibility for cluster-level dependencies. See [BYOC deployment differences: Third-party dependency risk](./byoc-differences#third-party-dependency-risk).


=== PAGE: https://www.union.ai/docs/v2/union/security/byoc-differences ===

# BYOC deployment differences

Union.ai's BYOC (Bring Your Own Cloud) deployment shares the same control plane / data plane architecture, encryption, RBAC, tenant isolation, and audit logging as the self-managed deployment. The key difference is that **Union.ai manages the Kubernetes cluster** in the customer's cloud account, rather than the customer managing it independently.

This page consolidates all security-relevant differences between BYOC and self-managed deployments.

## Overview

| Aspect | Self-Managed | BYOC |
| --- | --- | --- |
| Data plane operator | Customer | Union.ai |
| K8s cluster management | Customer | Union.ai (via PrivateLink/PSC) |
| K8s API exposure | Customer-controlled | Private only (never public Internet) |
| Union.ai infrastructure access | None (Cloudflare tunnel only) | K8s cluster management only |
| Data/secrets/logs access by Union.ai | None | None |
| Upgrade responsibility | Customer | Union.ai |
| Monitoring responsibility | Customer | Union.ai + customer |

## Network architecture

In addition to the Cloudflare Tunnel (which operates identically in both models), Union.ai maintains a **private management connection** to the customer's Kubernetes cluster in BYOC deployments. This connection uses cloud-native private connectivity:

| Cloud Provider | Technology |
| --- | --- |
| AWS | AWS PrivateLink |
| GCP | GCP Private Service Connect |
| Azure | Azure Private Link |

This connection is used exclusively for cluster management operations (upgrades, provisioning, health monitoring) and does not carry customer data. The Kubernetes API endpoint is never exposed to the public Internet.

This means BYOC has an additional communication path not present in self-managed deployments:

| Communication Path | Protocol | Encryption |
| --- | --- | --- |
| Union.ai → Customer K8s API | PrivateLink / PSC | TLS (private connectivity) |

This satisfies ISO 27001 A.5.15 (access control), CIS v8 4.4 (restrict administrative access), and CIS v8 12.11 (segment administration interfaces) requirements.

## Human access to customer environments

In self-managed deployments, Union.ai personnel access only the customer's control plane tenant. They have zero access to the customer's data plane infrastructure.

In BYOC deployments, Union.ai support and engineering personnel additionally have **authenticated access to the customer's Kubernetes cluster** for operational purposes:

* Cluster upgrades
* Node pool provisioning
* Helm chart updates
* Health monitoring and troubleshooting

This access is via cloud-native private connectivity (PrivateLink/PSC) and is scoped to K8s cluster management. Union.ai personnel still **cannot** access:

* Customer object stores
* Secrets backends
* Container registries
* Log aggregators

All cluster management actions are logged. Union.ai is implementing **just-in-time (JIT) access controls** to replace persistent support access with time-bound, customer-authorized grants.

The scope of "administrative operations" also differs: in self-managed, these are limited to control plane API calls (cluster configuration, namespace provisioning). In BYOC, they extend to direct K8s cluster management through the PrivateLink/PSC connection.

## Secrets management

The default secrets backend differs by deployment model:

* **Self-managed:** Kubernetes Secrets (K8s etcd) is the default
* **BYOC:** A cloud-native secrets backend (AWS Secrets Manager, GCP Secret Manager, or Azure Key Vault) is the default, for managed integration with the provisioning workflow

All four backends remain available as options in both models. The security properties (write-only API, runtime-only consumption, in-memory relay) are identical.

## Infrastructure management

In self-managed deployments, the customer manages their own Kubernetes clusters, including provisioning, configuration, version management, node pools, and security patching.

In BYOC deployments, Union.ai manages the Kubernetes cluster in the customer's cloud account:

* **Cluster provisioning and configuration**
* **Kubernetes version management and upgrades**
* **Node pool health and autoscaler configuration**
* **Helm chart updates for platform components**
* **Monitoring stack deployment and maintenance** (Prometheus, Grafana, Fluent Bit)
* **Serving infrastructure lifecycle** (Kourier gateway, Knative, Union Operator)

The customer retains responsibility for their cloud account's underlying infrastructure (VPC, IAM policies, object storage configuration).

### IAM role provisioning

The same two IAM roles (`adminflyterole` and `userflyterole`) exist in both models. In self-managed, the customer provisions them using Union.ai's documentation and templates. In BYOC, Union.ai provisions these roles as part of cluster setup.

### Data plane patching

In self-managed, the customer is responsible for all data plane patching (K8s version, platform components, monitoring stack). In BYOC, Union.ai manages data plane updates, including Kubernetes version, helm charts, and platform components. The control plane is updated independently in both models.

## Availability and resilience

Control plane availability is identical across both models (AWS multi-AZ, managed PostgreSQL with automated failover, SOC 2 Type II coverage).

The difference is in data plane availability:

* **Self-managed:** The customer is solely responsible for data plane availability, including Kubernetes cluster operations, node pool management, upgrades, and monitoring. Union.ai's availability commitment covers only the control plane.
* **BYOC:** Union.ai is responsible for data plane cluster availability, including Kubernetes version management, node pool health, autoscaler configuration, and monitoring stack uptime. The customer retains responsibility for their cloud account's underlying availability (VPC, IAM, object storage SLAs). Union.ai's operational SLA for BYOC cluster management is defined in the customer contract.

In both models, in-flight workflows continue executing during control plane outages. The operational difference is that in BYOC, Union.ai's monitoring detects control plane connectivity issues; in self-managed, the customer must detect these independently.

## Third-party dependency risk

In self-managed, the customer owns all data plane dependencies. Union.ai's dependency risk scope is limited to the control plane and Cloudflare tunnel.

In BYOC, Union.ai assumes operational responsibility for cluster-level dependencies and their associated risk mitigation:

* Kubernetes version
* Helm charts
* Monitoring stack (Prometheus, Grafana, Fluent Bit)
* Serving infrastructure (Kourier, Knative)

Union.ai's vendor management program, covered under the SOC 2 Type II audit, includes periodic evaluation of these dependencies.

## Shared responsibility model

The shared responsibility model shifts in BYOC for data plane operations:

| Responsibility Area | Self-Managed | BYOC |
| --- | --- | --- |
| Control plane security | Union.ai | Union.ai |
| Data plane K8s cluster | Customer | Union.ai |
| Cloud account (VPC, IAM) | Customer | Customer |
| Data encryption at rest | Customer (CMK optional) | Customer (CMK optional) |
| Network security (tunnel) | Union.ai (tunnel) + Customer (firewall/VPC) | Union.ai (tunnel + PrivateLink) + Customer (VPC) |
| IAM role provisioning | Customer | Union.ai |
| Secrets management | Customer (backend selection + values) | Union.ai (default backend) + Customer (values) |
| Application-level access control | Customer (role assignment) | Customer (role assignment) |
| Compliance documentation | Union.ai (SOC 2, Trust Center) + Customer | Union.ai (SOC 2, Trust Center) + Customer |

## HIPAA and compliance

Union.ai's HIPAA compliance support applies equally to both deployment models. The architecture ensures that all customer data -- including any PHI -- remains exclusively in the customer's own cloud infrastructure regardless of who manages the K8s cluster. The control plane stores only orchestration metadata and never persists PHI.

## Contact and resources

* Trust Center: [trust.union.ai](https://trust.union.ai)
* SOC 2 Type II Report: Available upon request
* Security Inquiries: Contact your Union.ai account representative or visit [trust.union.ai](https://trust.union.ai)


=== PAGE: https://www.union.ai/docs/v2/union/security/data-residency-summary ===

# Data residency summary

| Data | Stored In | Accessed Via | Transits Control Plane? |
| --- | --- | --- | --- |
| Task definitions (spec metadata) | Control plane DB | ConnectRPC | Yes — metadata only |
| Run metadata (phase, timestamps) | Control plane DB | ConnectRPC | Yes |
| Action metadata (phase, attempts) | Control plane DB | ConnectRPC | Yes |
| Task inputs/outputs | Customer object store | Presigned URL | No — direct client ↔ object store |
| Code bundles | Customer object store | Presigned URL | No — direct client ↔ object store |
| Reports (HTML) | Customer object store | Presigned URL | No — direct client ↔ object store |
| Container images | Customer container registry | Pulled by K8s | No — stays in customer infra |
| Task logs | Customer log aggregator | Streamed via tunnel | Relayed in-memory (not stored) |
| Secrets | Customer secrets backend | Injected at runtime | Relayed during create (not stored) |
| Observability metrics | Customer ClickHouse | Proxied via DataProxy | Relayed in-memory (not stored) |
| User identity / RBAC | Control plane DB | ConnectRPC | Yes |
| Cluster state | Control plane DB | Internal | Yes |


=== PAGE: https://www.union.ai/docs/v2/union/security/presigned-url-data-types ===

# Presigned URL data types

| Data Type | Access Method | Direction |
| --- | --- | --- |
| Task inputs/outputs | Presign via ObjectStore service | Download (GET) |
| Code bundles (TGZ) | CreateDownloadLinkV2 | Download (GET) |
| Reports (HTML) | CreateDownloadLinkV2 | Download (GET) |
| Fast registration uploads | CreateUploadLocation | Upload (PUT) |


=== PAGE: https://www.union.ai/docs/v2/union/security/kubernetes-rbac-control-plane ===

# Kubernetes RBAC: Control plane

**All roles are ClusterRole**

| Role Name | Purpose | API Groups | Resources | Verbs |
| --- | --- | --- | --- | --- |
| `flyteadmin` | Full control over K8s resources for workflow orchestration, namespace provisioning, RBAC setup for workspaces | ""(core) `flyte.lyft.com rbac.authorization.k8s.io` | `configmaps flyteworkflows namespaces pods resourcequotas roles rolebindings secrets services serviceaccounts spark-role limitranges` | *(all) |
| `scyllacluster-edit` | Aggregated admin/edit role for ScyllaDB cluster management (control plane database) | `scylla.scylladb.com` | `scyllaclusters scylladbmonitorings scylladbdatacenters scylladbclusters scylladbmanagerclusterregistrations scylladbmanagertasks` | `create patch update delete deletecollection` |
| `scylladb:controller:aggregate-to-operator` | ScyllaDB operator controller - manages ScyllaDB cluster lifecycle for the control plane database | ""(core) `apps policy scylla.scylladb.com networking.k8s.io batch` | `events nodes endpoints persistentvolumeclaims pods services configmaps secrets statefulsets deployments daemonsets jobs poddisruptionbudgets serviceaccounts scyllaclusters scyllaoperatorconfigs nodeconfigs ingresses` | `get list watch create update delete patch` |
| `scylla-operator:webhook` | ScyllaDB webhook server for admission control of ScyllaDB resources | `admissionregistration.k8s.io scylla.scylladb.com` | `validatingwebhookconfigurations mutatingwebhookconfigurations scyllaclusters nodeconfigs scyllaoperatorconfigs scylladbdatacenters scylladbclusters scylladbmanagertasks` | `get list watch create update patch delete` |
| `console-clusterrole` | Read-only access for Union Console UI to display namespaces, workflows, and pod logs | ""(core) `flyte.lyft.com` | `namespaces flyteworkflows pods pods/log` | `get list watch` |
| `authorizer-clusterrole` | Authorizer service reads namespaces for authorization decisions | ""(core) | `namespaces` | `get list watch` |
| `cluster-clusterrole` | Cluster management service monitors cluster state for health and capacity | ""(core) `apps` | `namespaces nodes replicasets deployments` | `get list watch` |
| `dataproxy-clusterrole` | DataProxy service reads secrets for presigned URL generation and data relay configuration | ""(core) | `secrets` | `get list watch` |
| `executions-clusterrole` | Executions service reads workflow state for execution management and status tracking | ""(core) `flyte.lyft.com` | `namespaces configmaps flyteworkflows` | `get list watch` |
| `queue-clusterrole` | Queue service reads namespaces for task queue routing | ""(core) | `namespaces` | `get list watch` |
| `run-scheduler-clusterrole` | Run Scheduler reads namespaces to determine scheduling scope for workflows | ""(core) | `namespaces` | `get list watch` |
| `usage-clusterrole` | Usage tracking service reads namespaces for resource usage aggregation | ""(core) | `namespaces` | `get list watch` |


=== PAGE: https://www.union.ai/docs/v2/union/security/kubernetes-rbac-data-plane ===

# Kubernetes RBAC: Data plane

## Union core services (data plane)

| Role Name | Purpose | Kind | API Groups | Scope | Resources | Verbs |
| --- | --- | --- | --- | --- | --- | --- |
| `clustersync-resource` | Synchronizes K8s resources across namespaces: creates per-workspace namespaces, RBAC bindings, service accounts, and resource quotas | ClusterRole | ""(core) `rbac.authorization.k8s.io` | Cluster-wide | `configmaps namespaces pods resourcequotas roles rolebindings secrets services serviceaccounts clusterrolebindings` | *(all) |
| `union-executor` | Node Executor: creates/manages task pods, handles FlyteWorkflow and TaskAction CRDs, manages all plugin resource types (Spark, Ray, etc.) | ClusterRole | ""(core) *(all) `apiextensions.k8s.io flyte.lyft.com` | Cluster-wide | `pods (RO) events *(all plugin objects) customresourcedefinitions flyteworkflows/* taskactions/*` | `get list watch create update delete patch` |
| `proxy-system` | Read-only monitoring: streams workflow events, pod logs, and resource utilization data back to control plane via tunnel | ClusterRole | "*" | Cluster-wide | `events flyteworkflows pods/log pods rayjobs resourcequotas` | `get list watch` |
| `operator-system` | Union Operator: manages FlyteWorkflow lifecycle, cluster-level configuration, health monitoring, node management | ClusterRole | `flyte.lyft.com` *(all) | Cluster-wide | `flyteworkflows flyteworkflows/finalizers resourcequotas pods configmaps podtemplates secrets namespaces nodes` | `get list watch create update delete patch post deletecollection` |
| `flytepropeller-role` | FlytePropeller workflow engine: creates task pods, manages FlyteWorkflow CRDs, handles all plugin resource types, enforces resource limits | ClusterRole | ""(core) *(all) `apiextensions.k8s.io flyte.lyft.com` | Cluster-wide | `pods (RO) events *(all plugin objects) customresourcedefinitions flyteworkflows/* limitranges` | `get list watch create update delete patch` |
| `flytepropeller-webhook-role` | Admission webhook: intercepts pod creation to inject secrets from the secrets backend into task containers | ClusterRole | "*" | Cluster-wide | `mutatingwebhookconfigurations secrets pods replicasets/finalizers` | `get create update patch` |
| `proxy-system-secret` | Manages proxy service secrets within the union namespace for tunnel authentication and configuration | Role | "*" | union namespace | `secrets` | `get list create update delete` |
| `operator-system` (ns) | Operator manages its own secrets and deployments within the union namespace | Role | "*" | union namespace | `secrets deployments` | `get list watch create update` |
| `union-operator-admission` | Webhook admission controller reads/creates TLS secrets for webhook serving certificates | Role | ""(core) | union namespace | `secrets` | `get create` |

## Observability and monitoring

| Role Name | Purpose | Kind | API Groups | Scope | Resources | Verbs |
| --- | --- | --- | --- | --- | --- | --- |
| `release-name-fluentbit` | Fluent Bit log collector: reads pod metadata to tag and route container logs to CloudWatch/Cloud Logging | ClusterRole | ""(core) | Cluster-wide | `namespaces pods` | `get list watch` |
| `opencost` | OpenCost: read-only access to all cluster resources for cost attribution and resource usage tracking | ClusterRole | ""(core) `extensions apps batch autoscaling storage.k8s.io` | Cluster-wide | `configmaps deployments nodes pods services resourcequotas replicationcontrollers limitranges PVCs PVs namespaces endpoints daemonsets replicasets statefulsets jobs storageclasses` | `get list watch` |
| `release-name-kube-state-metrics` | KSM: exports K8s object metrics for Prometheus monitoring dashboards | ClusterRole | ""(core) `extensions apps batch autoscaling policy networking.k8s.io certificates.k8s.io discovery.k8s.io storage.k8s.io admissionregistration.k8s.io` | Cluster-wide | `certificatesigningrequests configmaps cronjobs daemonsets deployments endpoints HPAs ingresses jobs leases limitranges namespaces networkpolicies nodes PVCs PVs pods replicasets replicationcontrollers resourcequotas secrets services statefulsets storageclasses validatingwebhookconfigurations volumeattachments endpointslices` | `list watch` |
| `release-name-grafana-clusterrole` | Grafana: reads `configmaps`/`secrets` for dashboard definitions and data source configuration | ClusterRole | ""(core) | Cluster-wide | `configmaps secrets` | `get watch list` |
| `union-operator-prometheus` | Prometheus: scrapes metrics from all cluster services and nodes for monitoring | ClusterRole | ""(core) `discovery.k8s.io networking.k8s.io` | Cluster-wide | `nodes nodes/metrics services endpoints pods endpointslices ingresses`; `nonResourceURLs`: `/metrics /metrics/cadvisor` | `get list watch` |
| `prometheus-operator` | Prometheus Operator: manages the full Prometheus monitoring stack lifecycle, CRDs, and configurations | ClusterRole | `monitoring.coreos.com apps extensions` (core) `networking.k8s.io policy admissionregistration.k8s.io storage.k8s.io` | Cluster-wide | `alertmanagers prometheuses thanosrulers servicemonitors podmonitors prometheusrules probes scrapeconfigs prometheusagents statefulsets daemonsets deployments configmaps secrets pods services endpoints namespaces ingresses PDBs webhookconfigs storageclasses` | *(all) |
| `release-name-dcgm-exporter` | DCGM Exporter: reads node/pod metadata for GPU metrics labeling (optional, for GPU workloads) | ClusterRole | ""(core) | Cluster-wide | `nodes pods` | `get list watch` |


=== PAGE: https://www.union.ai/docs/v2/union/security/aws-iam-roles ===

# AWS IAM roles

In self-managed deployments, the customer provisions these roles using Union.ai's documentation and templates. In BYOC deployments, [Union.ai provisions them](./byoc-differences#iam-role-provisioning).

| Plane | Service Account | Purpose | K8s Namespace | IAM Role ARN Pattern | Bound To | S3 Access |
| --- | --- | --- | --- | --- | --- | --- |
| Control Plane | `flyteadmin` | Orchestration metadata management, namespace provisioning, presigned URL generation for code upload/download | union | `arn:aws:iam::<account-id>:role/adminflyterole` | FlyteAdmin (workflow admin service) | Generates presigned URLs for customer S3 buckets (does not directly read/write data) |
| Data Plane | `clustersync-system` | Synchronizes K8s namespaces, RBAC roles, service accounts, resource quotas, and config across the cluster | union | `adminflyterole` (data plane admin) | ClusterResourceSync controller | No direct S3 access |
| Data Plane | `executor` | Receives task assignments via tunnel, creates task pods, manages pod lifecycle, reports status back to control plane | union | `adminflyterole` (data plane admin) | Node Executor (TaskAction controller) | R/W to metadata bucket and fast-registration bucket for staging task inputs/outputs |
| Data Plane | `proxy-system` | Monitors events, Flyte workflows, pod logs; streams data back to control plane via tunnel | union | `adminflyterole` (data plane admin) | Proxy Service | Read-only access to metadata bucket for proxying presigned URL requests |
| Data Plane | `operator-system` | Cluster operations, health monitoring, config management, image builder orchestration, tunnel management | union | `adminflyterole` (data plane admin) | Union Operator | R/W to metadata bucket for operator state and config |
| Data Plane | `flytepropeller-system` | K8s operator managing FlyteWorkflow CRDs, pod creation, workflow lifecycle execution | union | `adminflyterole` (data plane admin) | FlytePropeller (workflow engine) | R/W to metadata bucket for workflow data (inputs, outputs, offloaded data) |
| Data Plane | `flytepropeller-webhook-system` | Mutating admission webhook that injects secrets into task pods at creation time | union | `adminflyterole` (data plane admin) | FlytePropeller Webhook | No direct S3 access (handles secrets injection only) |
| Data Plane | `clusterresource-template` (per-namespace) | Executes user workflow tasks; reads inputs, writes outputs to S3 | Per-workspace namespace | `userflyterole` (data plane user) | Task Pods (user workloads) | R/W to metadata bucket for task inputs/outputs, code bundles, artifacts |

For BYOC-specific deployment concerns, see [BYOC deployment differences](./byoc-differences).