🎊 Publish gh.io readme as a vscode documentation. (#213)

.github/workflows/website.yaml

@@ -0,0 +1,37 @@
+name: generate github pages
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - ".github/workflows/website.yaml"
+      - "docs/**"
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          submodules: true
+          fetch-depth: 0
+
+      - name: Set TOOLS_BIN_DIR and add to PATH
+        run: |
+          TOOLS_BIN_DIR="${HOME}/.cargo/bin"
+          echo "TOOLS_BIN_DIR=${TOOLS_BIN_DIR}" >> ${GITHUB_ENV}
+          echo "${TOOLS_BIN_DIR}" >> ${GITHUB_PATH}
+
+      - name: Build
+        run: make -C docs/book build
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.ref == 'refs/heads/master' }}
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/book/book

docs/book/.gitignore

@@ -0,0 +1 @@
+book

docs/book/Makefile

@@ -0,0 +1,26 @@
+TOOLS_BIN_DIR ?= $(PWD)/bin
+# include tools bin dir in path so that mdbook-toc can be run by mdbook
+PATH := ${PATH}:${TOOLS_BIN_DIR}
+MDBOOK_VERSION ?= v0.4.27
+# this version of mdbook-toc is built against mdbook 0.4.27
+MDBOOK_TOC_VERSION ?= 0.11.2
+MDBOOK_INSTALL := $(realpath ../../publish-book/install-mdbook.sh)
+MDBOOK_TOC_INSTALL := $(realpath ../../publish-book/install-mdbook-toc.sh)
+
+MDBOOK := $(TOOLS_BIN_DIR)/mdbook
+$(MDBOOK):
+	$(MDBOOK_INSTALL) ${MDBOOK_VERSION} ${TOOLS_BIN_DIR}
+
+MDBOOK_TOC := $(TOOLS_BIN_DIR)/mdbook-toc
+$(MDBOOK_TOC):
+	$(MDBOOK_TOC_INSTALL) ${MDBOOK_TOC_VERSION} ${TOOLS_BIN_DIR}
+
+DEPS := $(MDBOOK) $(MDBOOK_TOC)
+
+.PHONY: build
+build: $(DEPS)
+	$(MDBOOK) build
+
+.PHONY: serve
+serve: $(DEPS)
+	$(MDBOOK) serve

docs/book/book.toml

