docs: Design documents for rollback functionality (#170)

Resolves [AB#325]

Author: tbarlow12

docs/DEPLOY.md

@@ -1,4 +1,4 @@
-# Overview
+# Deploy Overview
 
 Deploy usage guide and design decision.
 
@@ -56,3 +56,64 @@ then user try to deploy
 
 1. always using the right resource group
 1. restrictive for user who have already defined their resources
+
+## Deployment Methodologies
+
+#### 1. Deployment to Function App (rollback disabled)
+- Deploy resource group, upload packaged artifact directly to function app. Sets function app `RUN_FROM_PACKAGE` setting to `1`.
+
+#### 2. Deployment to Blob Storage (rollback enabled)
+- Deploy resource group, upload packaged function app to blob storage with version name. Sets function app `RUN_FROM_PACKAGE` setting to path of zipped artifact in blob storage
+- Default container name - `DEPLOYMENT_ARTIFACTS` (configurable in `serverless.yml`, see below)
+
+### Deployment configuration
+
+```yml
+service: my-app
+provider:
+  ...
+
+plugins:
+  - serverless-azure-functions
+
+package:
+  ...
+
+deploy:
+  # Rollback enabled, deploying to blob storage
+  # Default is true
+  # If false, deploys directly to function app
+  rollback: true
+  # Container in blob storage containing deployed packages
+  # Default is DEPLOYMENT_ARTIFACTS
+  container: MY_CONTAINER_NAME
+
+functions:
+  ...
+```
+
+If rollback is enabled, the name of the created package will include the UTC timestamp of its creation. This timestamp will also be included in the name of the Azure deployment so as to be able to link the two together. Both names will have `-t{timestamp}` appended to the end.
+
+##### Sequence diagram for deployment to blob storage
+
+```mermaid
+sequenceDiagram
+  participant s as Serverless CLI
+  participant r as Resource Group 
+  participant f as Function App
+  participant b as Blob Storage
+
+  note right of s: `sls deploy`
+  s ->> r: Create resource group
+  s ->> r: Deploy ARM template
+  r ->> f: Included in ARM template
+  r ->> b: Included in ARM template
+  note right of s: Zip code
+  s ->> b: Deploy zip code with name {appName}-v{version}.zip
+  s ->> f: Set package path in settings
+  note right of s: Log URLs 
+```
+
+##### Sub-Commands
+
+- `sls deploy list` - Logs list of deployments to configured resource group with relevant metadata (name, timestamp, etc.). Also logs versions of deployed function app code if available

docs/ROLLBACK.md

@@ -0,0 +1,55 @@
+# Rollback
+
+##### `sls rollback`
+- Description - Roll back deployment of Function App & Resource Group
+- Options:
+  - `-t` or `--timestamp` - Timestamp associated with version to target
+  - Use `sls deploy list` to discover timestamps
+  - Defaults to previous deployment
+- **Important to note that there is no option for rolling back an individual function. A function app is considered one unit and will be rolled back as such.**
+- In order to roll back your function app, make sure your `deploy.rollback` is either set to `true` or not specified (defaults to `true`). The container in Azure Blob Storage which contains the packaged code artifacts can also be specified, defaults to `DEPLOYMENT_ARTIFACTS` (see [deploy documentation](./DEPLOY.md))
+
+##### Example usage
+
+```bash
+# List all deployments to know the timestamp for rollback
+$ sls deploy list
+Serverless:
+-----------
+Name: myFunctionApp-t1561479533 
+Timestamp: 1561479533
+Datetime: 2019-06-25T16:18:53+00:00
+-----------
+Name: myFunctionApp-t1561479506
+Timestamp: 1561479506
+Datetime: 2019-06-25T16:18:26+00:00
+-----------
+Name: myFunctionApp-t1561479444
+Timestamp: 1561479444
+Datetime: 2019-06-25T16:17:24+00:00
+-----------
+
+$ sls rollback -t 1561479506
+```
+
+##### Sequence diagram for rollback
+
+```mermaid
+sequenceDiagram
+  participant s as Serverless CLI
+  participant r as Resource Group 
+  participant f as Function App
+  participant b as Blob Storage
+
+  note right of s: `sls rollback`
+  s ->> r: Request deployments
+  r ->> s: Return deployments
+  note right of s: Select deployment
+  s ->> r: Deploy ARM template
+  s ->> b: Request names of previously deployed artifacts
+  b ->> s: Return names
+  note right of s: Select artifact
+  s ->> r: Re-deploy template
+  s ->> f: Update RUN_FROM_PACKAGE path (could be done with above step)
+  note right of s: Log URLs
+```