Documentation updates for proposed Cobalt workflow (#244)

* changing the formatting setup of the readme and deleting the empty readme

* readjust the table of contents to move design towards the end

* some ideas for project main readme

* Refactor main project README.md to be smaller and reference other more granular README docs. Also added some high level template/module documentation.

* Adding in the main steps for the application developers - TODO adding in detailed instructions and UI images

* updating the getting started for app dev doc...Screenshots to be added

* updating the readme with the screenshots of the az devops portal steps

* Merged getting started documentation into a single feature branch to ensure coverage.

* update getting started doc

* update getting started doc

* update getting started doc

* Updates to docs; added preview feature notes and environment variable groups.

* update getting started doc

* update getting started doc

* update getting started doc

* Added initial cut of CLI version of app dev focused Getting Started

* update getting started doc

* update getting started doc

* update getting started doc

* update getting started doc

* update getting started doc

* Updated with CLI commands

* Fixed removal of unneeded pieces.

* update getting started doc

* update getting started doc

* update getting started doc

* update getting started doc

* update getting started doc

* update getting started doc

* update getting started doc

* update getting started doc

* update getting started doc

* update getting started doc

* update getting started doc

* update getting started doc

* update getting started doc

* update getting started doc

* update getting started doc

* Updates to CLI docs. Broke out steps into separate code blocks versus single code block.

* adding some minor changes to the app dev readme

* Moved getting started docs into new 'docs' directory.

* Updated links and resolved CLI docs comments.

* Update GETTING_STARTED_ADD_PAT_OWNER.md

* Update GETTING_STARTED_APP_DEV_CLI.md

* update getting started doc

README.md

@@ -1,92 +1,44 @@
+- [Cobalt](#cobalt)
+- [Getting Started](#getting-started)
+- [Relationship to Bedrock](#relationship-to-bedrock)
+- [Community](#community)
+- [Contributing](#contributing)
+
 # Cobalt
 
 [![Build Status](https://dev.azure.com/csedallascrew/project-cobalt/_apis/build/status/Microsoft.cobalt?branchName=master)](https://dev.azure.com/csedallascrew/project-cobalt/_build/latest?definitionId=2&branchName=master)
 [![Go Report Card](https://goreportcard.com/badge/github.com/microsoft/cobalt)](https://goreportcard.com/report/github.com/microsoft/cobalt)
 
-This project is an attempt to combine and share best practices when building production ready [cloud native](https://www.cncf.io/) managed service solutions. Cobalt's infrastructure turn-key starter [templates](/infra/templates/README.md) are based on real world engagements with enterprise customers.
+This project combines and shares best practices for building production ready [cloud native](https://www.cncf.io/) managed service solutions. Cobalt's infrastructure turn-key starter [templates](./infra/README.md) are based on real world engagements with enterprise customers.
 
-This project puts a focus on infrastructure scalability, security, automated testing and deployment repeatability and most importantly, developer experience. Cobalt's intended audience is for developers. Feedback and suggestions are encouraged through issue requests. We welcome contributions across any one of the major cloud providers.
+Cobalt puts a focus on infrastructure scalability, security, automated testing and deployment repeatability and most importantly, developer experience. The Project's intended audience is for developers. Feedback and suggestions are encouraged through issue requests. We welcome contributions across any one of the major cloud providers.
 
 Cobalt is a joint collaboration with project [Bedrock](https://github.com/Microsoft/bedrock).
 
-This project offers a set of continuous integration pipelines responsible for testing and deploying templated environments to cloud provider(s).
-
-## Infrastructure Setup: How it works
 
 ![image](https://user-images.githubusercontent.com/7635865/60480300-be8ffb80-9c4e-11e9-819a-221cea2cb93b.png)
 
-## How Cobalt differs from Bedrock
-
-Cobalt hosts reusable Terraform modules to scaffold managed container services like [ACI](https://docs.microsoft.com/en-us/azure/container-instances/) and [Application Services](https://docs.microsoft.com/en-us/azure/app-service/) as a couple of examples. Bedrock targets Kubernetes-based container orchestration workloads while following a [GitOps](https://medium.com/@timfpark/highly-effective-kubernetes-deployments-with-gitops-c7a0354f1446) devops flow. Cobalt templates reference Terraform modules like virtual networks, traffic manager, etc.
-
-## About the Repository
-
-### Infrastructure as Code
+# Getting Started
 
-Cobalt infrastructure templates are written in Terraform and can be found in the templates [folder](infra/templates). Each subfolder represents a unique deployment schema and is packaged with a set of Terraform scripts, overview and setup instructions and automated unit & integration tests.
+The steps for getting started depends on your high level goals. Select the correct set of instructions based on your overall use case for Cobalt.
 
-Each template makes use of Terraform [modules](https://www.terraform.io/docs/modules/index.html) across both Bedrock and [Cobalt](infra/modules). Cobalt's module registry is categorized by cloud provider then resource type. Each modules represents an abstraction for the set of related cloud infrastructure objects that the module will manage.
+- [Getting Started - Cobalt Developer](./docs/GETTING_STARTED_COBALT_DEV.md): Start here if you want to contribute to the Cobalt repository to create new advocated pattern templates or pipelines.
+- [Getting Started - Advocated Pattern Owner](./docs/GETTING_STARTED_ADD_PAT_OWNER.md): Start here if you want to maintain advocated pattern templates from Cobalt templates within your organization. Typically this will be the first step in leveraging Cobalt at your organization.
+- [Getting Started - Application Developer](./docs/GETTING_STARTED_APP_DEV_CLI.md): Start here if your organization already uses Cobalt and you want to deploy an advocated pattern to host your application.
 
-```bash
-$ tree infra
-├───modules
-│   └───providers
-│       ├───azure
-│       │   ├───api-mgmt
-│       │   ├───app-gateway
-│       │   ├───provider
-│       │   ├───service-plan
-│       │   ├───tm-endpoint-ip
-│       │   ├───tm-profile
-│       │   └───vnet
-│       └───common
-└───templates
-    ├───az-hello-world
-    │   └───test
-    │       └───integration
-    └───backend-state-setup
-```
 
-### Continuous Integration / Deployment + Testing
 
-Cobalt Continuous Integration pipeline definitions are available in the `./devops/provider` folder. As of today, Cobalt provides a git devops workflow [definition](devops/providers/azure-devops/templates/azure-pipelines.yml) for Azure DevOps. We welcome pipelines from other providers like Jenkins.
 
-#### Azure DevOps CI Flow
+# Relationship to Bedrock
 
-![image](./design-reference/devops/cobalt-devops-ci.gif)
-
-This pipeline is configured to trigger new builds for each new PR.
-
-1. Deployment credential secrets such as service principal and terraform remote state storage accounts are sourced in azure keyvault.
-2. The pipeline downloads secrets from keyvault and used to resolve terraform template variables.
-3. The test harness image will be re-built. This includes copying any changes to Terraform scripts and the associated Terraform tests.
-4. The test harness container will be run. It will perform the following stages.
-    * Run a lint check on all golang test files and terraform templates.
-    * Executes all golang unit tests.
-    * Generate and validate the terraform plan.
-    * Apply the terraform template resource updates to the development integration deployment environment.
-    * Run end-to-end integration tests.
-    * Tear down deployed resources.
-5. Update the build and PR status.
-6. Begin code review once the PR status is green.
-
-### Getting Started
-
-The easiest way to try Cobalt is to start with our [hello-world](https://github.com/Microsoft/cobalt/tree/master/infra/templates/az-hello-world) template.
-
-Setting up a cobalt deployment comprises of 5 general steps.
+Cobalt hosts reusable Terraform modules to scaffold managed container services like [ACI](https://docs.microsoft.com/en-us/azure/container-instances/) and [Application Services](https://docs.microsoft.com/en-us/azure/app-service/) as a couple of examples. Bedrock targets Kubernetes-based container orchestration workloads while following a [GitOps](https://medium.com/@timfpark/highly-effective-kubernetes-deployments-with-gitops-c7a0354f1446) devops flow. Cobalt templates reference Terraform modules like virtual networks, traffic manager, etc.
 
-1. You can follow these [instructions](devops/providers/azure-devops/README.md) to create an cloud-based CI pipeline definition.
-2. Our cloud deployment templates provide an configurable default setup intended for a t-shirt sized environment scenario. Pick the template folder most relevant to your use-case as a starting point. Each template folder is shipped with setup instructions.
-3. It's important to implement quality assurance that validates E2E functional assertions against your infrastructure resources. Each template comes pre-packaged with some basic integration and unit tests. We encourage you to define integration tests in the `test/integration` folder of your template that's specific to your use-case.
-4. Follow these [instructions](test-harness/README.md) to setup your local environment. Make sure that the repository lives in a directory that does not live within `$GOPATH`.
-5. Create a new local git branch and commit your changes. Run the test harness on your localhost via `./test-harness/local-run.sh`.
 
-## Community
+# Community
 
 [Please join us on Slack](https://publicslack.com/slacks/https-bedrockco-slack-com/invites/new) for discussion and/or questions.
 
-## Contributing
+# Contributing
 
 We do not claim to have all the answers and would greatly appreciate your ideas and pull requests.
 

devops/providers/azure-devops/README.md

@@ -1,21 +1,35 @@
-# CI/CD with Azure Devops
 
-![cobalt-ci-flow](https://user-images.githubusercontent.com/7635865/56059699-42aaa500-5d2a-11e9-8544-5236e7a9b2ef.png)
+- [Background Context](#background-context)
+- [Setup](#setup)
+  - [Prerequisites](#prerequisites)
+  - [CI/CD with Azure DevOps using the Azure DevOps CLI](#CI/CD-with-Azure-DevOps-using-the-Azure-DevOps-CLI)
+  - [CI/CD with Azure DevOps using the Azure DevOps UI](#CI/CD-with-Azure-DevOps-using-the-Azure-DevOps-UI)
+- [Design Motivation](#design-motivation)
+  - [CI/CD Flow](#ci/cd-flow)
+-[References](#references) 
 
+# Background Context 
 This section describes how to configure Azure Devops as the CI/CD system for your DevOPS Workflow.
 
-## Prerequisites
+# Setup 
+
+### Prerequisites
 
 1. _Permissions_: The ability to create Projects in your Azure DevOps Organization.
 2. Azure CLI installed on your [machine](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest).
 
-## Setup
-
-### Create a New Project in Azure DevOps using the CLI
+### CI/CD with Azure DevOps using the Azure DevOps CLI 
 
 ```bash
 az devops project create -n $PROJECT_NAME
 ```
+TODO
+
+### CI/CD with Azure DevOps using the Azure DevOps UI
+
+#### Create a new project
+
+TODO
 
 #### Create a Service Connection to Github
 
@@ -60,6 +74,13 @@ Setup the below variables to the build pipeline definition.
 - `TF_VAR_remote_state_account` - The terraform remote state storage account name.
 - `TF_VAR_remote_state_container` - The terraform remote state storage container name.
 
-### Reference
+# Design Motivation
+This section describes how to configure Azure Devops as the CI/CD system for your DevOPS Workflow.
+
+### CI/CD Flow
+
+![cobalt-ci-flow](https://user-images.githubusercontent.com/7635865/56059699-42aaa500-5d2a-11e9-8544-5236e7a9b2ef.png)
+
+# References
 
 - [Azure Pipelines](https://docs.microsoft.com/en-us/azure/devops/pipelines/get-started/what-is-azure-pipelines?toc=/azure/devops/pipelines/toc.json&bc=/azure/devops/boards/pipelines/breadcrumb/toc.json&view=azure-devops)