@@ -0,0 +1,14 @@
+[book]
+authors = ["Tatsat Mishra"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Visual Studio Code AKS Tools"
+description = "Display Azure Kubernetes Services within VS Code"
+
+[preprocessor.toc]
+command = "mdbook-toc"
+
+[output.html]
+curly-quotes = true
+git-repository-url = "https://github.com/Azure/vscode-aks-tools"

docs/book/src/README.md

@@ -0,0 +1,28 @@
+# Visual Studio Code AKS Tools
+
+## Introduction
+
+Azure Kubernetes Service (AKS) Extension for Visual Studio Code helps enable AKS developers with one-click quick to deploy features with in vscode eco-system.
+
+## Features
+
+* [Add AKS clusters to kubeconfig](./features/merge-save-kubeconfig.md)
+* [Perform AKS Diagnostics checks on your AKS cluster](./features/aks-diagnostics.md)
+* [Run AKS Periscope within VS Code](./features/aks-periscope.md)
+* [Install Azure Service Operator on your AKS cluster](./features/install-azureserviceoperator.md)
+* [Create GitHub Workflow from your AKS cluster](./features/create-gh-workflow.md)
+* [Show AKS cluster overview in Azure Portal](./features/show-properties-azureportal-start-stop.md)
+* [Show AKS cluster properties](./features/show-properties-azureportal-start-stop.md)
+* [Create AKS cluster from Azure Portal](./features/show-properties-azureportal-start-stop.md)
+* [Stop and Start the AKS cluster](./features/show-properties-azureportal-start-stop.md)
+* [Run Kubectl Commands from your AKS cluster](./features/run-kubectl-command.md)
+* [Run Managed Cluster Operations from your AKS cluster](./features/manage-cluster-operations.md)
+* [Run Kubernetes API Health Endpoints](./features/k8s-api-health-points.md)
+* [Deploy and Undeploy InspektorGadget](./features/inspektor-gadget.md)
+* [Enable Non-Interactive InspektorGadget Commands like Top, Profile and Snapshot](./features/inspektor-gadget.md)
+
+## Development and Release
+
+* [How to release](./release/releasing.md)
+* [Development](./development/development.md)
+* [Webview Development](./development/webview-development.md)

docs/book/src/SUMMARY.md

@@ -0,0 +1,26 @@
+# Summary
+
+- [Introduction](./README.md)
+- [Installation / Quick Start](./installation.md)
+- [Development](./development.md)
+  - [Development](./development/development.md)
+  - [Webview Settings](./development/webview-development.md)
+- [Features](./features/features.md)
+  - [Add AKS clusters to kubeconfig](./features/merge-save-kubeconfig.md)
+  - [Perform AKS Diagnostics checks on your AKS cluster](./features/aks-diagnostics.md)
+  - [Run AKS Periscope within VS Code](./features/aks-periscope.md)
+  - [Install Azure Service Operator on your AKS cluster](./features/install-azureserviceoperator.md)
+  - [Create GitHub Workflow from your AKS cluster](./features/create-gh-workflow.md)
+  - [Show AKS cluster overview in Azure Portal](./features/show-properties-azureportal-start-stop.md)
+  - [Show AKS cluster properties](./features/show-properties-azureportal-start-stop.md)
+  - [Create AKS cluster from Azure Portal](./features/show-properties-azureportal-start-stop.md)
+  - [Stop and Start the AKS cluster](./features/show-properties-azureportal-start-stop.md)
+  - [Run Kubectl Commands from your AKS cluster](./features/run-kubectl-command.md)
+  - [Run Managed Cluster Operations from your AKS cluster](./features/manage-cluster-operations.md)
+  - [Run Kubernetes API Health Endpoints](./features/k8s-api-health-points.md)
+  - [Deploy and Undeploy InspektorGadget](./features/inspektor-gadget.md)
+  - [Enable Non-Interactive InspektorGadget Commands like Top, Profile and Snapshot](./features/inspektor-gadget.md)
+- [Release](./release.md)
+  - [Releasing Information](./release/releasing.md)
+- [Contributing](./contributing.md)
+- [Telemetery](./telemetery.md)

docs/book/src/contributing.md

@@ -0,0 +1,15 @@
+# Contributing
+
+## Contributing
+
+This project welcomes contributions and suggestions.  Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.microsoft.com.
+
+When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [[email protected]](mailto:[email protected]) with any additional questions or comments.

docs/book/src/development/development.md

@@ -0,0 +1,25 @@
+# Package Scripts
+
+This gives an overview of the `npm` scripts available for development and release of the extension. See the `scripts` block in [package.json](../package.json).
+
+These can all be run from the command line in the root of the repository (with `npm` installed), using `npm run {script-name}`.
+
+## Environment Initialization
+
+- `install:all`: Installs `npm` dependencies for both the main extension project and the `webview-ui` sub-project. It's recommended to use this instead of `npm install`, which will only install dependencies for the main project.
+
+## Development and Testing
+
+- [`dev-webview`](./webview-development.md#developing-the-ui): for concurrent development/debugging of webview UX.
+- `build-webview`: bundles and minifies the webview UX for consumption by the extension.
+- `webpack`: builds and packages the extension.
+- `test`: runs automated tests.
+
+## Not for Running Directly
+
+Some scripts are invoked by other scripts or tools, so need not be run directly, or are otherwise not required for general development tasks:
+
+- `vscode:prepublish`: used by the `vsce` command for packaging the extension into a `vsix` file for distribution.
+- `webpack-dev`: bundles the extension code in development mode. Since we currently have no conditional logic that depends on whether the extension is running in development or production, this may be redundant.
+- `test-compile`: compiles the extension typescript (after building the `webview-ui` project) without webpacking it. This is a prerequisite to running automated tests. It _could_ be moved into `test`, but keeping it separate would allow it to be used in the future as a prelaunch task for debugging the extension without webpacking it.
+- `watch`: not currently used as part of any workflow I'm aware of, but could potentially be useful for editing while debugging.

docs/book/src/development/webview-development.md

@@ -0,0 +1,35 @@
+# Webview Development
+
+For commands that require a webview (see [guidance](https://code.visualstudio.com/api/extension-guides/webview#should-i-use-a-webview) on where this is appropriate), the [`webview-ui`](../webview-ui/) project provides the necessary tooling to develop the front end.
+
+## Initial Setup
+
+Run `npm run install:all` to install package dependencies for both the extension and webview project.
+
+## Development/Debugging
+
+### File structure
+
+- Webview source files are under `/webview-ui/src`.
+- When built, bundled/minified webview assets are output to `/webview-ui/dist`.
+
+When the extension is run (both in development and production), the webview assets are read from `/webview-ui/dist`.
+
+### Developing the UI
+
+If you like to use your browser development tools for debugging, or you wish to open the web application in an existing browser window:
+1. Run `npm run dev:webview` to start the development server.
+2. Navigate to `http://localhost:3000` in your browser.
+
+Alternatively, if you are developing in VS Code and wish to use the inbuilt debugging functionality:
+1. Hit `F5` to launch the `Webview UI` debug profile in a new browser window. This will automatically run the development server and attach a debugger.
+
+### Developing the VS Code commands that launch the UI
+
+To debug the extension itself, hit `F5` to launch the `Extension` debug profile in a new VS Code Window. This will automatically build, bundle and minify both the `webview-ui` project and the extension.
+
+The extension will not automatically update itself in response to code changes as you are debugging, so the best workflow here is to stop debugging, make changes, and launch the debugger again.
+
+## Building for release
+
+The process for this is unaffected by the webview setup. The `npm run webpack` and `vsce package` commands will ensure the `webpack-ui` project is built and bundled.

docs/book/src/features/aks-diagnostics.md

@@ -0,0 +1,16 @@
+# AKS Diagnostics
+
+### AKS Diagnostics
+
+Right click on your AKS cluster and click on **Run AKS Diagnostics** to display diagnostics information based on your AKS cluster's backend telemetry for:
+
+- Best Practices
+- Create, Upgrade, Delete and Scale issues
+- Identity and Security
+- Known Issues, Availability and Performance
+- Network and Connectivity issues
+- Node Health
+
+To perform further checks on your AKS cluster to troubleshoot and get recommended solutions, click on the AKS Diagnostics link at the top of the page to open it for the selected cluster. For more information on AKS Diagnostics, visit [AKS Diagnostics Overview](https://docs.microsoft.com/azure/aks/concepts-diagnostics). 
+
+![AKS Diagnostics Webview](../resources/aks-diagnostics-webview.png)

docs/book/src/features/aks-periscope.md

@@ -0,0 +1,32 @@
+# AKS Periscope
+
+### AKS Periscope
+
+Right click on your AKS cluster and click on **Run AKS Periscope** to collect node and pod logs for your AKS cluster and to export them to an Azure storage account. Upon selecting the option, a web view will load providing you the option to generate a downloadable link for the collected logs as well as a shareable link with 7-day expiry.
+
+> If you are not seeing the logs for all the nodes, it is possible the logs were still uploading. Try clicking the **Generate Link** button again to load more logs.
+
+For more information, visit [AKS Periscope](https://github.com/Azure/aks-periscope).
+
+![AKS Periscope Webview](../resources/aks-periscope-webview.png)
+
+#### Configuring Storage Account
+
+Running the AKS Periscope requires you to have a storage account associated with the Diagnostic settings of your AKS cluster. If you have only one storage account associated with the Diagnostic settings of your AKS cluster, the collected logs will be stored in the associated storage account by default. If you have more than one storage account associated with the Diagnostics settings of your AKS cluster, then the extension will prompt you to choose the storage account for saving collected logs. If you don't have a storage account configured in the Diagnostic settings, please follow these instructions to enable it.
+
+1. Navigate to your AKS cluster in the [Azure Portal](https://portal.azure.com/).
+
+2. Click on **Diagnostic Settings** under **Monitoring** in the left navigation.
+
+3. Click on **Add diagnostic setting**.
+
+4. Enter a name, such as myAKSClusterLogs, then select the option to **Archive to a storage account**.
+
+5. Select a storage account of your choice.
+
+6. In the list of available logs, select the logs you wish to enable.
+    > Note: The incurred cost is subject to your storage account usage and Azure Storage Policy.
+
+7. When ready, select **Save** to enable collection of the selected logs.
+
+For more information on Diagnostics settings, visit [Create diagnostic settings to send platform logs and metics to different destinations](https://docs.microsoft.com/azure/azure-monitor/platform/diagnostic-settings).

docs/book/src/features/create-gh-workflow.md

@@ -0,0 +1,10 @@
+# Create GitHub Workflow
+
+### Create GitHub Workflow
+
+Right click on your AKS cluster and click on **Create GitHub Workflow** to easily open and create a workflow starter template. This helps in quick generation of the workflow templates with pre populates resource and clustername for:
+
+- [Starter Workflow](https://github.com/actions/starter-workflows/blob/main/deployments/azure-kubernetes-service.yml)
+- [Helm Workflow](https://github.com/actions/starter-workflows/blob/main/deployments/azure-kubernetes-service-helm.yml)
+- [Kompose Workflow](https://github.com/actions/starter-workflows/blob/main/deployments/azure-kubernetes-service-kompose.yml)
+- [Kustomize Workflow](https://github.com/actions/starter-workflows/blob/main/deployments/azure-kubernetes-service-kustomize.yml)

docs/book/src/features/features.md

@@ -0,0 +1,19 @@
+## Features
+
+Once you successfully log in with your Azure Account, you can view all AKS clusters in your Azure subscriptions(s) under the section named **Azure**. You can right click on your AKS cluster and click a menu item to perform following actions.  
+
+![Cloud explorer extension menu](../resources/right-click-menu.png)
+
+![Cloud explorer extension menu](../resources/right-click-menu-workflow.png)
+
+![Cloud explorer extension menu](../resources/right-click-menu-kubectl.png)
+
+![Cloud explorer extension menu](../resources/right-click-menu-managedoperations.png)
+
+![Cloud explorer extension menu](../resources/right-click-api-health-check-menu.png)
+
+![Cloud explorer extension menu](../resources/right-click-inspektor-gadget.png)
+
+![Cloud explorer extension menu](../resources/right-click-inspektor-gadget-command.png)
+
+![Cloud explorer extension menu](../resources/right-click-subscription.png)

docs/book/src/features/inspektor-gadget.md

@@ -0,0 +1,9 @@
+### Inspektor Gadget
+
+### Deploy and Undeploy InspektorGadget
+
+Right click on your AKS cluster and click on **Inspektor Gadget** to easily deploy gadget into your cluster. User can easily one-click deploy and undeploy gadget from this feature.
+
+### Profile, Top and Snapshot Inspektor Gadget Commands
+
+After successfully deploying Inspektor Gadget, right-click on your AKS cluster and select **Inspektor Gadget** and choose **Gadget Commands** to easily use non-interactive Top, Profile or Snapshot commands for your cluster.

docs/book/src/features/install-azureserviceoperator.md

@@ -0,0 +1,11 @@
+### Install Azure Service Operator
+
+### Install Azure Service Operator
+
+Right click on your AKS cluster and click on **Install Azure Service Operator** to easily deploy the latest version of Azure Service Operator (ASO) on your AKS cluster and provision and connect applications to Azure resources within Kubernetes. When you select this option, you'll be prompted for a service principal for ASO to use when performing Azure resource operations. This service principal must have appropriate permissions (typically Contributor at suitable scope). Fill out the service principal details and click **Submit** to kick off the installation of Azure Service Operator.
+
+> Install Azure Service Operator can only be performed on an AKS cluster that has never had ASO installed before. If you have already initiated the installation manually, follow the instructions on [Azure Service Operator](https://azure.github.io/azure-service-operator/#installation) to complete.
+
+For more information on Azure Service Operator, visit [Azure Service Operator (for Kubernetes)](https://github.com/Azure/azure-service-operator). If you are experiencing issues with Azure Service Operator, visit [Azure Service Operator (ASO) troubleshooting](https://github.com/Azure/azure-service-operator/blob/master/docs/troubleshooting.md).
+
+![Azure Service Operator Webview](../resources/azure-service-operator-screenshot.png)

docs/book/src/features/k8s-api-health-points.md

@@ -0,0 +1,9 @@
+### Kubernetes API Health Endpoints
+
+### Run Kubernetes API Health Endpoints
+
+Right click on your AKS cluster and click on **Kubernetes API Health Endpoints** to easily run few [k8s cluster API endpoint health check](https://kubernetes.io/docs/reference/using-api/health-checks/). Currently we have enable following health check:
+
+- Healthz
+- Livez
+- Readyz

docs/book/src/features/manage-cluster-operations.md

@@ -0,0 +1,8 @@
+# Run Managed Cluster Operations
+
+### Run Managed Cluster Operations from your AKS cluster
+
+Right click on your AKS cluster and click on **Managed Cluster Operations** to easily run few managed cluster operations on your cluster. Currently we have enable following operations:
+
+- Delete Cluster
+- Rotate Cluster Certificate

docs/book/src/features/merge-save-kubeconfig.md

@@ -0,0 +1,10 @@
+# Merge and Save Into Kubeconfig
+
+### Merge into Kubeconfig
+
+Right click on your AKS cluster and click on **Merge into Kubeconfig** to add the selected AKS cluster to the kubeconfig file.
+
+### Save Kubeconfig
+
+Right click on your AKS cluster and click on **Save Kubeconfig** to save the kubeconfig of the selected AKS cluster.
+

docs/book/src/features/run-kubectl-command.md

@@ -0,0 +1,12 @@
+# Run Kubectl Commands
+
+### Run Kubectl Commands from your AKS cluster
+
+Right click on your AKS cluster and click on **Run Kubectl Commands** to easily run few known kubectl commands on your cluster. Currently we have enable following kubectl commands for the AKS cluster:
+
+- Describe Services
+- Get All Pods
+- API Resources
+- Get Cluster Info
+- Get Node
+- Get All Events

docs/book/src/features/show-properties-azureportal-start-stop.md

@@ -0,0 +1,19 @@
+# Show Properties, Show in Azure Portal
+
+### Show in Azure Portal
+
+Right click on your AKS cluster and click on **Show in Azure Portal** to easily navigate to AKS cluster overview page in Azure Portal.
+
+### Show Properties
+
+Right click on your AKS cluster and click on **Show Properties** to display the AKS cluster and agent pool properties like provisioning state, fqdn, k8s version, along with node properties like node version, vm type, vm size, o/s type, o/s disk size and nodes provisioning state.
+
+### Create cluster from Azure Portal
+
+Right click on your AKS sunscription and click on **Create cluster from Azure Portal** to easily navigate to AKS create cluster page in Azure Portal.
+
+### Start or Stop AKS cluster
+
+Right click on your AKS cluster and click on **Show Properties** to display the AKS cluster properties, within the page there will be **Stop/Start Cluster** button to perform the start or stop the cluster operation.
+
+![Start or Stop Cluster From Properties Webview](../resources/aks-startstop-cluster.png)