deployment-details.txt

CloudFlow supports multi-cloud deployment and orchestration for web applications and
their dependent services. 

The deployment actions can be triggered using command line flags or by specifying
a yaml file containing information required for deployment.

Structure of yaml file:
-----------------------
The yaml file consists of three sections: application, services, cloud.
The cloud section is compulsory whereas application and services section
can be included depending on whether you want to deploy a service instance
or an application. Below is an example of yaml file containing all three sections.

application:
  type: python
  entry_point: application.py
  env_variables:
    MY_VAR1: VALUE1
    MY_VAR2: VALUE2
  app_variables:
    db_var: DB
    host_var: HOST
    user_var: USER
    password_var: PASSWORD
services:
  - service:
      type: mysql
cloud:
  type: google
  project_id: greetings-python
  user_email: cc1h499@gmail.com

a) application:
The application section is used to define details of the application that we want to deploy.
It contains following sub-sections: type, entry_point, env_variables, and app_variables.
The type and entry_point sections are compulsory. type represents type of the application
(whether the application is python or Java). entry_point represents the main file
of the application. For python applications this will be the file in which the main()
function is defined. The env_variables section defines key-value pairs. 
These will be set as environment variables at application runtime.
The app_variables section is used to represent specific variables that may be used
by an application to represent database connection. There are four app_variables
supported: db_var, host_var, user_var, and password_var. These should be used
to capture the names of the environment variables in your application
code corresponding to the specific functions represented by that variable.
For instance, in your application if you are reading database name from an environment
variable named DB, then you should capture this using the db_var app_variable.
Similarly, if you are reading database host name from environment variable named HOST
then you should capture this using host_var app_variable. At runtime, LME will set
appropriate values for this variables ensuring that your application gets injected
with appropriate values for these environment variables.
Note that env_variables and app_variables section serve different purpose
even though both are related to setting of environment variables at application runtime.
The env_variables defines both keys and values for the environment variables,
whereas app_variables captures only the names of predefined environment variables
used by the application. The values are set by LME by capturing the output from
appropriate cloud.

Q) When should one use env_variables section vs. app_variables section?
A) When an application needs MySQL instance, you have two options to deploy such an
   application. One option is to first provision a service instance and then deploy the application
   by providing service information as part of app deployment. Second option is to directly
   deploy application letting the platform deploy the service instance.
   env_variables section is useful if you have provisioned service instance and the service
   connection parameters are available to you. On the other hand, the app_variables section
   should be used if you want the platform to handle application deployments.

b) services:
The services section supports a list of services. Currently only one service is
supported though - mysql.

c) cloud:
The cloud section is used to capture specific details about the cloud on which service/application
is going to be deployed. The type sub-section is compulsory for the cloud section.
Other sub-sections depend on the type of the cloud.
If the target cloud is Google then you will have to provide two things -- project_id corresponding
to the project and email address of the user 
in whose context you are deploying the application.

Here are some examples of yaml file for different deployments.

1) Deploying MySQL service instance locally
--
services:
  - service:
      type: mysql
cloud:
  type: local
--

2) Deploying Cloud SQL service instance on Google cloud
--
services:
  - service:
      type: mysql
cloud:
  type: google
  project_id: greetings-python
  user_email: cc1h499@gmail.com
--

3) Deploying RDS instance on AWS cloud
--
services:
  - service:
      type: mysql
cloud:
  type: aws
  SECRET_ACCESS_KEY: secret-access-key
  ACCESS_KEY_ID: access-key-id
--

4) Deploying application on Google cloud with env_variables to 
   connect to an existing Cloud SQL instance:
--
application:
  type: python
  entry_point: application.py
  env_variables:
    DB: testdb
    HOST: 107.178.214.1
    USER: testuser
    PASSWORD: testpass123!@#
cloud:
  type: google
  project_id: greetings-python
  user_email: cc1h499@gmail.com
--

5) Deploying application on Google cloud along with a Cloud SQL instance,
   and using app_variables to connect the application to the Cloud SQL
   instance at runtime.
--
application:
  type: python
  entry_point: application.py
  app_variables:
    db_var: DB
    host_var: HOST
    user_var: USER
    password_var: PASSWORD
services:
  - service:
      type: mysql
cloud:
  type: google
  project_id: greetings-python
  user_email: cc1h499@gmail.com
--


Available commands:
--------------------
1) lme service provision --service-name <service-name>
2) lme service show --service-name <service-name>
3) lme app deploy
4) lme app show --app-name <app-name>
5) lme app show --deploy-id <deploy-id>
6) lme app show --cloud <cloud>


$ lme --help
usage: lme [--version] [-v | -q] [--log-file LOG_FILE] [-h] [--debug]

lme cli

optional arguments:
  --version            show program's version number and exit
  -v, --verbose        Increase verbosity of output. Can be repeated.
  -q, --quiet          Suppress output except warnings and errors.
  --log-file LOG_FILE  Specify a file to log output. Disabled by default.
  -h, --help           Show help message and exit.
  --debug              Show tracebacks on errors.

Commands:
  app deploy     Build and deploy application
  app show       Show application status
  complete       print bash completion command
  help           print detailed help for another command
  service provision  Deploy a service
  service show   Show a service

  
----
Additional Notes

Installing FirstMile (Manually):
---------------------------------
a) Install virtualenv (pip install virtualenv)
b) Create virtualenv (virtualenv test-firstmile)
c) Start virtualenv (source test-firstmile/bin/activate)
d) Install firstmile
   - git clone https://devdattakulkarni@bitbucket.org/devdattakulkarni/lme.git
   - cd lme
   - pip install -r requirements.txt
e) Start the server:
   - python cld.py
f) Install the FirstMile cli
   - Open a new terminal window and navigate to the directory where you cloned
     the lme repository. Go inside the "client" folder inside this directory
     and install the client.
   - cd client; sudo python setup.py install
     - This will install the FirstMile cli.
     - You can check the features of the FirstMile cli by using "cld --help"

      (virtenv) devdatta@devdatta-ThinkPad-T430:~/Code/lme/client$ cld app deploy --help
      usage: cld app deploy [-h] [--service-name SERVICE] [--cloud CLOUD]

      Build and deploy application

      optional arguments:
      -h, --help         show this help message and exit
      --service SERVICE  Name of the required service (e.g.: MySQL)
      --cloud CLOUD      Destination to deploy application (local, AWS, Google)

       (virtenv) devdatta@devdatta-ThinkPad-T430:~/Code/lme/client$ cld app show --help
       usage: cld app show [-h] [--deploy-id DEPLOYID]

       Show application status

       optional arguments:
       -h, --help            show this help message and exit
       --deploy-id DEPLOYID  Deployment ID/URL

Deploying applications:
------------------------
FirstMile supports deployments of applications and services (currently MySQL) to local Docker, Google, and AWS clouds.
The deployments are supported using command line flags. It is also possible to provide the required
deployment related inputs in a yaml file. Below we outline steps to deploy an application using command
line flags. For detailed discussion about various deployment options, please check
deployment-details.txt file.

Sample applications:
---------------------
Following sample applications are available in lme-examples repository
(https://devdattakulkarni@bitbucket.org/devdattakulkarni/lme-examples.git)
- hello-world
- greetings-python
- express-checkout

greetings-python and express-checkout applications depend on a MySQL database for their correct functioning.


1) Navigate to the application folder (say, greetings-python) and then run
      cld app deploy --service-name mysql --cloud local
   This will show output of following nature.

+------------------+-----------+--------+
|     App Name     | Deploy ID | Cloud  |
+------------------+-----------+--------+
| greetings-python |    1      | local  |
+------------------+-----------+--------+

2) Use the deploy-id to check the deployment status
      cld app show --deploy-id 1

+------------------+-----------+---------------------+--------+--------------------------------------------+
|     App Name     | Deploy ID |        Status       | Cloud  |                App URL                     |
+------------------+-----------+---------------------+--------+--------------------------------------------+
| greetings-python |    1      | DEPLOYMENT_COMPLETE | local  |  http://172.17.1.09:5000                   |
+------------------+-----------+---------------------+--------+--------------------------------------------+

3) You don't have to specify the "service" flag if an application does not need MySQL database for its functioning.
   The hello-world application is of this nature. You can deploy it simply by executing
   cld app deploy --cloud <local-docker|google|aws> command


Deploying through FirstMile UI (Under development):
---------------------------------------------
1) Start the UI
   - cd client; python lmeui.py
2) Create a deployment
   - Select the application by navigating to the application folder of the sample application (say, greetings-python)
   - Hit "Deploy"
3) Track the deployment
   - Hit "Track"


Details:
--------
- Deployment related artifacts are stored inside ".cld" folder inside your home directory (~/.cld/data/deployments)