Merge pull request #1400 from kubeshop/julianne/doc/monokle/monokle-d…

…oc-review-updates-18-02-2022 Monokle Documentation Updates 1.5.0
kubeshop · Feb 24, 2022 · ec94720 · ec94720
2 parents 58c0b30 + 57c3ed1
commit ec94720
Show file tree

Hide file tree

Showing 36 changed files with 229 additions and 130 deletions.
diff --git a/docs/apply-and-diff.md b/docs/apply-and-diff.md
@@ -7,8 +7,8 @@ When a resource is selected in the navigator, the Editor contains **Deploy** and
 - Selecting **Deploy** will deploy the selected resource to the currently configured Cluster. A status message will be
   shown in the top right after deploying.
 - Selecting **Diff** will diff the selected resource against the currently configured cluster;
-    - If the resource does not exist in the cluster an error will be shown.
-    - If the resource _does_ exist a Diff dialog will be shown.
+    - If the resource does not exist in the cluster, an error will be shown.
+    - If the resource _does_ exist, the Diff dialog will be shown.
 
 ![Resource Diff](img/diff-tble-8-1.5.0.png)
 
@@ -22,5 +22,17 @@ Refreshing the diff is done with the **Refresh** button and deploying your local
 
 ## **Editing a Resource in Cluster Mode**
 
-Monokle allows you to edit any resource viewed in [Cluster Mode](cluster-integration.md) and use the Deploy button to apply those changes back
+Monokle allows you to edit any resource viewed in [Cluster Mode](cluster-integration.md) and use the **Deploy** button to apply those changes back
 to the cluster. This immediately applies "hot fixes" to your cluster during browsing.
+
+## **Deploy Resource Changes to Cluster**
+
+After editing a resource in Monokle, click the **Diff** button:
+
+![Deploy Button](img/deploy-to-cluster-1.5.0.png)
+
+ The following modal appears for selecting the namesapce for deployment:
+
+![Namespace Selector](img/namespace-selector-1.5.0.png)
+
+Select an existing namespace from the cluster, create a new namespace, or don't specify a namespace, which will deploy into namespaces already declared in the resource.
diff --git a/docs/cluster-integration.md b/docs/cluster-integration.md
@@ -1,8 +1,14 @@
 # Cluster Integration
 
-Although Monokle is mainly geared at working with manifest files, it also has the capability to connect 
+Although Monokle is mainly geared toward working with manifest files, it also has the capability to connect 
 to a cluster and show all contained resources, providing a convenient and easy way to inspect cluster resources.
 
+Monokle will automatically detect the default Kubeconfig file or it can be declared in Settings:
+
+![Kubeconfig Setting](img/kubeconfig-setting-1.5.0.png)
+
+## **Using the Cluster Selector**
+
 Choose a cluster to work with by using the Cluster Selector:
 
 ![Clusters Tab](img/clusters-tab-1.5.0.png)
@@ -24,3 +30,20 @@ Monokle is now in **Cluster Mode** (as indicated by the header at the top):
   - Resource navigation works as with files; selecting a resource shows its content in the source editor.
   - Resource links are shown as before with corresponding popups/links/etc.
 - Selecting **Exit** in the top right restores the contents of the Resource Navigator to the currently selected folder.
+
+## **Working with Multiple Resources**
+
+In the Navigator, hover over a local resource to display a check box to select one or more resources:
+
+![Cluster Resource Check Box](img/navigator-resource-check-box-1.5.0.png)
+
+Selecting one or more resources brings up the **Action Links** at the top of the Navigator where the **Delete** and **Deploy** options are available:
+
+![Cluster Resource Check Box Select](img/navigator-select-cluster-resources-1.5.0.png)
+
+This same functionality is available for cluster resources where the **Delete** and **Save to file/folder** are the options:
+
+![Cluster Resource Check Box Options](img/navigator-resource-cluster-actions-1.5.0.png)
+
+
+
diff --git a/docs/creating-resources.md b/docs/creating-resources.md
@@ -1,6 +1,8 @@
 # Creating Resources
 
