diff --git a/content/docs/azure/_index.md b/content/docs/azure/_index.md new file mode 100644 index 0000000000000000000000000000000000000000..8241b9a2a92d59c789f3eaf0cd0f7da3a6620890 --- /dev/null +++ b/content/docs/azure/_index.md @@ -0,0 +1,5 @@ ++++ +title = "Kubeflow on Azure" +description = "Running Kubeflow on Kubernetes Engine and Microsoft Azure" +weight = 50 ++++ diff --git a/content/docs/azure/deploy/_index.md b/content/docs/azure/deploy/_index.md new file mode 100644 index 0000000000000000000000000000000000000000..c14dd6f7fb05cb54a445a332c5d64f224da107a4 --- /dev/null +++ b/content/docs/azure/deploy/_index.md @@ -0,0 +1,6 @@ ++++ +title = "Deployment" +description = "Instructions for deploying Kubeflow on AWS" +weight = 4 ++++ + diff --git a/content/docs/azure/deploy/existing-cluster.md b/content/docs/azure/deploy/existing-cluster.md new file mode 100644 index 0000000000000000000000000000000000000000..e532a5f822a5cd8d9c93fcf873d6ea3e11d0aa96 --- /dev/null +++ b/content/docs/azure/deploy/existing-cluster.md @@ -0,0 +1,13 @@ ++++ +title = "Initial cluster setup for existing cluster" +description = "Set up a cluster if you already have one" +weight = 5 ++++ + +## Initial Setup for Existing Cluster + +Get the Kubeconfig file: + + az aks get-credentials --name --resource-group + +From here on, please see [Install Kubeflow](/docs/azure/deploy/install-kubeflow). \ No newline at end of file diff --git a/content/docs/azure/deploy/install-kubeflow.md b/content/docs/azure/deploy/install-kubeflow.md new file mode 100644 index 0000000000000000000000000000000000000000..70a6ea725b185081ceab77206a4eed4a6c6a20d8 --- /dev/null +++ b/content/docs/azure/deploy/install-kubeflow.md @@ -0,0 +1,132 @@ ++++ +title = "Install Kubeflow" +description = "Instructions for deploying Kubeflow with the shell" +weight = 4 ++++ + +This guide describes how to use the `kfctl` binary to +deploy Kubeflow on Azure. + +## Prerequisites + +- Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl-on-linux) +- Install and configure the [Azure Command Line Interface (Az)](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest) + - Configure it with ```az init``` + - Log in with ```az login``` +- Install ksonnet (in the process of being deprecated) + - Download the [binary](https://github.com/ksonnet/ksonnet/releases) for your OS and unpack +- (Optional) Install Docker + - For Windows and WSL: [Guide](https://nickjanetakis.com/blog/setting-up-docker-for-windows-and-wsl-to-work-flawlessly) + - For other OS: [Docker Desktop](https://hub.docker.com/?overlay=onboarding) + +You do not need to have an existing Azure Resource Group or Cluster for AKS (Azure Kubernetes Service). You can create a cluster in the deployment process. + +## Understanding the deployment process + +The deployment process is controlled by 4 different commands: + +* init - The initial one-time set up. +* generate - Creates the configuration files that define your various resources. +* apply - Creates or updates the resources. +* delete - Deletes the resources. + + +With the exception of init, all commands take an argument which describes the set of resources to apply the command to; this argument can be one of the following: + +- k8s - All Kubernetes resources. Such as Kubeflow packages and add-on packages like fluentd or istio. +- all - Both Azure (WIP) and Kubernetes resources. +- `${KFAPP} `- the name of a directory where you want Kubeflow configurations to be stored. This directory is created when you runkfctl init. If you want a custom deployment name, specify that name here. The value of this variable becomes the name of your deployment. The value of this variable cannot be greater than 25 characters. It must contain just the directory name, not the full path to the directory. The content of this directory is described in the next section. + +### App layout + +Your Kubeflow `app` directory contains the following files and directories: + +* **app.yaml** - Defines the configuration related to your Kubeflow deployment. + * These values are set when you run `kfctl init`. + * These values are snapshotted inside `app.yaml` to make your app self contained. +* **${KFAPP}/ks_app** - A directory that contains the [ksonnet](https://ksonnet.io/) application for Kubeflow. + * The directory is created when you run `kfctl generate k8s`. + * You can use ksonnet to customize Kubeflow. + + +If you experience any issues running these scripts, see the [troubleshooting guidance](/docs/aws/troubleshooting-azure) for more information. + +## Azure Setup + +### Login to Azure + az login +### Initial cluster setup for new cluster + +Create a resource group: + az group create --name --location + +Example variables: + +- RESOURCE_GROUP_NAME=KubeTest +- LOCATION=westus + +Create a specifically defined cluster: + + az aks create -g -n -s -c -l --generate-ssh-keys +Example variables: + +- NAME=KubeTestCluster +- AGENT_SIZE=Standard_D2_v2 +- AGENT_COUNT=3 +- Use the same resource group and name from the previous step + +## Kubeflow Installation +Run the following commands to set up and deploy Kubeflow. The code below includes an optional command to add the binary kfctl to your path. If you don’t add the binary to your path, you must use the full path to the ```kfctl``` binary each time you run it. + +1. Create user credentials. You only need to run this command once. + + az aks get-credentials --name --resource-group + +1. Run the following commands to download the latest binary from the Kubeflow releases page (link = https://github.com/kubeflow/kubeflow/releases/). + + wget + +1. Unpack the tar ball + + tar -xvf kfctl__.tar.gz + +1. Run the following commands to set up and deploy Kubeflow. The code below includes an optional command to add the binary kfctl to your path. If you don’t add the binary to your path, you must use the full path to the `kfctl` binary each time you run it. +``` +# The following command is optional, to make kfctl binary easier to use. +export PATH=$PATH: + +# Initialize a kubeflow app: +export KFAPP= (ensure this is lowercase) +kfctl init ${KFAPP} + +# Generate and deploy the app: +cd ${KFAPP} +kfctl generate all -V +kfctl apply k8s -V +``` +${KFAPP} - the name of a directory where you want Kubeflow configurations to be stored. This directory is created when you runkfctl init. If you want a custom deployment name, specify that name here. The value of this variable becomes the name of your deployment. The value of this variable cannot be greater than 25 characters. It must contain just the directory name, not the full path to the directory. The content of this directory is described in the next section. + +1. Check the resources deployed correctly in namespace `kubeflow` + + kubectl get all -n kubeflow + +1. Open Kubeflow Dashboard +You may choose to use a load balancer: +``` +kubectl get svc –n kubeflow +kubectl expose svc ambassador -n kubeflow --type LoadBalancer --name +kfctl apply k8s -V + + +# Find the external IP to access the dashboard: +kubectl get svc –n kubeflow +``` + +In our case, the external IP for our service named 'amb1' was 40.XX.XXX.XXX + +If you didn’t create a load balancer, please use port-forwarding to visit your cluster. Run the following command and visit localhost:8080. + + kubectl port-forward svc/ambassador -n kubeflow 8080:80 + + + diff --git a/content/docs/azure/deploy/uninstall-kubeflow.md b/content/docs/azure/deploy/uninstall-kubeflow.md new file mode 100644 index 0000000000000000000000000000000000000000..1ede07090f04248d7798837fa75c34fc12679c95 --- /dev/null +++ b/content/docs/azure/deploy/uninstall-kubeflow.md @@ -0,0 +1,15 @@ ++++ +title = "Uninstall Kubeflow" +description = "Instructions for uninstalling Kubeflow" +weight = 10 ++++ + +## Uninstall Kubeflow on your Azure AKS cluster. + +``` +# Go to KFAPP Directory +cd ${KUBEFLOW_SRC}/${KFAPP} + +# Remove Kubeflow +kfctl delete all +``` \ No newline at end of file diff --git a/content/docs/azure/troubleshooting-azure.md b/content/docs/azure/troubleshooting-azure.md new file mode 100644 index 0000000000000000000000000000000000000000..33c07bd8c57c48a7d0605c33eeebfabdb7d0eed6 --- /dev/null +++ b/content/docs/azure/troubleshooting-azure.md @@ -0,0 +1,20 @@ ++++ +title = "Troubleshooting Deployments on Azure AKS" +description = "Help diagnose and fix issues you may encounter in your Kubeflow deployment" +weight = 100 ++++ + +### Jupyter Notebook ‘is not a valid page’ when accessing notebook +Restarting the ambassador pods will often fix this issue: +`kubectl delete pods -l service=ambassador` + +### The client does not have authorization to perform action... +This is likely an issue with ensuring your subscriptions are correctly setup. To fix the issue, list your subscriptions and then change the active subscription. + +``` +#list subscription +az account list --output table + +#change the active subscription +az account set --subscription "My Demos" +``` \ No newline at end of file