SUBMARINE-576. Always return empty list when listing environments

docs/userdocs/k8s/api/environment.md

@@ -0,0 +1,227 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Environment API Reference
+
+> Note: The Environment API is in the alpha stage which is subjected to incompatible changes in
+> future releases.
+
+## Create Environment
+`POST /api/v1/environment`
+
+**Example Request**
+```sh
+curl -X POST -H "Content-Type: application/json" -d '
+{
+  "name": "my-submarine-env",
+  "dockerImage" : "continuumio/anaconda3",
+  "kernelSpec" : {
+    "name" : "team_default_python_3.7",
+    "channels" : ["defaults"],
+    "dependencies" : 
+      ["_ipyw_jlab_nb_ext_conf=0.1.0=py37_0",
+      "alabaster=0.7.12=py37_0",
+      "anaconda=2020.02=py37_0",
+      "anaconda-client=1.7.2=py37_0",
+      "anaconda-navigator=1.9.12=py37_0"]
+  }
+}
+' http://127.0.0.1/api/v1/environment
+```
+
+**Example Response:**
+```json
+{
+  "status": "OK",
+  "code": 200,
+  "result": {
+    "environmentId": "environment_1586156073228_0001",
+    "environmentSpec": {
+      "name": "my-submarine-env",
+      "dockerImage" : "continuumio/anaconda3",
+      "kernelSpec" : {
+        "name" : "team_default_python_3.7",
+        "channels" : ["defaults"],
+        "dependencies" : 
+          ["_ipyw_jlab_nb_ext_conf=0.1.0=py37_0",
+          "alabaster=0.7.12=py37_0",
+          "anaconda=2020.02=py37_0",
+          "anaconda-client=1.7.2=py37_0",
+          "anaconda-navigator=1.9.12=py37_0"]
+      }
+    }
+  }
+}
+```
+
+### List environment
+`GET /api/v1/environment`
+
+**Example Request:**
+```sh
+curl -X GET http://127.0.0.1/api/v1/environment
+```
+
+**Example Response:**
+```json
+{
+  "status": "OK",
+  "code": 200,
+  "result": [
+  {
+    "environmentId": "environment_1586156073228_0001",
+    "environmentSpec": {
+      "name": "my-submarine-env",
+      "dockerImage" : "continuumio/anaconda3",
+      "kernelSpec" : {
+        "name" : "team_default_python_3.7",
+        "channels" : ["defaults"],
+        "dependencies" : 
+          ["_ipyw_jlab_nb_ext_conf=0.1.0=py37_0",
+          "alabaster=0.7.12=py37_0",
+          "anaconda=2020.02=py37_0",
+          "anaconda-client=1.7.2=py37_0",
+          "anaconda-navigator=1.9.12=py37_0"]
+      }
+    }
+  },
+  {
+    "environmentId": "environment_1586156073228_0002",
+    "environmentSpec": {
+      "name": "my-submarine-env-2",
+      "dockerImage" : "continuumio/miniconda",
+      "kernelSpec" : {
+        "name" : "team_miniconda_python_3.7",
+        "channels" : ["defaults"],
+        "dependencies" : 
+          ["_ipyw_jlab_nb_ext_conf=0.1.0=py37_0"]
+      }
+    }
+  }
+  ]
+}
+```
+
+### Get environment
+`GET /api/v1/environment/{name}`
+
+**Example Request:**
+```sh
+curl -X GET http://127.0.0.1/api/v1/environment/my-submarine-env
+```
+
+**Example Response:**
+```json
+{
+  "status": "OK",
+  "code": 200,
+  "result": {
+    "environmentId": "environment_1586156073228_0001",
+    "environmentSpec": {
+      "name": "my-submarine-env",
+      "dockerImage" : "continuumio/anaconda3",
+      "kernelSpec" : {
+        "name" : "team_default_python_3.7",
+        "channels" : ["defaults"],
+        "dependencies" : 
+          ["_ipyw_jlab_nb_ext_conf=0.1.0=py37_0",
+          "alabaster=0.7.12=py37_0",
+          "anaconda=2020.02=py37_0",
+          "anaconda-client=1.7.2=py37_0",
+          "anaconda-navigator=1.9.12=py37_0"]
+      }
+    }
+  }
+}
+```
+
+### Patch environment
+`PATCH /api/v1/environment/{name}`
+
+**Example Request:**
+```sh
+curl -X PATCH -H "Content-Type: application/json" -d '
+{
+  "name": "my-submarine-env",
+  "dockerImage" : "continuumio/anaconda3",
+  "kernelSpec" : {
+    "name" : "team_default_python_3.7_updated",
+    "channels" : ["defaults"],
+    "dependencies" : 
+      ["_ipyw_jlab_nb_ext_conf=0.1.0=py37_0",
+      "alabaster=0.7.12=py37_0"]
+  }
+}
+' http://127.0.0.1/api/v1/environment/my-submarine-env
+```
+
+**Example Response:**
+```json
+{
+  "status": "OK",
+  "code": 200,
+  "success": true,
+  "result": {
+    "environmentId": "environment_1586156073228_0001",
+    "environmentSpec": {
+      "name": "my-submarine-env",
+      "dockerImage" : "continuumio/anaconda3",
+      "kernelSpec" : {
+        "name" : "team_default_python_3.7_updated",
+        "channels" : ["defaults"],
+        "dependencies" : 
+          ["_ipyw_jlab_nb_ext_conf=0.1.0=py37_0",
+          "alabaster=0.7.12=py37_0"]
+      }
+    }
+  }
+}
+```
+> dockerImage, "name" (of kernelSpec), "channels", "dependencies" etc can be updated using this API.
+"name" of EnvironmentSpec is not supported.
+
+### Delete environment
+`GET /api/v1/environment/{name}`
+
+**Example Request:**
+```sh
+curl -X DELETE http://127.0.0.1/api/v1/environment/my-submarine-env
+```
+
+**Example Response:**
+```json
+{
+  "status": "OK",
+  "code": 200,
+  "result": {
+    "environmentId": "environment_1586156073228_0001",
+    "environmentSpec": {
+      "name": "my-submarine-env",
+      "dockerImage" : "continuumio/anaconda3",
+      "kernelSpec" : {
+        "name" : "team_default_python_3.7_updated",
+        "channels" : ["defaults"],
+        "dependencies" : 
+          ["_ipyw_jlab_nb_ext_conf=0.1.0=py37_0",
+          "alabaster=0.7.12=py37_0"]
+      }
+    }
+  }
+}
+```

docs/userdocs/k8s/api/experiment.md

@@ -22,7 +22,7 @@ under the License.
 > Note: The Experiment API is in the alpha stage which is subjected to incompatible changes in
 > future releases.
 
-## Create Experiment
+## Create Experiment (Using Anonymous/Embedded Environment)
 `POST /api/v1/experiment`
 
 **Example Request**
@@ -58,39 +58,112 @@ curl -X POST -H "Content-Type: application/json" -d '
 **Example Response:**
 ```json
 {
-    "status": "OK",
-    "code": 200,
-    "result": {
-        "experimentId": "experiment_1586156073228_0001",
+  "status": "OK",
+  "code": 200,
+  "result": {
+    "experimentId": "experiment_1586156073228_0001",
+    "name": "tf-mnist-json",
+    "uid": "28e39dcd-77d4-11ea-8dbb-0242ac110003",
+    "status": "Accepted",
+    "acceptedTime": "2020-06-13T22:59:29.000+08:00",
+    "spec": {
+      "meta": {
         "name": "tf-mnist-json",
-        "uid": "28e39dcd-77d4-11ea-8dbb-0242ac110003",
-        "status": "Accepted",
-        "acceptedTime": "2020-06-13T22:59:29.000+08:00",
-        "spec": {
-            "meta": {
-                "name": "tf-mnist-json",
-                "namespace": "default",
-                "framework": "TensorFlow",
-                "cmd": "python /var/tf_mnist/mnist_with_summaries.py --log_dir=/train/log --learning_rate=0.01 --batch_size=150",
-                "envVars": {
-                    "ENV_1": "ENV1"
-                }
-            },
-            "environment": {
-                "image": "gcr.io/kubeflow-ci/tf-mnist-with-summaries:1.0"
-            },
-            "spec": {
-                "Ps": {
-                    "replicas": 1,
-                    "resources": "cpu=1,memory=512M"
-                },
-                "Worker": {
-                    "replicas": 1,
-                    "resources": "cpu=1,memory=512M"
-                }
-            }
+        "namespace": "default",
+        "framework": "TensorFlow",
+        "cmd": "python /var/tf_mnist/mnist_with_summaries.py --log_dir=/train/log --learning_rate=0.01 --batch_size=150",
+        "envVars": {
+          "ENV_1": "ENV1"
+        }
+      },
+      "environment": {
+        "image": "gcr.io/kubeflow-ci/tf-mnist-with-summaries:1.0"
+      },
+      "spec": {
+        "Ps": {
+          "replicas": 1,
+          "resources": "cpu=1,memory=512M"
+        },
+        "Worker": {
+          "replicas": 1,
+          "resources": "cpu=1,memory=512M"
+        }
+      }
+    }
+  }
+}
+```
+
+## Create Experiment (Using Pre-defined/Stored Environment)
+`POST /api/v1/experiment`
+
+**Example Request**
+```sh
+curl -X POST -H "Content-Type: application/json" -d '
+{
+  "meta": {
+    "name": "tf-mnist-json",
+    "namespace": "default",
+    "framework": "TensorFlow",
+    "cmd": "python /var/tf_mnist/mnist_with_summaries.py --log_dir=/train/log --learning_rate=0.01 --batch_size=150",
+    "envVars": {
+      "ENV_1": "ENV1"
+    }
+  },
+  "environment": {
+    "name": "my-submarine-env"
+  },
+  "spec": {
+    "Ps": {
+      "replicas": 1,
+      "resources": "cpu=1,memory=512M"
+    },
+    "Worker": {
+      "replicas": 1,
+      "resources": "cpu=1,memory=512M"
+    }
+  }
+}
+' http://127.0.0.1/api/v1/experiment
+```
+Above example assume environment "my-submarine-env" already exists in Submarine. Please refer Environment API Reference doc to Create/Update/Delete/List Environment REST API's
+
+**Example Response:**
+```json
+{
+  "status": "OK",
+  "code": 200,
+  "result": {
+    "experimentId": "experiment_1586156073228_0001",
+    "name": "tf-mnist-json",
+    "uid": "28e39dcd-77d4-11ea-8dbb-0242ac110003",
+    "status": "Accepted",
+    "acceptedTime": "2020-06-13T22:59:29.000+08:00",
+    "spec": {
+      "meta": {
+        "name": "tf-mnist-json",
+        "namespace": "default",
+        "framework": "TensorFlow",
+        "cmd": "python /var/tf_mnist/mnist_with_summaries.py --log_dir=/train/log --learning_rate=0.01 --batch_size=150",
+        "envVars": {
+          "ENV_1": "ENV1"
+        }
+      },
+      "environment": {
+        "name": "my-submarine-env"
+      },
+      "spec": {
+        "Ps": {
+          "replicas": 1,
+          "resources": "cpu=1,memory=512M"
+        },
+        "Worker": {
+          "replicas": 1,
+          "resources": "cpu=1,memory=512M"
         }
+      }
     }
+  }
 }
 ```
 

submarine-server/server-core/src/main/java/org/apache/submarine/server/environment/EnvironmentManager.java

@@ -204,7 +204,8 @@ public Environment getEnvironment(String name)
    */
   public List<Environment> listEnvironments(String status)
       throws SubmarineRuntimeException {
-    List<Environment> environmentList = new ArrayList<>();
+    List<Environment> environmentList =
+        new ArrayList<Environment>(cachedEnvironments.values());
     return environmentList;
   }
 

submarine-server/server-core/src/main/java/org/apache/submarine/server/rest/EnvironmentRestApi.java

@@ -48,7 +48,7 @@
  * Environment REST API v1. It can accept {@link EnvironmentSpec} to create a
  * environment.
  */
-@Path(RestConstants.V1 + "/" + RestConstants.ENVIRONMENTS)
+@Path(RestConstants.V1 + "/" + RestConstants.ENVIRONMENT)
 @Produces({MediaType.APPLICATION_JSON + "; " + RestConstants.CHARSET_UTF8})
 public class EnvironmentRestApi {
   private final EnvironmentManager environmentManager =