-While using Monokle, you can directly add new K8s resources. Once you have browsed and added your project folder, click on the “New Resource” button at the top of the navigator to launch the “Add New Resource” dialog.
+## **Add a Resource**
+
+While using Monokle, you can directly add new K8s resources. Once you have browsed and added your project folder, click on the **New Resource** button at the top of the navigator to launch the **Add New Resource** dialog.
 
 ![Add Resource](img/add-resource-1.5.0.png)
 
@@ -10,4 +12,48 @@ For adding resources to new or existing files in the navigator, click on the Sav
 
 While creating a resource, it is possible to select an existing resource as a template from the drop-down menu. 
 
-![Resource template](img/template.png)
+![Resource template](img/template.png)
+
+## **Create a Resource from a Template**
+
+Monokle allows the use of templates to start a new project via the **Start from a template** option:
+
+![Start with Template](img/start-with-template-1.5.0.png)
+
+The **Create a Project from a Template** dialog appears:
+
+![Start with Template](img/name-project-1.5.0.png)
+
+Name your project, select its location and click **Next: Select a Template**.
+
+Monokle includes a default set of templates which are installed automatically when starting Monokle
+for the first time and available in the Templates Explorer when working with your Monokle projects:
+
+![Default Templates](img/template-selection-1.5.0.png)
+
+Check out the [Monokle Default Templates Plugin](https://github.com/kubeshop/monokle-default-templates-plugin) repository to 
+see the complete list of templates that are included along with their corresponding schemas and manifests.
+
+## **Navigator Resource Options**
+
+Click the ellipsis to the right of a resource name to see the options available:
+
+![Resource Options](img/navigator-resource-options-1.5.0.png)
+
+### **Rename a Resource**
+
+You can rename resources and update all the references associated with that resource to ensure the integrity of that link.
+
+![Rename Resource](img/rename.png)
+
+### **Clone a Resource**
+
+You can use the Clone action to create a new resource by using existing resources as a template. 
+
+![Clone Resource](img/clone.png)
+
+### **Delete a Resource**
+
+You can use the Delete action in the cluster mode to delete the resource from the actual cluster. 
+
+![Delete Resource](img/delete.png)
diff --git a/docs/features.md b/docs/features.md
@@ -48,14 +48,14 @@ Easily switch in between projects to more efficiently work with multiple project
 
 ## **Diff Multiple Resources**
 
-When a resource is selected in the navigator, the Editor contains a "Diff" button at the top right.
+When a resource is selected in the navigator, the Editor contains a **Diff** button at the top right.
 
 ![Diff Button](img/diff-button-1.5.0.png)
 
-Selecting "Diff" will compare the selected resource against the currently configured cluster:
+Selecting **Diff** will compare the selected resource against the currently configured cluster:
 
   - If the resource does not exist in the cluster an error will be shown.
-  - If the resource _does_ exist a Diff dialog will be shown.
+  - If the resource _does_ exist the Diff dialog will be shown.
 
 ![Resource Diff](img/diff-tble-8-1.5.0.png)
 
@@ -81,11 +81,11 @@ Name your project, select its location and click **Next: Select a Template**.
 Monokle includes a default set of templates which are installed automatically when starting Monokle
 for the first time and available in the Templates Explorer when working with your Monokle projects:
 
+![Default Templates](img/template-selection-1.5.0.png)
+
 Check out the [Monokle Default Templates Plugin](https://github.com/kubeshop/monokle-default-templates-plugin) repository to 
 see the complete list of templates that are included along with their corresponding schemas and manifests.
 
-![Default Templates](img/template-selection-1.5.0.png)
-
 
 
 

diff --git a/docs/file-explorer.md b/docs/file-explorer.md
@@ -1,19 +1,19 @@
 # File Explorer
 
-- The File Explorer shows all files parsed in the folder selected:
-  - Excluded files are greyed out.
-  - Files containing resource manifests have a number displayed after them, showing the number of 
-    resources found in that file.
+The File Explorer shows all files parsed in the folder selected:
+
+- Excluded files are greyed out.
+- Files containing resource manifests have a number displayed after them, showing the number of resources found in that file.
 
 Selecting a file will highlight contained resources in the Navigator and attempt to scroll them into view. The contents of the 
-file will be shown in the source editor to the right - allowing for direct editing of the file.
+file will be shown in the source editor to the right, allowing for direct editing of the file.
 
 ![File Explorer Navigation](img/resource-navigation-2-1.5.0.png)
 
 In this screenshot:
 
 - The argo-rollouts-aggregate-roles.yaml file is selected - the "3" after the filename indicates it contains 3 kubernetes resources.
-- The 3 ClusterRole resources in thie file are highlighed in the Navigator in the middle.
+- The 3 ClusterRole resources in the file are highlighed in the Navigator in the middle of the screen.
 - The contents of the file are shown in the editor to the right.
 
 While in the File Explorer, the File Action drop down list is available by clicking the ellipsis to the right of the file name.

diff --git a/docs/form-editor.md b/docs/form-editor.md
@@ -0,0 +1,21 @@
+# Using the Form Editor
+
+## **Edit Resources Properties via Form**
+
+Monokle shows form editors for diverse Kubernetes resources which allows you to interactively change the specification of your resources using visual controls/inputs.
+
+![Form Editor](img/form-editor-1.5.0.png)
+
+For example in the case of a ConfigMap Kubernetes resource, clicking on "Form" at the top of the Editor, opens the form fields editor for key ConfigMap properties, allowing you to edit/discover all available properties without having to learn or lookup the corresponding YAML/resource documentation. Any changes made and saved (with the Save button on the top right)
+are written back to the underlying YAML. 
+
+## **Using the Object Metadata Editor**
+
+To launch the Metadata Editor, click on the **Metadata** button.
+
+![Metadata Button](img/metadata-button-image-1.5.0.png)
+
+For editing object metadata, you need to provide a specific name, namespace, annotations, labels, cluster name, generate name, and finalizers to uniquely identify the object.  
+
+**Check out [this tutorial](tutorials/how-to-create-and-edit-configmap.md) for more details 
+on how to use the Form Editor and Metadata.**
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -35,11 +35,11 @@ Monokle uses Helm, Kubectl and Kustomize for corresponding preview functionality
 
 Check out one of our tutorials to get started:
 
-- [How to work with Manifests](tutorials/how-to-navigate-and-edit-manifests.md) to get you started with basic concepts.
+- [How to Work with Manifests](tutorials/how-to-navigate-and-edit-manifests.md) to get you started with basic concepts.
 - [How to Browse Clusters](tutorials/how-to-browse-clusters.md) to help you interact with your cluster(s).
 - [How to Configure Monokle](tutorials/how-to-configure-monokle.md) to see how you can set up Monokle to your needs.
 - [How to Fix Broken Links](tutorials/how-to-fix-broken-links.md) to give you an idea of how Monokle can be used for resource validation and correction.
-- [How to work with ConfigMaps](tutorials/how-to-create-and-edit-configmap.md) to see how the Form editor for ConfigMaps helps you edit resources without having to write any YAML.
+- [How to Work with ConfigMaps](tutorials/how-to-create-and-edit-configmap.md) to see how the Form editor for ConfigMaps helps you edit resources without having to write any YAML.
 
 
 ## **Get in Touch!**

diff --git a/docs/helm.md b/docs/helm.md
@@ -3,9 +3,16 @@
 Monokle has built-in support for [Helm](https://helm.sh/) - a popular tool for managing kubernetes configurations:
 
 - Monokle can identify and show Helm charts and their values files.  
-- Monokle can preview resources generated by Helm, helping you debug your charts before you deploy them to your cluster. Requires Helm to be installed and configured in your PATH.
+- Monokle can preview resources generated by Helm, helping you debug your charts before you deploy them to your cluster. This requires Helm to be installed and configured in your PATH.
+
+All examples below are from the [Emissary Ingress Charts Folder](https://github.com/emissary-ingress/emissary/tree/master/charts/emissary-ingress) - clone and try these yourself!
+
+## **Configuring Helm Integration**
+
+In Settings, set which Helm command to use when generating Helm previews in Monokle:
+
+![Helm Settings](img/helm-settings-1.5.0.png)
 
-All examples below are from the [Emissary Ingress charts folder](https://github.com/emissary-ingress/emissary/tree/master/charts/emissary-ingress) - clone and try these yourself!
 
 ## **Helm Navigation**
 

diff --git a/docs/img/deploy-to-cluster-1.5.0.png b/docs/img/deploy-to-cluster-1.5.0.png
diff --git a/docs/img/error-details-popup-1.5.0.png b/docs/img/error-details-popup-1.5.0.png
diff --git a/docs/img/helm-settings-1.5.0.png b/docs/img/helm-settings-1.5.0.png
diff --git a/docs/img/invoke-kustomize-setting-1.5.0.png b/docs/img/invoke-kustomize-setting-1.5.0.png
diff --git a/docs/img/kubeconfig-setting-1.5.0.png b/docs/img/kubeconfig-setting-1.5.0.png
diff --git a/docs/img/kustomize-settings-1.5.0.png b/docs/img/kustomize-settings-1.5.0.png
diff --git a/docs/img/link-syntax-errors-image-1-1.5.0.png b/docs/img/link-syntax-errors-image-1-1.5.0.png
diff --git a/docs/img/metadata-button-image-1.5.0.png b/docs/img/metadata-button-image-1.5.0.png
diff --git a/docs/img/namespace-selector-1.5.0.png b/docs/img/namespace-selector-1.5.0.png
diff --git a/docs/img/navigator-broken-links-list-1.5.0.png b/docs/img/navigator-broken-links-list-1.5.0.png
diff --git a/docs/img/navigator-link-and-syntax-errors-header-1.5.0.png b/docs/img/navigator-link-and-syntax-errors-header-1.5.0.png
diff --git a/docs/img/navigator-link-syntax-errors-1.5.0.png b/docs/img/navigator-link-syntax-errors-1.5.0.png
diff --git a/docs/img/navigator-resource-check-box-1.5.0.png b/docs/img/navigator-resource-check-box-1.5.0.png
diff --git a/docs/img/navigator-resource-cluster-actions-1.5.0.png b/docs/img/navigator-resource-cluster-actions-1.5.0.png
diff --git a/docs/img/navigator-resource-options-1.5.0.png b/docs/img/navigator-resource-options-1.5.0.png
diff --git a/docs/img/navigator-select-cluster-resources-1.5.0.png b/docs/img/navigator-select-cluster-resources-1.5.0.png
diff --git a/docs/img/navigator-syntax-errors-list-1.5.0.png b/docs/img/navigator-syntax-errors-list-1.5.0.png
diff --git a/docs/img/resource-navigation-1-1.5.0.png b/docs/img/resource-navigation-1-1.5.0.png
diff --git a/docs/img/source-editor-pane-1.5.0.png b/docs/img/source-editor-pane-1.5.0.png
diff --git a/docs/kustomize.md b/docs/kustomize.md
@@ -1,17 +1,29 @@
 # Working with Kustomize 
 
-Monokle has built-in support for [Kustomize](https://kustomize.io/) - a popular tool for managing kubernetes configurations:
+Monokle has built-in support for [Kustomize](https://kustomize.io/) - a popular tool for managing Kubernetes configurations:
 
 - Monokle can visualize dependencies and relationships between kustomize files to help you understand the scope of
   a specific kustomization.
 - Monokle can preview resources generated by Kustomize, helping you debug your configurations before you deploy them to 
   your cluster (requires kubectl to be installed and configured in your PATH).
 
-All examples below are from the [Argo Rollouts manifest folder](https://github.com/argoproj/argo-rollouts/tree/master/manifests) - clone and try these yourself!
+All examples below are from the [Argo Rollouts Manifest Folder](https://github.com/argoproj/argo-rollouts/tree/master/manifests) - clone and try these yourself!
+
+## **Configuring Kustomize Integration**
+
+In Settings, set the defaults for working with Kustomize in Monokle:
+
+![Kustomize Settings](img/kustomize-settings-1.5.0.png)
+
+Use the drop-down selector to select how to invoke Kustomize when previewing or applying kustomization files:
+
+![Invoke Kustomize](img/invoke-kustomize-setting-1.5.0.png)
+
+Tick the check box to enable Helm-related functionality when invoking Kustomize.
 
 ## **Kustomize Navigation**
 
-When selecting a folder containing kustomization.yaml files, these will automatically be displayed in a **Kustomizations** section 
+When selecting a folder containing kustomization.yaml files, these files will automatically be displayed in a **Kustomizations** section 
 on top of the Navigator:
 
 ![Kustomize Navigation](img/kustomize-navigation-1.5.0.png)
@@ -68,7 +80,7 @@ specified in the kustomization configuration:
 
 ## **Editing of Kustomizations During Preview**
 
-When previewing a kustomization it is possible to edit the previewed kustomization.yaml file and recreate the preview, allowing 
+When previewing a kustomization, it is possible to edit the previewed kustomization.yaml file and recreate the preview, allowing 
 you to quickly assess the impact of any changes on the generated files, instead of having to exit and recreate the preview to make a change.
 
 ![Edit kustomization during Preview](img/kust-preview-reload-1.5.0.png)
diff --git a/docs/overview.md b/docs/overview.md
@@ -10,8 +10,6 @@ Launch Monokle and on the welcome screen, there are three options to start worki
  - Create an empty project.
  - Start from a template.
 
-
-
 ![Welcome](img/welcome-1.5.0.png)
 
 Click **Select an existing project** to add your project folder containing K8 resources. 
@@ -37,23 +35,23 @@ The top right contains the following buttons:
 - Open Plugins Manager
 - Open Settings (see below)
 - Help:
-    - Documentation -> opens the Monokle documentation in your system browser.
-    - GitHub -> opens the Monokle GitHub repo in your system browser.
-    - Discord -> Open Discord to talk to us about your Monokle experience.
+    - **Documentation** -> opens the Monokle documentation in your system browser.
+    - **GitHub** -> opens the Monokle GitHub repo in your system browser.
+    - **Discord** -> Opens Discord to talk to us about your Monokle experience.
 
 ## **Settings**
 
 Clicking the Settings icon on the top right opens the settings:
 
 ![Monokle Settings](img/monokle-settings-1.5.0.gif)
 
-- ### **Global Settings**
+### **Global Settings** 
   - **Projects Root Path**
   - **On Startup**: 
     - Automatically load last project.
     - Show Cluster Selector.
 
-- ### **Default Project Settings**  
+### **Default Project Settings**  
   - **Kubeconfig**: Sets which kubeconfig Monokle should use for all cluster interactions.
   - **Files: Include**: Sets which files to parse for kubernetes resources when scanning folders.
   - **Files: Exclude**: Sets which files/folders to exclude when scanning folders for resources.
@@ -67,7 +65,7 @@ Clicking the Settings icon on the top right opens the settings:
   - **Resource links processing**:
     - Ignore optional unsatisfied links.
 
-- ### **Active Project Settings**
+### **Active Project Settings**
    - **Kubeconfig**: Sets which kubeconfig Monokle should use for all cluster interactions.
   - **Files: Include**: Sets which files to parse for kubernetes resources when scanning folders.
   - **Files: Exclude**: Sets which files/folders to exclude when scanning folders for resources.
@@ -83,7 +81,7 @@ Clicking the Settings icon on the top right opens the settings:
 
 ## **System Menu**
 
-Monokle provides a system menu with common File/Edit/View/Window/Help functionality.
+Monokle provides a system menu with the common File/Edit/View/Window/Help functionality.
 
 Mac System Menu: