Kubeflow – Fairing

Docs: Overview of Kubeflow Fairing

Mon, 01 Jan 0001 00:00:00 +0000

Out of date

This guide contains outdated information pertaining to Kubeflow 1.0. This guide needs to be updated for Kubeflow 1.1.

Beta

This Kubeflow component has beta status. See the Kubeflow versioning policies. The Kubeflow team is interested in your feedback about the usability of the feature.

Kubeflow Fairing streamlines the process of building, training, and deploying machine learning (ML) training jobs in a hybrid cloud environment. By using Kubeflow Fairing and adding a few lines of code, you can run your ML training job locally or in the cloud, directly from Python code or a Jupyter notebook. After your training job is complete, you can use Kubeflow Fairing to deploy your trained model as a prediction endpoint.

Getting started

Use the following guides to get started with Kubeflow Fairing:

To set up your development environment, follow the guide to installing Kubeflow Fairing.
To ensure that Kubeflow Fairing can access your Kubeflow cluster, follow the guide to configuring your development environment with access to Kubeflow.
To learn more about how to use Kubeflow Fairing in your environment, follow the Kubeflow Fairing tutorials.

What is Kubeflow Fairing?

Kubeflow Fairing is a Python package that makes it easy to train and deploy ML models on Kubeflow. Kubeflow Fairing can also been extended to train or deploy on other platforms. Currently, Kubeflow Fairing has been extended to train on Google AI Platform.

Kubeflow Fairing packages your Jupyter notebook, Python function, or Python file as a Docker image, then deploys and runs the training job on Kubeflow or AI Platform. After your training job is complete, you can use Kubeflow Fairing to deploy your trained model as a prediction endpoint on Kubeflow.

The following are the goals of the Kubeflow Fairing project:

Easily package ML training jobs: Enable ML practitioners to easily package their ML model training code, and their code’s dependencies, as a Docker image.
Easily train ML models in a hybrid cloud environment: Provide a high-level API for training ML models to make it easy to run training jobs in the cloud, without needing to understand the underlying infrastructure.
Streamline the process of deploying a trained model: Make it easy for ML practitioners to deploy trained ML models to a hybrid cloud environment.

Next steps

Learn how to set up a Jupyter notebooks instance on your Kubeflow cluster.

Docs: Install Kubeflow Fairing

Mon, 01 Jan 0001 00:00:00 +0000

Out of date

This guide contains outdated information pertaining to Kubeflow 1.0. This guide needs to be updated for Kubeflow 1.1.

You can use Kubeflow Fairing to build, train, and deploy machine learning (ML) models in a hybrid cloud environment directly from Python code or a Jupyter notebook. This guide describes how to install Kubeflow Fairing in your development environment for local development, or development in a hosted notebook.

Using Kubeflow Fairing with Kubeflow notebooks

Kubeflow notebook servers that are built from one of the standard Jupyter Docker images include Kubeflow Fairing and come preconfigured for using Kubeflow Fairing to run training jobs on your Kubeflow cluster.

If you use a Kubeflow notebook server that was built from a custom Jupyter Docker image as your development environment, follow the instruction on setting up Kubeflow Fairing in a hosted notebook environment.

Set up Kubeflow Fairing for local development

Follow these instructions to set up Kubeflow Fairing for local development. This guide has been tested on Linux and Mac OS X. Currently, this guide has not been tested on Windows.

Set up Python

You need Python 3.6 or later to use Kubeflow Fairing. To check if you have Python 3.6 or later installed, run the following command:
```
python3 -V
```
The response should be something like this:
```
Python 3.6.5
```
If you do not have Python 3.6 or later, you can download Python from the Python Software Foundation.
Use virtualenv to create a virtual environment to install Kubeflow Fairing in. To check if you have virtualenv installed, run the following command:
```
which virtualenv
```
The response should be something like this:
```
/usr/bin/virtualenv
```
If you do not have virtualenv, use pip3 to install virtualenv.
```
pip3 install virtualenv
```
Create a new virtual environment, and activate it.
```
virtualenv venv --python=python3
source venv/bin/activate
```

Install Kubeflow Fairing

Run the following command to install Kubeflow Fairing in your virtual environment.

pip install kubeflow-fairing

After the install is complete, the fairing python package is available. Run the following command to verify that Kubeflow Fairing is installed:

pip show kubeflow-fairing

