Command line tool (CLI)

veHaaS command line tool enables you to interact with the veHaaS services using commands in your command-line shell or from python scripts.

Deprecation notice

The v2 get-jobs subcommand is deprecated as of v1.20.0. It remains functional but will be removed in a future version. A v3 CLI subcommand is planned and will be documented when available.

Installation

The veHaaS command line tool requires Python >=3.10 to be installed. You can verify the installed Python version by running:

:

python --version

If Python is not installed, refer to the Python download page for instructions on installing Python.

Once Python is installed, use pip to install the veHaaS command line tool:

:

pip install pes-vehaas

After installation, confirm that the veHaaS command line tool is installed correctly by running:

:

vehaas --version

This command should display the installed version the veHaaS command line tool, indicating a successful installation. :

vehaas, version 1.0.8

Syntax

The veHaaS command line tool uses a multipart structure that is specified in the following order

:

vehaas <command> <subcommand> [options]

1. Invocation of the command line tool: This is the initial call to the vehaas command.
2. Top-level command: The primary command either use-case or API version specific.
3. Subcommand: Additional commands that refine the action. Multiple levels of subcommands can be nested.
4. Command options: Options that modify the behavior of the command or subcommand. These can be specified using - or -- flags.

Environment variables

This section explains how to configure environment variable settings for the veHaaS command line tool. These include the following environment variables that are supported:

Variable	Description
VEHAAS_HOST	The URL of the veHaaS API. By default https://vehaas.vi.vector.int/ is used.
VEHAAS_TOKEN	The token to authenticate with the veHaaS API. Go to access-tokens for more information.

You can set the VEHAAS_HOST and VEHAAS_TOKEN environment variables to specify the API URL and authentication token, eliminating the need to provide them with each command invocation.

Commands

The commands of the veHaaS command line tool are divided into two main categories: commands for specific use cases and commands to interact with specific versions of the veHaaS API.

Use-case-specific commands are utility functions designed to implement specific workflows, simplifying usage and providing additional convenience for the user. These include commands for session booking in the CI workflow and commands for administrative purposes.

Additionally, the veHaaS command line tool includes commands for all available API versions. These commands are autogenerated by the OpenAPI Generator, allowing users to interact with various API endpoints. They are categorized by the version of the veHaaS API, ensuring that users can easily find and use the commands relevant to the specific API version they are working with.

Assembly session commands

The assembly session commands are used for the session booking in the CI workflow.

Assembly session commands

Usage: vehaas [OPTIONS] COMMAND [ARGS]...

  Command line tool to interact with the veHaaS API.

  Version: 1.0.8

  Environment variables:
    VEHAAS_HOST: The host URL of the veHaaS API.
    VEHAAS_TOKEN: The token to authenticate with the veHaaS API.

Options:
  --version   Show the version and exit.
  -h, --help  Show this message and exit.

Commands:
  book-maintenance        CLI command to book a maintenance window over a...
  create-session-request  CLI command to create a session request.
  delete-maintenance      Creates a session request and waits until the...
  maintenance             Maintenance related commands.
  release-session         CLI command to release an assembly session as...
  v2                      API v2 commands.

create-session-request

This command will create a new session request and waits until the session is either successfully booked or the request is rejected.

create-session-request

vehaas create-session-request --duration 30 --assembly-ref "ASSEMBLY-0"

Options

Option	Default	Description
--duration		Duration of the session in minutes.
--timeout	10	Timeout for the session request in minutes.
--assembly-ref		Assembly reference that should be checked for booking. Can be set multiple times to check multiple assemblies.
--request-profile		Assembly profile json. If set all other request profile options are ignored.
--provider-url		The URL of the GitLab runner provider. If set the gitlab runner is enabled. Otherwise not.
--virtual-machine-label		The label of the virtual machine.
--host	'https://vehaas.vi.vector.int/'	The host URL of the veHaaS API. Uses value of $VEHAAS_HOST if set.
--token		The token to authenticate with the veHaaS API. Uses value of $VEHAAS_TOKEN if set.

release-session

Release an assembly session as soon as possible. The cleanup duration needed will be automatically calculated. The updated assembly session with the calculated end time will be printed to the console.

release-session

vehaas release-session --session-id "27c21e35-bded-49bd-89a1-8e792942601c"

Options

Option	Default	Description
--session-id		ID of the session to release.
--host	'https://vehaas.vi.vector.int/'	The host URL of the veHaaS API. Uses value of $VEHAAS_HOST if set.
--token		The token to authenticate with the veHaaS API. Uses value of $VEHAAS_TOKEN if set.

Maintenance commands

Maintenance commands are used for administrative purposes.

Maintenance commands

Usage: vehaas [OPTIONS] COMMAND [ARGS]...

  Command line tool to interact with the veHaaS API.

  Version: 1.0.8

  Environment variables:
    VEHAAS_HOST: The host URL of the veHaaS API.
    VEHAAS_TOKEN: The token to authenticate with the veHaaS API.

Options:
  --version   Show the version and exit.
  -h, --help  Show this message and exit.

