Document and facilitate t-shirt size deployments

[SorraTheOrc]

In #29 and #32 we added the ability to configure the deployment of the elasticsearch VMs and O365 Plugins, There are also a number of other configuration options not currently exposed via the default azuredeploy.parameters.json file.

We need to document these options clearly and provide some example "t-shirt size" configurations to guide users. That is, what configuration should be used for "5000 students", "10000 students", "25000 students' etc.

[SorraTheOrc]

I've added docs/Parameters.md, at present it contains a jq script for generating documentation from azuredeploy.md and a copy of the output from this script. Further work is underway in the docs branch and will be merged periodically.

[hosungsmsft]

This is partially addressed in the tshirt-sizing branch. More refinement/improvement should be done before releasing it to master.

[hosungsmsft]

Even though the tshirt-sizing branch merge added some tshirt-sizing recommendation into the master branch of the repo, it's still somewhat vague and the recommended SKU choices may be somewhat ambiguous. We'd like to have some more concrete recommendations (e.g., SKU types, number of VMSS instances, ...) for specific workloads and/or use cases. Eventually, it'd be desirable to provide some spreadsheet-like application that'll allow users to fill in some form characterizing use cases and/or workloads and generate recommended configurations (SKU types, VMSS instance count, HA option, DB size, ...).

[nimojg-microsoft]

@hosungsmsft two questions:

1. in terms of having a spreadsheet-like application - we might look at doing this in Excel using some of the new Excel api's or a Excel add-in

2. do we want to leverage things like the rate card api so that we also can help predict costs? or do we want to stop at providing the configuration?

[SorraTheOrc]

I think it is important to keep this very simple at this point. There is no need to use "new Excel api's" when a simple excel sheet would suffice. Similarly, integrating the rate card API would be interesting but I would see that as a stretch goal. Lets stay focused on doing a simple experiment now to see if it is even possible to build something useful.

Here's my suggestion:

1. Gather essential data about expected workload, e.g. a. # concurrent users b. Data HA or not c. Automated backup or not d. Moodle data storage requirements e. Azure search, Elastic search or not

2. Perform a “best match” against known load testing results

3. Suggest a spec that will match requirements a. Assert this is only an estimate and point user to the load test scripts so they can validate the recommendation

4. Point the user to the online cost calculator to estimate costs

In terms of implementation, whatever is easiest at this point. Lets consider this a PoC. If an Excel sheet is chosen then something like:

Sheet 1: Data input for the variables in point 1 (above) + a bunch of lookup formula for point 3 (above) Sheet 2: The data from recommendations and our load testing results

The lookup formula would be:

1. Match rows with nearest concurrent users match (rounding up) and highest performance metric
2. Filter rows based on the options chosen

This tool should be built in such a way that whenever we do more load testing we can add those results to the tool and gradually improve the lookups. However, we should not try to do anything beyond simple lookups unless someone on the team has appropriate experience.