The response should be something like this:

Name: kubeflow-fairing
Version: 0.6.0
Summary: Kubeflow Fairing Python SDK.
Home-page: https://github.com/kubeflow/fairing
Author: Kubeflow Authors
Author-email: hejinchi@cn.ibm.com
License: Apache License Version 2.0
Location: <path-to-kubeflow-fairing>
Requires: notebook, future, docker, tornado, cloudpickle, oauth2client, numpy, requests, setuptools, httplib2, google-auth, google-api-python-client, urllib3, boto3, azure, six, kubernetes, google-cloud-storage

Docker setup

Kubeflow Fairing uses Docker to package your code. Run the following command to verify if Docker is installed and running:

docker ps

If you receive the docker: command not found message, install Docker.
If you receive the Error response from daemon: Bad response from Docker engine message, restart your docker daemon.
If you are using Linux and you use sudo to access Docker, follow these steps to add your user to the docker group. Note, the docker group grants privileges equivalent to the root user. To learn more about how this affects security in your system, see the guide to the Docker daemon attack surface.

Configure Kubeflow Fairing

To configure Kubeflow Fairing with access to an environment that you would like to use for training and deployment, follow the instructions in the guide to configuring Kubeflow Fairing.

Set up Kubeflow Fairing in a hosted Jupyter notebook

Follow these instructions to set up Kubeflow Fairing in a hosted Jupyter notebook.

If you are using a Kubeflow notebook server that was built from one of the standard Jupyter Docker images, your notebooks environment has been preconfigured for training and deploying ML models with Kubeflow Fairing and no additional installation steps are required.

Prerequisites

Check the following prerequisites to verify that Kubeflow Fairing is compatible with your hosted notebook environment.

In the Jupyter notebooks user interface, click File > New > Terminal in the menu to start a new terminal session in your notebook environment.
You need Python 3.6 or later to use Kubeflow Fairing. To check if you have Python 3.6 or later installed, run the following command in your terminal session:
```
python3 -V
```
The response should be something like this:
```
Python 3.6.5
```
Kubeflow Fairing uses Docker to package your code. Run the following command in your terminal session to verify if Docker is installed and running in your notebook environment:
```
docker ps
```
- If you receive the docker: command not found message, install Docker.
- If you receive the Error response from daemon: Bad response from Docker engine message, restart your docker daemon.
- If you are using Linux and you use sudo to access Docker, follow these steps to add your user to the docker group. Note, the docker group grants privileges equivalent to the root user. To learn more about how this affects security in your system, see the guide to the Docker daemon attack surface.

Install Kubeflow Fairing

In the Jupyter notebooks user interface, click File > New > Terminal in the menu to start a new terminal session in your notebook environment.

Run the following command to install Kubeflow Fairing.

pip3 install kubeflow-fairing

After successful installation, the fairing python package should be available. Run the following command to verify that Kubeflow Fairing is installed:

pip3 show kubeflow-fairing

The response should be something like this:

Name: kubeflow-fairing
Version: 0.6.0
Summary: Kubeflow Fairing Python SDK.
Home-page: https://github.com/kubeflow/fairing
Author: Kubeflow Authors
Author-email: hejinchi@cn.ibm.com
License: Apache License Version 2.0
Location: <path-to-kubeflow-fairing>
Requires: notebook, future, docker, tornado, cloudpickle, oauth2client, numpy, requests, setuptools, httplib2, google-auth, google-api-python-client, urllib3, boto3, azure, six, kubernetes, google-cloud-storage

Configure Kubeflow Fairing

To configure Kubeflow Fairing with access to the environment you would like to use for training and deployment, follow the instructions in the guide to configuring Kubeflow Fairing.

Next steps

Configure your Kubeflow Fairing development environment with access to run training jobs remotely.
Follow the samples and tutorials to learn more about how to run training jobs remotely with Kubeflow Fairing.

Docs: Configure Kubeflow Fairing

Mon, 01 Jan 0001 00:00:00 +0000

Out of date

This guide contains outdated information pertaining to Kubeflow 1.0. This guide needs to be updated for Kubeflow 1.1.

In order to use Kubeflow Fairing to train or deploy a machine learning model on Kubeflow, you must configure your development environment with access to your container image registry and your Kubeflow cluster. This guide describes how to configure Kubeflow Fairing to run training jobs on Kubeflow.

Additional configuration steps are required to access Kubeflow when it is hosted on a cloud environment. Use the following guides to configure Kubeflow Fairing with access to your hosted Kubeflow environment.

To use Kubeflow Fairing to train and deploy on Kubeflow on Google Kubernetes Engine, follow the guide to configuring Kubeflow Fairing with access to Google Cloud Platform.

Prerequisites

Before you configure Kubeflow Fairing, you must have a Kubeflow environment and Kubeflow Fairing installed in your development environment.

If you do not have a Kubeflow cluster, follow the getting started with Kubeflow guide to set one up.
If you have not installed Kubeflow Fairing, follow the installing Kubeflow Fairing guide.

Using Kubeflow Fairing with Kubeflow notebooks

The standard Kubeflow notebook images include Kubeflow Fairing and come preconfigured to run training jobs on your Kubeflow cluster. No additional configuration is required.

If you built your Kubeflow notebook server from a custom Jupyter Docker image, follow the instruction in this guide to configure your notebooks environment with access to your Kubeflow environment.

Configure Docker with access to your container image registry

Authorize Docker to access your container image registry by following the instructions in the docker login reference guide.

Configure access to your Kubeflow cluster

Use the following instructions to configure kubeconfig with access to your Kubeflow cluster.

Kubeflow Fairing uses kubeconfig to access your Kubeflow cluster. This guide uses kubectl to set up your kubeconfig. To check if you have kubectl installed, run the following command:
```
which kubectl
```
The response should be something like this:
```
/usr/bin/kubectl
```
If you do not have kubectl installed, follow the instructions in the guide to installing and setting up kubectl.
Follow the guide to configuring access to Kubernetes clusters, to update your kubeconfig with appropriate credentials and endpoint information to access your Kubeflow cluster.

Next steps

Follow the samples and tutorials to learn more about how to run training jobs remotely with Kubeflow Fairing.

Docs: Fairing on Azure

Mon, 01 Jan 0001 00:00:00 +0000

This page documents how to run the Fairing prediction example notebook on Azure Kubernetes Service (AKS) in a notebook hosted on Kubeflow.

Prerequisites

Before you configure and use the Kubeflow Fairing Python SDK, you must have a Kubeflow environment installed. The example notebook does in-cluster training. The example notebook has been tested to work in a cluster with 2 nodes and virtual machines with Standard_D4_v3 size. It is not recommended to use the smallest size virtual machines.

If you do not have a Kubeflow installation on Azure, follow the installation guide.
You must have the kubectl command line interface installed and configured to use the Kubernetes cluster where Kubeflow is installed. In the above installation guide, the command az aks get-credentials configures kubectl to access your Kubernetes cluster.

Create Azure Container Registry and Storage

The example notebook uses Azure Container Registry (ACR) to host docker images for deployment and Azure Storage (Storage) is used as build context for in-cluster building.

You can re-use existing ACR and Storage resources or create new ones. For more information, see the documentation for ACR and Storage.

After you have created your ACR and Storage resources, you must configure a service principal with access to these resources.

You can create a new service principal with the following command:

az ad sp create-for-rbac --name <name>

The above command has output like this:

{
  "appId": "<client-id>",
  "displayName": "<name>",
  "name": "http://<name>",
  "password": "<client-secret>",
  "tenant": "<tenant-id>"
}

The role you grant must have at least read and write permissions to ACR and Storage. We recommend using the AcrPush role and the Storage Account Contributor role scoped to a resource group.

You can perform the role assignment for ACR like this:

az role assignment create --assignee <id> \
  --scope /subscriptions/<azure-subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ContainerRegistry/registries/<acr-name> \
  --role "AcrPush"

You can grant full storage rights at a resource group level like this:

az role assignment create --assignee <id> \
  --scope /subscriptions/<azure-subscription-id>/resourceGroups/<resource-group-name> \
  --role "Storage Account Contributor"

To learn more about how to grant the service principal access, follow the Azure role-based authentication documentation.

Setting up credentials as Kubernetes secrets

Before running the notebook, you must first configure credentials so that the Python code running within the cluster can access the Azure resources required to train and deploy a model.

Run the following commands to set up your credentials as a Kubernetes secret.

Set environment variables to use in the following commands.
```
export AZ_CLIENT_ID=<service-principal-client-id>
export AZ_CLIENT_SECRET=<service-principal-client-secret>
export AZ_TENANT_ID=<tenant-id>
export AZ_SUBSCRIPTION_ID=<subscription-id>
export TARGET_NAMESPACE=<target-namespace e.g. kubeflow-anonymous>
export ACR_NAME=<acr-name>
```
- AZ_CLIENT_ID: The service principal client ID. You can get the client_id property from ~/.azure/aksServicePrincipal.json.
- AZ_CLIENT_SECRET: The service principal secret.
- AZ_TENANT_ID: The Azure Tenant ID of your account. You can get the Tenant ID from the tenantId field in the output of az account show.
- AZ_SUBSCRIPTION: The Azure Subscription ID of your account. You can get the Subscription ID from the id field in the output of az account show.
- TARGET_NAMESPACE: Specify the namespace that your Notebook Server is in. For example, this guide recommends using kubeflow-anonymous.
- ACR_NAME: The name of an ACR that the service principal can access.

Use the following command to create a secret that Kubeflow can use to access Azure APIs.

kubectl create secret generic -n ${TARGET_NAMESPACE} azcreds \
--from-literal=AZ_CLIENT_ID=${AZ_CLIENT_ID} \
--from-literal=AZ_CLIENT_SECRET=${AZ_CLIENT_SECRET} \
--from-literal=AZ_TENANT_ID=${AZ_TENANT_ID} \
--from-literal=AZ_SUBSCRIPTION_ID=${AZ_SUBSCRIPTION_ID}

Use the following command to create a secret that Kubeflow can use to access ACR.

kubectl create secret docker-registry -n ${TARGET_NAMESPACE} acrcreds \
--docker-server=${ACR_NAME}.azurecr.io \
--docker-username=${AZ_CLIENT_ID} \
--docker-password=${AZ_CLIENT_SECRET}
kubectl patch serviceaccount default-editor -n ${TARGET_NAMESPACE} \
-p "{\"imagePullSecrets\": [{\"name\": \"acrcreds\"}]}"

Creating a Notebook Server in Kubeflow

To create a notebook server, use your Web browser to access the Kubeflow Central Dashboard and select the Notebook Servers panel from the menu.

First, select the target namespace in which you want to host the server. In the default Kubeflow installation, there should be a namespace kubeflow-anonymous available in the namespace drop-down menu.

After the target namespace is selected, click NEW SERVER and fill in the mandatory fields. The fields with default values can all be left as they are and do not have to be modified to run the example notebook.

After launching the server, wait for the CONNECT button to appear and click CONNECT to launch your Notebook Server. It may take up to a minute for the server to be ready for connections.

Cloning the example notebook

Clone the Kubeflow Fairing repository to download the files used in this example.

Connect to your notebook server, then click the new terminal option like in the screenshot below:
Run the following command to clone the Kubeflow Fairing project:
```
git clone https://github.com/kubeflow/fairing.git
```
This command clones the project including the example into your notebook server.

You can now close the terminal window, and you should now see the fairing folder in your notebooks server’s Files tab. Navigate to the example notebooks at fairing/examples/prediction/xgboost-high-level-apis.ipynb.

Executing the notebook

Before running the cells, read the following to learn how to configure Fairing to use your Azure resources.

In the xgboost-high-level-apis.ipynb notebook, find the cell tagged with parameters and update this cell to use Azure. Update following values to configure Fairing to use your Azure backend and Storage.

export FAIRING_BACKEND = 'KubeflowAzureBackend'
export DOCKER_REGISTRY = '<acr-name>.azurecr.io'
export AZURE_REGION = None # This is only relevant if you haven't created a
                           # Storage yet and let Fairing create it for you.
                           # In that case, you can specify the region as
                           # string, for example, 'NorthEurope'.
export AZURE_RESOURCE_GROUP = '<storage-resource-group>'
export AZURE_STORAGE_ACCOUNT = '<storage-name>'

After the above steps have been completed, you can run the example notebook.

You can also have a look at the CI pipeline that runs the example notebook in AKS for steps involved to accomplish a successful run programmatically.

Docs: Fairing on GCP

Mon, 01 Jan 0001 00:00:00 +0000

Docs: Tutorials

Mon, 01 Jan 0001 00:00:00 +0000

Docs: Reference

Mon, 01 Jan 0001 00:00:00 +0000