Commands:
  book-maintenance        CLI command to book a maintenance window over a...
  create-session-request  CLI command to create a session request.
  delete-maintenance      Creates a session request and waits until the...
  maintenance             Maintenance related commands.
  release-session         CLI command to release an assembly session as...
  v2                      API v2 commands.

book-maintenance

Book a maintenance window over a fixed schedule.

book-maintenance

vehaas book-maintenance \
--start-date "2025-02-17" \
--start-time "10:00" \
--duration 30 \
--end-recurrent-date "2025-02-20" \
--description "important maintenance" \
--assembly-ref "ASSEMBLY-0" \
--interval "daily"

Options

Option	Default	Description
--start-date		Start date (YYYY-MM-DD)
--start-time		Time of the maintenance (HH:MM)
--duration		Duration of the maintenance in minutes
--end-recurrent-date		Optional end date for recurrence (YYYY-MM-DD)
--description		Description of the maintenance
--assembly-ref		Assembly ref to book the maintenance for. The default is all assemblies.
--interval		Interval type for the maintenance (daily, weekly, monthly, one-time)
--skip		Number of intervals to skip
--host	'https://vehaas.vi.vector.int/'	The host URL of the veHaaS API. Uses value of $VEHAAS_HOST if set.
--token		The token to authenticate with the veHaaS API. Uses value of $VEHAAS_TOKEN if set.

delete-maintenance

Delete a (recurring) maintenance window.

delete-maintenance

vehaas delete-maintenance --context-grouping-id "3b81efc4cdda4b02bf9d49482c62fd30"

Options

Option	Default	Description
--context-grouping-id		The context grouping ID to delete. You can find this in the description of the context.
--host	'https://vehaas.vi.vector.int/'	The host URL of the veHaaS API. Uses value of $VEHAAS_HOST if set.
--token		The token to authenticate with the veHaaS API. Uses value of $VEHAAS_TOKEN if set.

create-vm

This command takes a technical-user with a defined pattern (svc-pes-hil-*) from vault of the stockpile and assigns it to the newly created VM.

maintenance create-vm

vehaas maintenance create-vm \
--vault-token $VAULT_TOKEN \
--vm-host-name "vistrpeshilxxxx.vi.vector.int" \
--cluster-ref "CLUSTER-1"

Options

Option	Default	Description
--vault-addr	'https://pes01.prod.vault.d4s.vi.vector.int'	Address of the Vault instance.
--vault-token		Token for the Vault instance.
--vault-mount		Vault mount point.
--vault-path		Path to the Vault secret.
--vault-path-pattern		Vault path pattern to select a random secret
--vm-hostname		Hostname of the new VM
--vm-labels		List of labels for the new VM (optional).
--vm-properties		Dictionary in JSON format (optional)
--cluster-ref		Reference to an existing cluster
--verbose-secrets		Show password in plaintext on the cli.
--host	'https://vehaas.vi.vector.int/'	The host URL of the veHaaS API. Uses value of $VEHAAS_HOST if set.
--token		The token to authenticate with the veHaaS API. Uses value of $VEHAAS_TOKEN if set.

API commands

These commands are grouped by their API version tag (e.g. v2) and allow the user to interact with all available veHaaS API endpoints.

API commands

Usage: vehaas [OPTIONS] COMMAND [ARGS]...

  Command line tool to interact with the veHaaS API.

  Version: 1.0.8

  Environment variables:
    VEHAAS_HOST: The host URL of the veHaaS API.
    VEHAAS_TOKEN: The token to authenticate with the veHaaS API.

Options:
  --version   Show the version and exit.
  -h, --help  Show this message and exit.

Commands:
  book-maintenance        CLI command to book a maintenance window over a...
  create-session-request  CLI command to create a session request.
  delete-maintenance      Creates a session request and waits until the...
  maintenance             Maintenance related commands.
  release-session         CLI command to release an assembly session as...
  v2                      API v2 commands.

Get help

To get more information on available commands for each API version, you can invoke the --help option on the API version tag.

:

vehaas v2 --help

This will display an overview of all commands for the specified API version, grouped by their resource type. These groups are organized similarly to the API endpoints in the [veHaaS API docs](https://vehaas.vi.vector.int/api/v2.0/docs), where you can interactively explore, call, and test the veHaaS API directly from your browser.

??? info "API commands grouped by resource type"

    ```sh hl_lines="9-27"
    Usage: vehaas v2 [OPTIONS] COMMAND [ARGS]...

      API v2 commands.

    Options:
      -h, --help  Show this message and exit.

    Commands:
      access-tokens                 API access-tokens commands.
      assemblies                    API assemblies commands.
      assembly-group-relationships  API assembly-group-relationships commands.
      assembly-session-contexts     API assembly-session-contexts commands.
      assembly-session-transfers    API assembly-session-transfers commands.
      assembly-sessions             API assembly-sessions commands.
      banners                       API banners commands.
      clusters                      API clusters commands.
      default                       API default commands.
      deprecation-info              API deprecation-info commands.
      groups                        API groups commands.
      health                        API health commands.
      jobs                          API jobs commands.
      monitoring                    API monitoring commands.
      organizations                 API organizations commands.
      users                         API users commands.
      virtual-machines              API virtual-machines commands.
      websocket-ticket              API websocket-ticket commands.
    ```

To get an overview of all commands available for a specific resource type, you can use the --help flag and traverse through the subcommands. For example, to see all commands for assembly-sessions, run:

:

vehaas v2 assembly-sessions --help

This will list all commands related to assembly-sessions.

??? info "Commands available for assembly-sessions"

    ```sh hl_lines="9-15"
    Usage: vehaas v2 assembly-sessions [OPTIONS] COMMAND [ARGS]...

      API assembly-sessions commands.

    Options:
      -h, --help  Show this message and exit.

    Commands:
      create-assembly-session         Create Assembly Session
      delete-assembly-session         Delete Assembly Session
      get-assembly-session            Get Assembly Session
      get-assembly-sessions           Get Assembly Sessions
      get-session-tasks-for-assembly-session
                                      Get Session Tasks For Assembly...
      update-assembly-session         Update Assembly Session
    ```

From there, you can run --help on the individual subcommands. For example, to see the options and syntax for create-assembly-session, run:

:

vehaas v2 assembly-sessions create-assembly-session --help

This will display the available options and the basic syntax of the command.

??? info "create-assembly-session command syntax and options"

    ```sh
    Usage: vehaas v2 assembly-sessions create-assembly-session [OPTIONS]

      Create Assembly Session

      Creates and returns a new assembly session.

    Options:
      --assembly-session-request   (AssemblySessionRequest) Allocate request.
                                  Example:
                                  {
                                    "start_time" : "2000-01-23T04:56:07.000+00:00",
                                    "assembly_ref" : "assembly_ref",
                                    "end_time" : "2000-01-23T04:56:07.000+00:00"
                                  }
      --host (optional)            The host URL of the veHaaS API. Defaults to
                                  https://vehaas.vi.vector.int/
      --token (optional)           The token to authenticate with the veHaaS API.
      -h, --help                   Show this message and exit.
    ```

Examples

get-assembly

get-assembly

$ vehaas v2 assemblies get-assembly --assembly-ref "ASSEMBLY-0"

{
  "assembly_ref": "ASSEMBLY-0",
  "assembly_profile": {
    "assembly_ref": "ASSEMBLY-0",
    "assembly_name": "Spielwiese",
    "cluster_ref": null,
    ...
  },
  "status_type": "available",
  "is_operational": true,
  "user_id": null,
  "user_name": null,
  "favorite": false,
  "is_public": true,
  "cluster_ref": "dummy-cluster",
  "virtual_machines": null
}

create-assembly

create-assembly

$ vehaas v2 assemblies create-assembly \
    --json-file $FILE_PATH \
    --is-public "false" \
    --organization-id "organization-id-1"

{
  "assembly_ref": "assembly-1",
  "assembly_profile": {
    "assembly_ref": "assembly-1",
    "assembly_name": "My_Assembly-1",
    "cluster_ref": "CLUSTER-0",
    ...
  },
  "status_type": "on stock",
  "is_operational": false,
  ...
}

Python script

Since the veHaaS command line tool is written in Python, it can also be imported as a package and used directly in your Python scripts. The following example demonstrates how to interact with the veHaaS API using the veHaaS command line tool:

Python script

import json
import os
from datetime import datetime, timedelta, timezone

from pydantic.json import pydantic_encoder
from vehaas.openapi_client_v2 import ApiClient, Configuration
from vehaas.openapi_client_v2.api import AssembliesApi, AssemblySessionsApi
from vehaas.openapi_client_v2.models import AssemblySessionRequest

VEHAAS_URL = "https://vehaas.vi.vector.int"  # must be without trailing slash
VEHAAS_TOKEN = os.environ.get("VEHAAS_TOKEN", "")


def main() -> None:
    # Client configuration
    config = Configuration(host=VEHAAS_URL)
    client = ApiClient(configuration=config)
    client.default_headers["private-token"] = VEHAAS_TOKEN

    assembly_session_client = AssemblySessionsApi(api_client=client)
    assemblies_api = AssembliesApi(api_client=client)

    # Create a new assembly session
    start_time = datetime.now(timezone.utc)
    session_response = assembly_session_client.create_assembly_session(
        assembly_session_request=AssemblySessionRequest(
            assembly_ref="ASSEMBLY-101", start_time=start_time, end_time=start_time + timedelta(minutes=30)
        )
    )
    print("Assembly Session Response:")
    print(json.dumps(session_response, indent=2, default=pydantic_encoder))

    # Get the assembly session
    session = assembly_session_client.get_assembly_session(session_id=session_response.session_id)
    print("\nAssembly Session:")
    print(json.dumps(session, indent=2, default=pydantic_encoder))

    # Get the assembly profile
    assembly = assemblies_api.get_assembly(assembly_ref=session.assembly_ref)

    print("\nAssembly Profile:")
    print(json.dumps(assembly.assembly_profile, indent=2, default=pydantic_encoder))


if __name__ == "__main__":
    main()