This project has retired. For details please refer to its Attic page.
Development Guide | Apache Submarine
Skip to main content
Version: 0.6.0

Development Guide

Project Overview

The document Getting Started/Quickstart shows how to deploy the Submarine service to your Kubernetes cluster. The Submarine service consists mainly of nine components, and you can check them with the following command:

kubectl get pods -n ${your_namespace}

A brief introduction about these components:

  1. tf-operator: Enable users to run TensorFlow jobs distributedly
  2. pytorch-operator: Enable users to run PyTorch jobs distributedly
  3. notebook-controller: Jupyter Notebook controller
  4. submarine-traefik: Kubernetes Ingress controller
  5. submarine-database: A MySQL database to store metadata
  6. submarine-minio: An object store for machine learning artifacts
  7. submarine-mlflow: A platform for model management
  8. submarine-tensorboard: A visualization tool for distributed training experiments
  9. submarine-server: Handle API requests, and submit distributed training experiments to Kubernetes.

Submarine Development

Video

  • From this Video, you will know how to deal with the configuration of Submarine and be able to contribute to it via Github.

Develop server

Prerequisites

  • JDK 1.8
  • Maven 3.3 or later ( < 3.8.1 )
  • Docker

Setting up checkstyle in IDE

Checkstyle plugin may help to detect violations directly from the IDE.

  1. Install Checkstyle+IDEA plugin from Preference -> Plugins
  2. Open Preference -> Tools -> Checkstyle ->
    1. Set Checkstyle version:
      • Checkstyle version: 8.0
    2. Add (+) a new Configuration File
      • Description: Submarine
      • Use a local checkstyle ${SUBMARINE_HOME}/dev-support/maven-config/checkstyle.xml
  3. Open the Checkstyle Tool Window, select the Submarine rule and execute the check

Testing

  • Unit Test

    For each class, there is a corresponding testClass. For example, SubmarineServerTest is used for testing SubmarineServer. Whenever you add a funtion in classes, you must write a unit test to test it.

  • Integration Test: IntegrationTestK8s.md

Build from source

  • Before building

    1. We assume the developer use minikube as a local kubernetes cluster.
    2. Make sure you have installed the submarine helm-chart in the cluster.
  1. Package the Submarine server into a new jar file

    mvn package -DskipTests
  2. Build the new server docker image in minikube

    # switch to minikube docker daemon to build image directly in minikube
    eval $(minikube docker-env)

    # run docker build
    ./dev-support/docker-images/submarine/build.sh

    # exit minikube docker daemon
    eval $(minikube docker-env -u)
  3. Update server pod

    helm upgrade --set submarine.server.dev=true submarine ./helm-charts/submarine

    Set submarine.server.dev to true, enabling the server pod to be launched with the new docker image.

Develop workbench

  1. Deploy the Submarine

    Follow Getting Started/Quickstart, and make sure you can connect to http://localhost:32080 in the browser.

  2. Install the dependencies

    cd submarine-workbench/workbench-web
    npm install
  3. Run the workbench based on proxy server

    npm run start
    1. The request sent to http://localhost:4200 will be redirected to http://localhost:32080.
    2. Open http://localhost:4200 in browser to see the real-time change of workbench.
  4. Frontend E2E test: IntegrationTestE2E.md

Develop database

  1. Build the docker image

    # switch to minikube docker daemon to build image directly in minikube
    eval $(minikube docker-env)

    # run docker build
    ./dev-support/docker-images/database/build.sh

    # exit minikube docker daemon
    eval $(minikube docker-env -u)
  2. Deploy new pods in the cluster

    helm upgrade --set submarine.database.dev=true submarine ./helm-charts/submarine

    Develop operator

  • Before building

    1. We assume the developer use minikube as a local kubernetes cluster.
    2. Make sure you have NOT installed the submarine helm-chart in the cluster.
  1. Start the minikube cluster

    minikube start --vm-driver=docker --kubernetes-version v1.15.11
  2. Install the dependencies

    cd submarine-cloud-v2/
    cp -r ../helm-charts/submarine/charts ./helm-charts/submarine-operator/
    go mod vendor
    helm install --set dev=true submarine-operator ./helm-charts/submarine-operator/
  3. Run the operator out-of-cluster

    make
    ./submarine-operator
  4. Deploy a Submarine

    kubectl apply -f artifacts/examples/crd.yaml
    kubectl create ns submarine-user-test
    kubectl apply -n submarine-user-test -f artifacts/examples/example-submarine.yaml
  5. Exposing service

    # Method1 -- use minikube ip
    minikube ip # you'll get the IP address of minikube, ex: 192.168.49.2

    # Method2 -- use port-forwarding
    kubectl port-forward --address 0.0.0.0 -n submarine-user-test service/traefik 32080:80
  6. View workbench

    If you use method 1 in step 5, please go to http://{minikube ip}:32080, ex: http://192.168.49.2:32080

    If you use method 2 in step 5, please go to http://127.0.0.1:32080

  7. Delete submarine

    kubectl delete submarine example-submarine -n submarine-user-test
  8. Stop the operator

    Press ctrl+c to stop the operator.

  9. Uninstall helm chart dependencies

    helm delete submarine-operator

For other details, please check out the README and Developer Guide on GitHub.

Develop Submarine Website

Submarine website is built using Docusaurus 2, a modern static website generator.

We store all the website content in markdown format in the submarine/website/docs. When committing a new patch to the submarine repo, Docusaurus will help us generate the html and javascript files and push them to https://github.com/apache/submarine-site/tree/asf-site.

To update the website, click “Edit this page” on the website.

Add a new page

If you want to add a new page to the website, make sure to add the file path to sidebars.js.

Installation

We use the yarn package manager to install all dependencies for the website

yarn install

Build

Make sure you can successfully build the website before creating a pull request.

yarn build

Local Development

This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.

yarn start