Merge pull request #9601 from jeroenterheerdt/master

Adding AppDeploy Concepts Page

Author: GitHubber17

docs/big-data-cluster/big-data-cluster-create-apps.md

@@ -44,7 +44,7 @@ In SQL Server 2019 (preview) CTP 2.4 you can create, delete, describe, initializ
 
 |Command |Description |
 |:---|:---|
-|`mssqlctl login` | Log into a SQL Server big data cluster |
+|`mssqlctl login` | Sign into a SQL Server big data cluster |
 |`mssqlctl app create` | Create application. |
 |`mssqlctl app delete` | Delete application. |
 |`mssqlctl app describe` | Describe application. |
@@ -61,9 +61,9 @@ mssqlctl app create --help
 
 The following sections describe these commands in more detail.
 
-## Log in
+## Sign in
 
-Before you deploy or interact with applications, first log in to your SQL Server big data cluster with the `mssqlctl login` command. Specify the external IP address of the `endpoint-service-proxy` service (for example: `https://ip-address:30777`) along with the user name and password to the cluster.
+Before you deploy or interact with applications, first sign in to your SQL Server big data cluster with the `mssqlctl login` command. Specify the external IP address of the `endpoint-service-proxy` service (for example: `https://ip-address:30777`) along with the user name and password to the cluster.
 
 ```bash
 mssqlctl login -e https://<ip-address-of-endpoint-service-proxy>:30777 -u <user-name> -p <password>
@@ -93,54 +93,50 @@ To create an application, you use `mssqlctl` with the `app create` command. Thes
 Use the following syntax to create a new app in big data cluster:
 
 ```bash
-mssqlctl app create -n <app_name> -v <version_number> --spec <directory containing spec file>
+mssqlctl app create --spec <directory containing spec file>
 ```
 
 The following command shows an example of what this command might look like:
 
-This assumes that you have file called `spec.yaml` within the `addpy` folder.
-The `addpy` folder contains the `add.py` and  `spec.yaml`
-The `spec.yaml` is a specification file for the `add.py` app.
+```bash
+mssqlctl app create --spec ./addpy
+```
 
+This assumes that you have your application stored in the `addpy` folder. This folder should also contain a specification file for the application, called called `spec.yaml`. Please see [the Application Deployment page](concept-application-deployment.md) for more information on the `spec.yaml` file.
 
-`add.py` creates the following python app:
+To deploy this app sample app, create the following files in a directory called `addpy`:
 
-```py
-#add.py
-def add(x,y):
+- `add.py`. Copy the following Python code into this file:
+   ```py
+   #add.py
+   def add(x,y):
         result = x+y
         return result
-result=add(x,y)
-```
-
-The following script is a sample of the contents for `spec.yaml`:
-
-```yaml
-#spec.yaml
-name: add-app #name of your python script
-version: v1  #version of the app
-runtime: Python #the language this app uses (R or Python)
-src: ./add.py #full path to the location of the app
-entrypoint: add #the function that will be called upon execution
-replicas: 1  #number of replicas needed
-poolsize: 1  #the pool size that you need your app to scale
-inputs:  #input parameters that the app expects and the type
-  x: int
-  y: int
-output: #output parameter the app expects and the type
-  result: int
-```
-
-To try this, copy the above lines of code into two files in the directory `addpy` as `add.py`  and `spec.yaml` and run the command below:
+    result=add(x,y)
+   ```
+- `spec.yaml`. Copy the following code into this file:
+   ```yaml
+   #spec.yaml
+   name: add-app #name of your python script
+   version: v1  #version of the app
+   runtime: Python #the language this app uses (R or Python)
+   src: ./add.py #full path to the location of the app
+   entrypoint: add #the function that will be called upon execution
+   replicas: 1  #number of replicas needed
+   poolsize: 1  #the pool size that you need your app to scale
+   inputs:  #input parameters that the app expects and the type
+     x: int
+     y: int
+   output: #output parameter the app expects and the type
+     result: int
+   ```
+
+Then, run the command below:
 
 ```bash
 mssqlctl app create --spec ./addpy
 ```
 
-> [!NOTE]
-> The `spec.yaml` file specifies both a `poolsize` and a number of `replicas`. The number of `replicas` specifies the number of copies of the service need to be deployed. The `poolsize` specifies the number of pools you want to create per replica. These settings have an impact on the amount of requests the deployment can handle in parallel. The maximum number of requests at one given time is equal to `replicas` times `poolsize`, i.e if you have 5 replicas and 2 pools per replica the deployment can handle 10 requests in parallel. See the image below for a graphical representation of `replicas` and `poolsize`:
-![Poolsize and replicas](media/big-data-cluster-create-apps/poolsize-vs-replicas.png)
-
 You can check if the app is deployed using the list command:
 
 ```bash

docs/big-data-cluster/concept-application-deployment.md

@@ -0,0 +1,68 @@
+---
+title: What is Application Deployment?
+titleSuffix: SQL Server 2019 big data clusters
+description: This article describes application deployment on a SQL Server 2019 big data cluster (preview).
+author: jterh 
+ms.author: jroth 
+manager: craigg
+ms.date: 03/26/2019
+ms.topic: conceptual
+ms.prod: sql
+ms.technology: big-data-cluster
+ms.custom: seodec18
+---
+
+# What is Application Deployment on a SQL Server 2019 big data cluster?
+
+Application Deployment enables the deployment of applications on the big data cluster by providing interfaces to create, manage, and run applications. Applications deployed on the big data cluster benefit from the computational power of the cluster and can access the data that is available on the cluster. This increases scalability and performance of the applications, while managing the applications where the data lives.
+The following sections describe the architecture and functionality of Application Deployment.
+
+## Application Deployment architecture
+
+Application deployment consists of a controller and app runtime handlers. When creating an application, a specification file (`spec.yaml`) is provided. This `spec.yaml` file contains everything the controller needs to know to successfully deploy the application. The following is a sample of the contents for `spec.yaml`:
+
+```yaml
+#spec.yaml
+name: add-app #name of your python script
+version: v1  #version of the app
+runtime: Python #the language this app uses (R or Python)
+src: ./add.py #full path to the location of the app
+entrypoint: add #the function that will be called upon execution
+replicas: 1  #number of replicas needed
+poolsize: 1  #the pool size that you need your app to scale
+inputs:  #input parameters that the app expects and the type
+  x: int
+  y: int
+output: #output parameter the app expects and the type
+  result: int
+```
+
+The controller inspects the `runtime` specified in the `spec.yaml` file and calls the corresponding runtime handler. The runtime handler creates the application. First, a Kubernetes ReplicaSet is created containing one or more pods, each of which contains the application to be deployed. The number of pods is defined by the `replicas` parameter set in the `spec.yaml` file for the application. Each pod can have one of more pools. The number of pools is defined by the `poolsize` parameter set in the `spec.yaml` file.
+
+These settings have an impact on the amount of requests the deployment can handle in parallel. The maximum number of requests at one given time is equals to `replicas` times `poolsize`. If you have 5 replicas and 2 pools per replica the deployment can handle 10 requests in parallel. See the image below for a graphical representation of `replicas` and `poolsize`:
+
+![Poolsize and replicas](media/big-data-cluster-create-apps/poolsize-vs-replicas.png)
+
+After the ReplicaSet has been created and the pods have started, a cron job is created if a `schedule` was set in the `spec.yaml` file. Finally, a Kubernetes Service is created that can be used to manage and run the application (see below).
+
+When an application is executed, the Kubernetes service for the application proxies the requests to a replica and returns the results.
+
+## How to work with Application Deployment
+
+The two main interfaces for Application Deployment are: 
+- [Command line interface `mssqlctl`](big-data-cluster-create-apps.md)
+- [Visual Studio Code and Azure Data Studio extension](app-deployment-extension.md)
+
+It is also possible for an application to be executed using a RESTful web service. For more information, see [Consume applications on big data clusters](big-data-cluster-consume-apps.md).
+
+## Next steps
+
+To learn more about how to create and run applications on SQL Server big data clusters, see the following:
+
+- [Deploy applications using mssqlctl](big-data-cluster-create-apps.md)
+- [Deploy applications using the App Deploy extension](app-deployment-extension.md)
+- [Consume applications on big data clusters](big-data-cluster-consume-apps.md)
+
+To learn more about the SQL Server big data clusters, see the following overview:
+
+- [What are SQL Server 2019 big data clusters?](big-data-cluster-overview.md)

docs/toc/toc.yml

@@ -79,6 +79,8 @@
         href: ../big-data-cluster/deploy-on-minikube.md
   - name: Concepts
     items:
+    - name: Application deployment
+      href: ../big-data-cluster/concept-application-deployment.md
     - name: Controller
       href: ../big-data-cluster/concept-controller.md
     - name: Master instance