Skip to content

Environments

Deployment versions and training experiments make use of environments. Using environments makes it possible to manage your code and the environment that it runs in separately. Reusing the same environment for different deployment versions and experiments, and thus standardizing them, can greatly reduce build time.

Environments are docker containers that are built by UbiOps. They determine the code environment in which your deployment or training code will run. Deployment code is loaded on top of the environment on instance start-up. Training code is loaded on top of the environment on training run initialization.

environment-layer

Base environments are prepared by UbiOps, and contain a code language (either Python or R). We currently support Python versions 3.7-11, and R version 4.0. We have also prepared base environments with CUDA-drivers pre-installed, to support the development on instance types with GPU support. You can find all base environments supported by UbiOps by going to the Environments tab in the WebApp. You can also find the reference name of each base environment here, which is the name you can use to reference this environment, when working with the Client Libraries or with the CLI.

UbiOps currently supports the following base environments:

base-environments

You can add additional dependency specifications to base environments, which will create a custom environment. This way, you can supplement the base environment with additional language-specific dependencies (including your own, e.g. from a custom pip repo), OS-level dependencies, or your own CUDA-version. Note that dependencies are only installed once, when building the environment. Keeping your environments small will result in a faster cold start time, as the environment is loaded in everytime an instance instance is started.

Uploading dependency information

Dependencies in an environment can be installed by uploading environment files with dependency information to UbiOps. You can specify what dependencies you want to use with these environment files, which can be either one or more of the following files:

  • requirements.txt - A list of Python packages required for the deployment. UbiOps will install the packages defined in this file for you using a fresh pip virtual environment once you upload your deployment. After this build step the dependencies are fixed and won't change. Read more about the requirements.txt file format and possibilities here.

  • libraries/ - directory where packages and system libraries can be installed that will be used in your deployment. This directory is added to the system $PATH variable,

  • A ubiops.yamlfile for installing OS level packages in the container. For more information see installing OS level packages.

  • install_packages.R - An R file containing instructions to install packages, like, install.packages("randomForest"). After this build step the dependencies are fixed and won't change.

  • renv.lock - A lockfile containing packages required for the deployment. In addition to install_packages.R, UbiOps supports renv as well, and will install the packages defined in this file for you using renv::restore() once you upload your deployment. For more information, take a look at renv documentation.

  • ubiops.yaml - A yaml file to install OS level packages in the container.

Preinstalled packages

To speed up the package installation process, some standard R packages are preinstalled:

All preinstalled packages

askpass, assertthat, backports, base64enc, BH, blob, broom, callr, cellranger, cli, clipr, colorspace, cpp11, crayon, curl, DBI, dbplyr, digest, dplyr, ellipsis, evaluate, fansi, farver, forcats, fs, generics, ggplot2, glue, gtable, haven, here, highr, hms, htmltools, httr, isoband, jsonlite, knitr, labeling, lifecycle, lubridate, magrittr, markdown, mime, modelr, munsell, openssl, pillar, pkgconfig, prettyunits, processx, progress, ps, purrr, R6, RColorBrewer, Rcpp, readr, readxl, rematch, remotes, renv, reprex, rlang, rmarkdown, rprojroot, rstudioapi, rvest, scales, selectr, stringi, stringr, sys, tibble, tidyr, tidyselect, tidyverse, tinytex, utf8, vctrs, viridisLite, withr, xfun, xml2, yaml

Using the CLI to create the zip for you

You can also make use of the UbiOps command line interface to create the zip for you and upload it to reduce manual work.

Validating environment files locally

These files can be validated locally with the validate function.

Uploading one of these files to your environment, will trigger a new build and create a new Revision for your environment. A revision is defined as an uploaded environment package. You can get information, like the status, about a revision by navigating to the Revision tab in the environment details page.

The XGBoost tutorial for example uses Python 3.9 as a base environment, with a requirements.txt with the following dependencies:

pandas==1.4.2
numpy==1.21.5
scikit-learn==1.0.2
scipy==1.7.3
xgboost==1.6.2
joblib==1.1.0
After uploading the deployment package, with this requirements.txt a custom environment will be implicitly created, and added to your list of custom environments.

Using public or private Git libraries is also possible by following this guide.

If the Python package is hosted on a different pip repository than the default PyPI repository, you can add a link to this custom pip repository by following this guide.

Managing environments

You can manage your environments using the WebApp and the UbiOps Client Library. In the WebApp you can find both the base environments that UbiOps offers and your own custom environments by going to the Environments tab.

environments-tab

Alternatively, you can use the environments_list function from the Client Library to get details of all environments that are currently in your project.

Create a custom environment

Custom environments can be created in two ways:

  • Explicitly: By creating an environment in the Environments tab in the WebApp. For an explicit custom environment you need to provide a name, the base environment you would like to use, and either a single dependency file, or a zipped folder that includes multiple dependency files. You can optionally also provide a description, and create labels for your custom environment. When creating a deployment version or a training experiment, you can select your custom environment from the environment dropdown. An example of this is shown in the XGBoost training tutorial.
  • Implicitly: which is done by adding environment files (the files mentioned in the Uploading dependency information section) to your deployment package. UbiOps will then generate a custom environment for you by adding the dependencies specified in these environment files to the base environment that you selected. UbiOps will give this new custom environment a name that consists of the base environment + deployment name + deployment version + 8 random characters, e.g. Python3.9-xgboost-deployment-v1-xxxxxxxx, and the label Created_by: UbiOps. This method is applied in the Tensorflow template tutorial.

You can also use the environments_create function from the Client Library to explicitly create a custom environment, where you need to provide the same parameters as with the WebApp (name, base environment, custom dependencies, and optionally labels). An example of using the environments_create using authorizing parameters is shown below.

import ubiops

project_name = 'project_name_example' # str
data = ubiops.EnvironmentCreate(
    name="python3-11-custom-1",
    display_name="My custom Python 3.11",
    base_environment="python3.11",
    description="",
    labels={}
)

# Create environments
api_response = core_api.environments_create(project_name, data)
print(api_response)

# Close the connection
api_client.close()

Updating environments

You can update a custom environment in the WebApp by clicking on the custom environment, and then on the Edit button on the top. You can then edit the name, add or remove labels, and upload new dependency files.

Updating an active environment

Changing an environment affects all deployment versions and/or training experiments that use that environment.

edit-custom-environment

The Client Library offers two functionalities for updating your environment:

  • The environments_update function can be used to update the (display) name, description, and labels of the environment.
  • The environment_revisions_file_upload can be used to upload a file containing new dependency information. Uploading a file will create a new revision and trigger a build. It is also possible to provide a source environment, from which the environment file will be copied.
import ubiops

project_name = 'project_name_example' # str
environment = 'environment_name_example' # str
data = ubiops.EnvironmentUpdate(
name="updated-custom-environment-name",
display_name="Updated Custom Environment display name",
description="",
labels={}
)


# Update environment
api_response = core_api.environments_update(project_name, environment, data)
print(api_response)
import ubiops

project_name = 'project_name_example' # str
environment = 'environment_name_example' # str
file = '/path/to/file' # file (optional)
source_environment = 'source_environment_example' # str (optional)

# Upload environment file
api_response = core_api.environment_revisions_file_upload(project_name, environment, file=file, source_environment=source_environment)
print(api_response)

Have a look at our Tutorials if you want to see some examples of how to define and use environments in your deployment versions and training experiments.