Developer Guide
App Bundle Structure
Each q8s-compatible app has to be bundled as a zip archive (commonly used with suffix .qz
)
consisting of:
wave-app.toml
- to q8s configuration filestatic/
- static asset directory, including the app icon (a png file starting withicon
) and screenshots (files starting withscreenshot
)requirements.txt
- pip-managed dependencies of the app (can contain references to.whl
files included in the.qz
using paths relative to the archive root)- app source code
You can quickly create a .qz
archive by running q8s-cli bundle
in your app git repository
(see the CLI section)
q-app.toml
Each q8s-compatible app has to contain a q-app.toml
configuration file in the TOML format,
placed in the root of the .qz
archive, example:
Required attributes:
App
Name
- a machine-oriented unique identifier of the app (links different app versions together)Version
- a https://semver.org version of the app
Runtime
Module
- the name of the main Python module of the app, i.e., the app should be started viapython3 -m $module_name
Optional attributes:
App
Title
- a human-oriented name of the app for presentation in UI/CLI; stringDescription
- a multiline description of the app for presentation in UI/CLI; stringCategory
- category for organizing apps into groups, string (UI recognizesAll
,Data Science
,Financial Services
,Healthcare
,Insurance
,Manufacturing
,Marketing
,Retail
,Sales
,Telecommunications
, andOther
)Keywords
- keywords for search in the UI/CLI, list of strings
Runtime
VolumeMount
andVolumeSize
- request for a volume to persist app instance data across restarts,VolumeMount
has to be an absolute path,VolumeSize
needs to conform to the k8s resource model.MemoryLimit
andMemoryReservation
- memory requirements for an instance of the app (default to service-wide settings managed by Admins); be conservative with these limits;MemoryLimit
is a hard limit on the maximum amount of memory an instance can use before it is OOM-killed;MemoryReservation
is how much memory is required to schedule an instance of the app.
Env
- request for a configuration/secret to be injected into an instance at startup-time as an Env variable; repeated; see Utilizing Secrets.Name
- name of the Env variable to the injected into the Python processSecret
- name of the shared secret to use; each secret can contain multiple key-value pairsSecretKey
- name of the key within the secret to use
Runtime Environment
Q8s configures the app instance runtime environment, i.e., OS, OS dependencies, location of the app code/venv, etc.
Developers can specify the pip-managed dependencies of the app via requirements.txt
(can contain
references to .whl
files included in the .qz
using paths relative to the archive root)
Developers can further customize the runtime environment by Utilizing Secrets.
note
At this moment, q8s does not provide any provisions for developers to customize the OS, native OS dependencies, Qd version, etc.
We are actively working on improving this.
CLI
As a developer, you will need the q8s-cli
binary to interact with the q8s service.
Configuring the CLI
First you need to configure the CLI by running q8s-cli config setup
so that it knows how to talk
to a particular q8s deployment.
Be aware, currently the CLI launches a browser to complete the user authentication, and due to this we currently unable to support remote use of the CLI over SSH without provisions for X forwarding.
Listing existing apps
The q8s-cli app list -a
command will list all apps available for launch.
Launching existing apps
To launch an app, the q8s-cli app run <appId>
command can be used to launch a new instance of that app.
The -v
flag can be used with app run
to specify app instance visibility settings.
Publishing an app for others to see and launch
Just run q8s-cli bundle import
in your app git repository. This will automatically package your
current directory into a .qz
package and import it to q8s.
If you set the visibility to ALL_USERS
(via the -v
flag), others will be able use q8s-cli app run
or the UI to launch the app in q8s.
Note: the name-version combination from your q-app.toml
has to be unique and q8s will reject
the request if such combination already exists. Therefore, you need to update the version in q-app.toml
before each run.
Running an app under development in q8s
Just run q8s-cli bundle deploy
in your app git repository. This will automatically package your
current directory into a .qz
package, import it to q8s, and run it.
In the output you will be able to find a URL where you can reach the instance, or visit the "My Instances" in the UI.
Note: q8s will auto-generate the version so that you can keep executing this without worrying about version conflicts, just don't forget to clean up old instances/versions.
Getting the logs of a running q8s instance
Just run q8s-cli instance logs
, use the flag -f
(--follow
) to tail the log.
Running the app in q8s-like environment locally
Just run q8s-cli exec
. This will bundle the app in a temporary .qz
and launch it locally
using our q8s docker image.
Note that this requires that you have docker installed and that you have access to the docker image.
Then navigate to http://localhost:55555/<your main route>
.
Updating App Visibility
The q8s-cli app update <appId> -v <visbility>
command can be used to modify an existing app's visibility.
Authors who publish a new version of an app may want to de-list the old version. It is not possible
to remove an app if there are instances running, as the data may still need to be available.
The preferred method to de-list previous versions is to modify the visibility setting to PRIVATE
.
Updating Instance Visibility
The q8s-cli instance update <instanceId> -v <visbility>
command, much like the app
version,
can be used to modify an existing running instance's visibility setting.
How-To
Updating App To a Newer Version
The "Catalog" page shows apps with visibility ALL_USERS
, so rolling out a new app version is done by:
- importing a new version of the app as
PRIVATE
- testing the new version
- changing the visibility of the new version to
ALL USERS
- (optional) changing the visibility of the old version to
PRIVATE
This is based on the Basic Concepts:
Apps are mostly immutable, meaning once uploaded, they cannot be changed (except for visibility). To "update" an app, one has to upload a new version.
and:
Internally, H2O AI Cloud treats every app name/version combination as a separate entity. The UI then uses the app name to link several versions together; however each can have different title, description, owner, instances, etc.
An important corollary is that instances of the old app version are not affected by the update (as they are completely separate from the new app version). The update only prevents users from starting new instances of the old version.
Utilizing Secrets
Developers can pass secrets registered with q8s to apps, exposed as environment variables, using
the [[Env]]
section within the q-app.toml
.
This allows developers to link their apps with external dependencies (e.g., S3, Driverless AI) securely, while allowing easy overrides for local development.
Environment variables prefixed with Q8S
are disallowed.
note
There is currently not a self-service option for developers to add their own secrets, nor is there an API for listing the available secrets. Secrets are currently managed by Admins. Contact your admins for the available secrets or for adding a new one.
We are actively working on improving this.
App Route
While it is not a strict requirement, since each app in q8s is deployed with its own Qd,
it is advised that apps use /
as its main route: