Update read-me. (#186)

Co-authored-by: Tatsinnit <tatsat.mishra@microsoft.com>
Co-authored-by: Peter Bomber <peter.bomber@microsoft.com>

README.md

@@ -10,6 +10,22 @@ Quick troubleshooting for your Azure Kubernetes Service (AKS) cluster.
 
 ![Icon](https://user-images.githubusercontent.com/33297523/69174241-4075a980-0ab6-11ea-9e33-76afc588e7fb.png)
 
+
+# Table of contents
+1. [Overview](#overview)
+2. [Data Privacy and Collection](#data-privacy-and-collection)
+3. [Compatibility](#compatibility)
+4. [Current Feature Set](#current-feature-set)
+5. [User Guide](#user-guide)
+   1. [Raw Kustomize](#kustomize-deployment)
+   2. [Azure CLI Kollect Command](#using-azure-command-line-tool)
+   3. [VS Code AKS Extension](#using-vs-code-aks-extension)
+6. [Programming Guide](#programming-guide)
+   1. [Automated Tests](#automated-tests)
+7. [Dependent Consuming Tools and Working Contract](#dependent-consuming-tools-and-working-contract)
+8. [Debugging Guide](#debugging-guide)
+9. [Contributing](#contributing)
+
 ## Overview
 
 Hopefully most of the time, your AKS cluster is running happily and healthy. However, when things do go wrong, AKS customers need a tool to help them diagnose and collect the logs necessary to troubleshoot the issue. It can be difficult to collect the appropriate node and pod logs to figure what's wrong, how to fix the problem, or even to pass on those logs to others to help.
@@ -46,12 +62,63 @@ Periscope collects the following logs and metrics:
 8. Kubelet command arguments.
 9. System performance (kubectl top nodes and kubectl top pods).
 
-It also generates the following diagnostic signals:
+## User Guide
+
+You can deploy Periscope to your cluster in different ways, depending on your preferred working environment and the degree of control over precisely how it needs to be run.
 
-1. Network outbound connectivity, reports the down period for a specific connection.
-2. Network configuration, includes Network Plugin, DNS, and Max Pods per Node settings.
+### Kustomize Deployment
 
-## User Guide
+This approach gives you the most control, allowing you to inspect and override the configuration of all Kubernetes resources deployed to your cluster, as well as choosing a specific release.
+
+The [`Kustomize`](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/) tool deploys resources defined in a directory containing a `kustomization.yaml` file. To deploy Periscope, a minimal file might look like this:
+
+```yaml
+resources:
+- https://github.com/azure/aks-periscope//deployment/base?ref=<RELEASE_TAG>
+
+images:
+- name: periscope-linux
+  newName: mcr.microsoft.com/aks/periscope
+  newTag: <IMAGE_TAG>
+- name: periscope-windows
+  newName: mcr.microsoft.com/aks/periscope-win
+  newTag: <IMAGE_TAG>
+
+secretGenerator:
+- name: azureblob-secret
+  behavior: replace
+  literals:
+  - AZURE_BLOB_ACCOUNT_NAME=<STORAGE_ACCOUNT_NAME>
+  - AZURE_BLOB_CONTAINER_NAME=<CONTAINER_NAME>
+  - AZURE_BLOB_SAS_KEY=<SAS_KEY>
+
+# Uncomment for optional configuration (default values shown)
+# configMapGenerator:
+# - name: diagnostic-config
+#   behavior: replace
+#   literals:
+#   - DIAGNOSTIC_CONTAINERLOGS_LIST=kube-system # space-separated namespaces
+#   - DIAGNOSTIC_KUBEOBJECTS_LIST=kube-system/pod kube-system/service kube-system/deployment # space-separated namespace/kind pairs
+#   - DIAGNOSTIC_NODELOGS_LIST_LINUX="/var/log/azure/cluster-provision.log /var/log/cloud-init.log" # space-separated log file locations
+#   - DIAGNOSTIC_NODELOGS_LIST_WINDOWS="C:\AzureData\CustomDataSetupScript.log" # space-separated log file locations
+```
+
+All placeholders in angled brackets (`<`/`>`) need to be substituted for the relevant values:
+- `RELEASE_TAG`: The [Periscope release](https://github.com/Azure/aks-periscope/tags) to use.
+- `IMAGE_TAG`: The [Docker image tag](https://mcr.microsoft.com/en-us/product/aks/periscope/tags) to use.
+- `STORAGE_ACCOUNT_NAME`: The Azure storage account for Periscope to upload diagnostics to.
+- `CONTAINER_NAME`: The blob container within the storage account for Periscope to upload diagnostics to.
+- `SAS_KEY`: An [Account SAS](https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview#account-sas) including preceding `?` with [parameters](https://docs.microsoft.com/en-us/rest/api/storageservices/create-account-sas#specify-the-account-sas-parameters):
+  - `ss`: `b` (Service: blob)
+  - `srt`: `sco` (Resource types: service, container and object)
+  - `sp`: `rlacwd` (Permissions: read, list, add, create, write, delete)
+
+You can then deploy Periscope by running:
+```sh
+kubectl apply -k <path-to-kustomize-directory>
+```
+
+### Using Azure Command-Line tool
 
 AKS Periscope can be deployed by using Azure Command-Line tool (CLI). The steps are:
 
@@ -123,22 +190,20 @@ AKS Periscope can be deployed by using Azure Command-Line tool (CLI). The steps
       --node-logs "/var/log/azure-vnet.log /var/log/azure-vnet-ipam.log"
       ```
 
-All collected logs, metrics and node level diagnostic information is stored on host nodes under directory:  
-> `/var/log/aks-periscope`.
+After export, they will also be stored in Azure Blob Storage in a container named with the cluster's API Server FQDN. A zip file is also created for easy download.
 
-This directory is also mounted to container as:  
-> `/aks-periscope`.
+### Using VS Code AKS Extension
 
-After export, they will also be stored in Azure Blob Storage in a container named with the cluster's API Server FQDN. A zip file is also created for easy download.
+AKS Periscope can also be deployed by using the [VS Code AKS extension](https://marketplace.visualstudio.com/items?itemName=ms-kubernetes-tools.vscode-aks-tools).
 
-Alternatively, AKS Periscope can be deployed directly with `kubectl`. See instructions in [Appendix].
+You first need to configure your cluster's diagnostic settings to use a storage account [as explained here](https://github.com/Azure/vscode-aks-tools#configuring-storage-account). You can then right-click on the cluster and select `Run AKS Periscope` to run the tool and upload the result. The results can be downloaded directly from VS Code. For more detail how this feature works [please refer here](https://github.com/Azure/vscode-aks-tools#aks-periscope).
 
 ## Programming Guide
 
 To locally build this project from the root of this repository:
 
 ```sh
-CGO_ENABLED=0 GOOS=linux go build -mod=vendor github.com/Azure/aks-periscope/cmd/aks-periscope
+CGO_ENABLED=0 GOOS=linux go build -mod=mod github.com/Azure/aks-periscope/cmd/aks-periscope
 ```
 
 ### Automated Tests