From 15ae41ceb865e8342e50da29d7b17a39495c7788 Mon Sep 17 00:00:00 2001 From: ashokdevtron Date: Mon, 15 Apr 2024 20:23:38 +0530 Subject: [PATCH 1/8] Revamped Draft of Resource Browser --- docs/reference/glossary.md | 6 ++ docs/user-guide/resource-browser.md | 118 +++++----------------------- 2 files changed, 24 insertions(+), 100 deletions(-) diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index e6c04376b3..581752e7f6 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -176,6 +176,12 @@ The physical or virtual machines that make up a Kubernetes cluster, where contai In Devtron, you can view nodes by going to Resource Browser → (choose a cluster) → Nodes. [Read More...](../user-guide/clusters.md#nodes) +### Objects + +Kubernetes objects are the building blocks that define and manage your applications running on the platform. They are also known as 'Resources' or 'Kinds'. This includes nodes, pods, deployment, cronjob, configmap, and many more. + +Devtron's [Resource Browser](../user-guide/resource-browser/README.md) helps you manage all such objects present in your clusters. + ### Pod The smallest deployable unit in Kubernetes, consisting of one or more containers that share storage and network resources within the same context. diff --git a/docs/user-guide/resource-browser.md b/docs/user-guide/resource-browser.md index 745f28ae87..0301fd8beb 100644 --- a/docs/user-guide/resource-browser.md +++ b/docs/user-guide/resource-browser.md @@ -1,109 +1,27 @@ # Resource Browser -`Resource Browser` lists all of the resources running in your cluster. You can use it to view, inspect, manage, and delete resources in your cluster. You can also create resources from the `Resource Browser`. +The Devtron Resource Browser provides you a central interface to view and manage all your [Kubernetes objects](../../reference/glossary.md#objects) across clusters. It helps you perform key actions like viewing logs, editing live manifests, and even creating/deleting resources directly from the user interface. This is especially useful for troubleshooting purposes as it supports multi-cluster too. -Resource Browser are helpful for troubleshooting issues. It supports multi-cluster. +First, the Resource Browser shows you a list of clusters added to your Devtron setup. By default, it displays a cluster named '*default_cluster*' after the [initial setup](../../setup/install/README.md) is successful. -**Note**: To provide permission to a user to view, inspect, manage, and delete resources, go to the [Authorization > User Permissions](./global-configurations/authorization/user-access.md) section of `Global Configurations`. You can also provide permission via [API token](./global-configurations/authorization/api-tokens.md) or [Permission groups](./global-configurations/authorization/permission-groups.md). Only super admin users will be able to see `Kubernetes Resources` tab and provide permission to other users to access `Resource Browser`. - -Please also note that `Resource Browser` page is under the early version of development and its a `Beta` release. - -## Kubernetes Resources - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/kubernetes-resource-browser-latest.jpg) - -The following resources are grouped in the categories: - -* **Workloads** displays workloads (Cronjob, Deployment, StatefulSet, DaemonSet, Job, and Pod resources) deployed to clusters in your current project. Includes each workload's name, status, type, number of running and total desired Pods, namespace, and cluster. - -* **Config & Storage** display ConfigMap, Secret, PersistentVolume, PersistentVolumeClaim, Pod DisruptionBudget, resources which are used by applications for storing data. The configMap and secret data are provided as local ephemeral storage, which means there is no long-term guarantee about durability. A PersistentVolume (PV) is a piece of storage in the cluster that has been provisioned by server/storage/cluster administrator or dynamically provisioned using Storage Classes. It is a resource in the cluster just like node. Whereas, A PersistentVolumeClaim (PVC) is a request for storage by a user which can be attained from PV. It is similar to a Pod. Pods consume node resources and PVCs consume PV resources. - - -* **Networking** displays your project's [Endpoints](https://kubernetes.io/docs/concepts/services-networking/endpoint-slices/), [NetworkPolicy](https://kubernetes.io/docs/concepts/services-networking/network-policies/) and [Service](https://kubernetes.io/docs/concepts/services-networking/service/) resources. Displays each resource's name, namespace, type, Cluster-IP, External-IP, Port(s), Age. - -* **RBAC** stands for Role-based access control which provides the authorization strategy for regulating access to cluster or resources based on the roles of individual users within your organization. - -* **Custom Resource** allows you to create your own API resources and define your own kind just like Pod, Deployment, ReplicaSet, etc. - - -The following resources are grouped as uncategoried: - -** **Events** displays all the reports of an event in a cluster. - -** **Namespaces** displays the current list of namespaces in a cluster. - -### Search and Filter Resources - -You can search and filter resources by specific resource Kinds. You can also preview `Manifest`, `Events`, `Logs`, access `Terminal` by selecting ellipsis on the specific resource or `Delete` a specific resource. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/select-resource.jpg) - -#### Manifest - - -A manifest is a YAML file that describes each component or resource of your deployment and the state you want your cluster to be in once applied. Once you deploy, you can always edit your manifest file. A manifest specifies the desired state of an object that Kubernetes will maintain when you apply the manifest. - -#### Events - -An event is automatically generated in response to changes with other resources—like nodes, pods, or containers. For example, phases across a pod’s lifecycle transition from pending to running, or statuses like successful or failed may trigger a K8s event. The same goes for re-allocations and scheduling. These events are available until 15 minutes of deployment of the application. - -#### Logs - -Logs contain the logs of the Pods and Containers deployed which you can use for the process of debugging. - - -### Create Kubernetes Resource - -**Note**: As a pre-requisite, you must have a basic understanding of Kubernetes Cluster, Resources, Kinds. - -You can create a Kubernetes resource by passing definition YAML file. You can create more than one resource by separating the resource YAMLs by ‘---’. - -An example that shows the required fields and object specifications for a Kubernetes Deployment: - -```bash -apiVersion: apps/v1 -kind: Deployment -metadata: - name: nginx-deployment - labels: - app: nginx -spec: - replicas: 2 - selector: - matchLabels: - app: nginx - template: - metadata: - labels: - app: nginx - spec: - containers: - - name: nginx - image: nginx:1.14.2 - ports: - - containerPort: 80 -``` - -* Click `Create` button on the upper right corner of the `Kubernetes Resource Browser` page. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/create-resource.jpg) - -* Provide YAML containing K8s resource configuration and click `Apply`. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/create-kubernetes-resource-latest.jpg) - -* You will see the details of `Kind`, `Name`, `Status` and `Message` of the created resources. - ->Note: A message is displayed only when there is an error in the resource YAML. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/edit-yaml.jpg) - - -* If required, click `Edit YAML` to edit the YAML or click `Close`. - -* A new resource will be created or updated accordingly. +![Devtron Resource Browser - List of Clusters](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/resource-browser.jpg) +You can easily connect more clusters by clicking the **Add Cluster** button located at the top of the browser. This will take you to the [Cluster & Environments](../global-configurations/cluster-and-environments.md) configuration within [Global Configurations](../global-configurations/README.md). +You may click a cluster to view and manage all its resources as shown below. +![Resources within Cluster](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/resource-list.jpg) +## Actions You Can Perform +### Viewing/Editing Cluster Details +### Searching a Resource +### Creating a Resource +### Deleting a Resource +### Launching Ephemeral Container +### Viewing/Editing Manifests +### Checking Events +### Using Debug Mode +### Performing Node Operations +### Accessing Pod Terminal +### Downloading Pod Logs From 7e0f764c31f59b6ee2db7d4c4ca06e0c6fa8d649 Mon Sep 17 00:00:00 2001 From: ashokdevtron Date: Thu, 18 Apr 2024 16:01:04 +0530 Subject: [PATCH 2/8] Copied Old Details to New --- .gitbook.yaml | 1 + docs/user-guide/clusters.md | 211 ------------------------- docs/user-guide/resource-browser.md | 233 ++++++++++++++++++++++++++-- 3 files changed, 221 insertions(+), 224 deletions(-) delete mode 100644 docs/user-guide/clusters.md diff --git a/.gitbook.yaml b/.gitbook.yaml index 97dde3b84b..9756aaa9fa 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -76,4 +76,5 @@ redirects: user-guide/use-cases/untitled-3: user-guide/use-cases/connect-django-with-mysql-database.md global-configurations/api-token: user-guide/global-configurations/authorization/api-tokens.md user-guide/creating-application/workflow/ci-pipeline2: user-guide/creating-application/workflow/ci-pipeline.md + usage/clusters: usage/resource-browser diff --git a/docs/user-guide/clusters.md b/docs/user-guide/clusters.md deleted file mode 100644 index 519f770560..0000000000 --- a/docs/user-guide/clusters.md +++ /dev/null @@ -1,211 +0,0 @@ -# Clusters - -Devtron allows you to manage your Kubernetes cluster by: - * Browsing information of cluster and its resources. - * Managing the added resources to meet the requirements for high speed and storage capacity. - * Managing Cluster resources with Kubernetes requests and limits and also individual containers. - * Debugging a pod or node by connecting to a terminal. - -On the left navigation of Devtron, select `Clusters`. You will find the list of clusters in this section which you have added under [Global Configurations > Clusters & Environments](./global-configurations/cluster-and-environments.md). - -You can also search the cluster in the `Search Clusters` bar. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/clusters-latest.jpg) - - -| Fields | Description | -| --- | --- | -| **Cluster** | User-defined name for the cluster in Devtron. E.g. `default-cluster` | -| **Connection Status** | Status of the cluster. The status can be either `Successful` or `Failed`. | -| **Nodes** | Shows the number of nodes in a cluster. | -| **Node Errors** | Shows the error in nodes. | -| **K8s Version** | Shows the version of Kubernetes cluster. | -| **CPU Capacity** | Shows the CPU capacity in your cluster in milicore. E.g., 8000m where 1000 milicore equals to 1 core. | -| **Memory Capacity** | Shows the memory capacity in your cluster in mebibytes. | - -To see the details of resource allocation and usage of the cluster, click the particular cluster. - -## Resources - -On the `Resource allocation and usage`, you can see the details of compute resources or resources. - -* CPU resources -* Memory resources - -If you specify a `request` and `limits` in the container resource manifest file, then the respective values will appear on the `Resource allocation and usage` section. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/resource-allocation-usage-latest.jpg) - -## Nodes - -You can see the list of nodes available in your cluster. Typically you have several nodes in a cluster; in a learning or resource-limited environment, you might have only one node. - -The components on a typical node include the `kubelet`, a `container runtime`, and the `kube-proxy`. - - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/cluster-nodes.jpg) - -If you have multiple nodes, you can search a node by name or label in the search bar. - -| Fields | Description | -| --- | --- | -| **Node** | User-defined name for the node in Devtron. E.g. `demo-new`.
Note: Two nodes cannot have the same name at the same time.
| -| **Status** | Status of a node. It can be either `Ready` or `Not Ready`. | -| **Roles** | Shows the roles of a node. | -| **Errors** | Shows the error in nodes. | -| **K8s Version** | Shows the version of Kubernetes cluster. | -| **No. of Pods** | Shows the number of namespaces or pods in a node. | -| **CPU Usage** | Shows the CPU consumption in a node. | -| **Mem Usage** | Shows the memory consumption in a node | -| **Age** | Shows the time that the pod has been running since the last restart. | - -To display a parameter of a node, use the `Columns` on the right side, select the parameter you want to display from the drop-down list and click `Apply`. - -## Manage Nodes - -Your applications run on pods, and pods run on Nodes. But sometimes, Kubernetes scheduler cannot deploy a pod on a Node for several reasons. As an example, node is not ready, node is not reachable, network is unavailable etc. - -Using the Devtron UI, you will be able to: -* [Debug a node](#debug-a-node) -* [Cordon a node](#cordon-a-node) -* [Drain a node](#drain-a-node) -* [Taint a node](#taint-a-node) -* [Edit a node config](#edit-a-node-config) -* [Delete a node](#delete-a-node) - -To see the summary of a node, click the specific node. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/summary-of-a-node.jpg) - -### Debug a Node - -You can debug a node via Terminal by selecting your namespace and image from the list that has all CLI utilities like kubectl, helm, netshoot etc. or can use a custom image, which is publicly available. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/node-terminal.png) - -* Go to the `Clusters` section from the left navigation pane. -* Select your cluster. -* Search a node by name or label in the search bar. -* On the node, click the ellipsis button and then click `Terminal`. -* Debug a node by selecting the terminal shell `bash` or `sh`. - - -### Cordon a Node - -Cordoning a node means making the node unschedulable. After cordoning a node, new Pods cannot be scheduled on this node. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/node-cordon.jpg) - -* On the node, click the ellipsis button and then click `Cordon`. -* A dialog box with message `Cordoning this node will mark this node as unschedulable. By cordoning a node, you can be sure that no new pods will be scheduled on this node` is displayed. -* The status of the node shows `SchedulingDisabled` with `Unschedulable` parameter set as `true`. - -Similarly, you can uncordon a node by clicking `Uncordon`. After a node is uncordoned, new Pods can be scheduled on the node. - -### Drain a Node - -Before performing maintenance on a node, draining a node evicts all of your pods safely from a node. Safe evictions allow the pod’s containers to gracefully terminate and honour the `PodDisruptionBudgets` you have specified (if relevant). - -After the node is drained, all Pods (including those managed by DaemonSets) in the node will be automatically drained to other nodes in the cluster, and the drained node will be set to cordoned status. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/drain-node.jpg) - -* On the node, click the ellipsis button and then click `Drain`. -* A dialog box with message `Drain will cordon off the node and evict all pods of the node` is displayed. -* Click `Drain Node`. - -You can also select from the following conditions before draining a node: - -| Name | Usage | -| --- | --- | -| **Grace Period** | Period of time in seconds given to each pod to terminate gracefully. If negative, the default value specified in the pod will be used. | -| **Delete empty directory data** | Enabling this field will delete the pods using empty directory data when the node is drained. | -| **Disable eviction (use with caution** | Enabling this field will force drain to use delete, even if eviction is supported. This will bypass checking `PodDisruptionBudgets`.
Note: Make sure to use with caution.
| -| **Force drain** | Enabling this field will force drain a node even if there are pods that do not declare a controller. | -| **Ignore DaemonSets** | Enabling this field will ignore DaemonSet-managed pods. | - -### Taint a Node - -Taints are `key:value` pairs associated with effect. After you add taints to nodes, you can set tolerations on a pod to allow the pod to be scheduled to nodes with certain taints. When you taint a node, it will repel all the pods except those that have a toleration for that taint. A node can have one or many taints associated with it. - -**Note**: Make sure to check taint validations before you add a taint. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/edit-taints.jpg) - -* On the node, click the ellipsis button and then click `Edit taints`. -* Click `Add taint`. -* On the `Key` and `Value` fields, enter the `key:value` pairs and select the [taint effect](#taint-effects) from the drop-down list. -* Click `Save`. -* You can also delete the added taint by clicking delete button. - -#### Taint Effects - -A taint can produce three possible effects: - -| Effect | Description | -| --- | --- | -| **NoSchedule** | The Kubernetes scheduler will only allow scheduling pods that have tolerations for the tainted nodes. | -| **PreferNoSchedule** | The Kubernetes scheduler will try to avoid scheduling pods that do not have tolerations for the tainted nodes. | -| **NoExecute** | Kubernetes will evict the running pods from the nodes if the pods do not have tolerations for the tainted nodes. | - -### Edit a Node Config - -`Edit node config` allows you to directly edit any node. It will open the editor which contains all the configuration settings in which the default format is YAML. You can edit multiple objects, although changes are applied one at a time. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/edit-yaml-node.jpg) - -* You can edit or modify the parameters or values of a node by clicking `Edit node config`. -* Click `Review Changes` to compare the changes in the YAML file. -* Click `Update Node`. - - -### Delete a Node - -* Search a node by name or label in the search bar. -* On the node, click the ellipsis button and then click `Delete`. - -The node will be deleted from the cluster. - - -## Access Cluster via Terminal for Troubleshooting - -User with [Super admins](./global-configurations/authorization/user-access.md#assign-super-admin-permission) access can now troubleshoot cluster issues by accessing the cluster terminal from Devtron. You can select an image from the list that has all CLI utilities like kubectl, helm, netshoot etc. or can use a custom image, which is publicly available. - -To troubleshoot a cluster or a specific node in a cluster, click the terminal symbol on the right side. - -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/cluster-terminal-access.jpg) - -* You will see the user-defined name for the cluster in Devtron. E.g. `default-cluster`. -* In the `Nodes` field, select the node from the drop-down list you want to troubleshoot. E.g. `demo-new`. -* Select the namespace from the drop-down list which you have added in the [Environment](./global-configurations/cluster-and-environments.md#add-environment) section. -* Select the image from the drop-down list which includes all CLI utilities or you can use a custom image, which is publicly available. -* Select the terminal shell from the drop-down list (e.g. `sh`, `bash`) to troubleshoot a node. - - -### One of the Use Cases: Debug Pod - -You can also create pod for debugging which will connect to pod terminal. To find out why the particular pod is not running, you can check `Pod Events` and `Pod Manifest` for details. - -* Check the current state of the Pod and recent events with the following command: - -```bash -kubectl get pods -``` - -* To know more information about each of these pods and to debug a pod depending on the state of the pods, run the following command: - -```bash -kubectl describe pod -``` - - * If the pod status shows `Pending`, it means that it cannot be scheduled onto a node. Generally this is because there are insufficient resources of one type or another that prevent scheduling. - * If the pod is stuck in the `Waiting` state, then it has been scheduled to a worker node, but it cannot run on that machine. One of the most common reason of Waiting pods is a failure to pull the container image. - * If the pod status shows `CrashLoopBackOff`, it may because some of the containers inside a pod are not operating on the default access token when trying to interact with API. - - -Here, you can see configuration information about the container(s) and Pod (labels, resource requirements, etc.), as well as status information about the container(s) and Pod (state, readiness, restart count, events, etc.). - - - **Note**: A container can have no or multiple shells running in it. If you are not able to create a successful connection, try changing the shell, as the container may not have that shell running. - - diff --git a/docs/user-guide/resource-browser.md b/docs/user-guide/resource-browser.md index 0301fd8beb..0d06126b50 100644 --- a/docs/user-guide/resource-browser.md +++ b/docs/user-guide/resource-browser.md @@ -1,5 +1,7 @@ # Resource Browser +## Introduction + The Devtron Resource Browser provides you a central interface to view and manage all your [Kubernetes objects](../../reference/glossary.md#objects) across clusters. It helps you perform key actions like viewing logs, editing live manifests, and even creating/deleting resources directly from the user interface. This is especially useful for troubleshooting purposes as it supports multi-cluster too. First, the Resource Browser shows you a list of clusters added to your Devtron setup. By default, it displays a cluster named '*default_cluster*' after the [initial setup](../../setup/install/README.md) is successful. @@ -12,16 +14,221 @@ You may click a cluster to view and manage all its resources as shown below. ![Resources within Cluster](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/resource-list.jpg) -## Actions You Can Perform - -### Viewing/Editing Cluster Details -### Searching a Resource -### Creating a Resource -### Deleting a Resource -### Launching Ephemeral Container -### Viewing/Editing Manifests -### Checking Events -### Using Debug Mode -### Performing Node Operations -### Accessing Pod Terminal -### Downloading Pod Logs +--- + +## Overview + +| Fields | Description | +| --- | --- | +| **Cluster** | User-defined name for the cluster in Devtron. E.g. `default-cluster` | +| **Connection Status** | Status of the cluster. The status can be either `Successful` or `Failed`. | +| **Nodes** | Shows the number of nodes in a cluster. | +| **Node Errors** | Shows the error in nodes. | +| **K8s Version** | Shows the version of Kubernetes cluster. | +| **CPU Capacity** | Shows the CPU capacity in your cluster in milicore. E.g., 8000m where 1000 milicore equals to 1 core. | +| **Memory Capacity** | Shows the memory capacity in your cluster in mebibytes. | + +To see the details of resource allocation and usage of the cluster, click the particular cluster. + +On the `Resource allocation and usage`, you can see the details of compute resources or resources. + +* CPU resources +* Memory resources + +If you specify a `request` and `limits` in the container resource manifest file, then the respective values will appear on the `Resource allocation and usage` section. + +![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/resource-allocation-usage-latest.jpg) + +--- + +## Browsing Resources + +--- + +## Nodes + +You can see the list of nodes available in your cluster. Typically you have several nodes in a cluster; in a learning or resource-limited environment, you might have only one node. + +The components on a typical node include the `kubelet`, a `container runtime`, and the `kube-proxy`. + +![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/cluster-nodes.jpg) + +If you have multiple nodes, you can search a node by name or label in the search bar. + +| Fields | Description | +| --- | --- | +| **Node** | User-defined name for the node in Devtron. E.g. `demo-new`.
Note: Two nodes cannot have the same name at the same time.
| +| **Status** | Status of a node. It can be either `Ready` or `Not Ready`. | +| **Roles** | Shows the roles of a node. | +| **Errors** | Shows the error in nodes. | +| **K8s Version** | Shows the version of Kubernetes cluster. | +| **No. of Pods** | Shows the number of namespaces or pods in a node. | +| **CPU Usage** | Shows the CPU consumption in a node. | +| **Mem Usage** | Shows the memory consumption in a node | +| **Age** | Shows the time that the pod has been running since the last restart. | + +To display a parameter of a node, use the `Columns` on the right side, select the parameter you want to display from the drop-down list and click `Apply`. + +### Manage Nodes + +Your applications run on pods, and pods run on Nodes. But sometimes, Kubernetes scheduler cannot deploy a pod on a Node for several reasons. As an example, node is not ready, node is not reachable, network is unavailable etc. + +Using the Devtron UI, you will be able to: +* [Debugging a Node](#debug-a-node) +* [Cordoning a Node](#cordon-a-node) +* [Draining a Node](#drain-a-node) +* [Tainting a Node](#taint-a-node) +* [Editing a Node Config](#edit-a-node-config) +* [Deleting a Node](#delete-a-node) + +To see the summary of a node, click the specific node. + +![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/summary-of-a-node.jpg) + +### Debugging a Node + +You can debug a node via Terminal by selecting your namespace and image from the list that has all CLI utilities like kubectl, helm, netshoot etc. or can use a custom image, which is publicly available. + +![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/node-terminal.png) + +* Go to the `Clusters` section from the left navigation pane. +* Select your cluster. +* Search a node by name or label in the search bar. +* On the node, click the ellipsis button and then click `Terminal`. +* Debug a node by selecting the terminal shell `bash` or `sh`. + +### Cordoning a Node + +Cordoning a node means making the node unschedulable. After cordoning a node, new Pods cannot be scheduled on this node. + +![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/node-cordon.jpg) + +* On the node, click the ellipsis button and then click `Cordon`. +* A dialog box with message `Cordoning this node will mark this node as unschedulable. By cordoning a node, you can be sure that no new pods will be scheduled on this node` is displayed. +* The status of the node shows `SchedulingDisabled` with `Unschedulable` parameter set as `true`. + +Similarly, you can uncordon a node by clicking `Uncordon`. After a node is uncordoned, new Pods can be scheduled on the node. + +### Draining a Node + +Before performing maintenance on a node, draining a node evicts all of your pods safely from a node. Safe evictions allow the pod’s containers to gracefully terminate and honour the `PodDisruptionBudgets` you have specified (if relevant). + +After the node is drained, all Pods (including those managed by DaemonSets) in the node will be automatically drained to other nodes in the cluster, and the drained node will be set to cordoned status. + +![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/drain-node.jpg) + +* On the node, click the ellipsis button and then click `Drain`. +* A dialog box with message `Drain will cordon off the node and evict all pods of the node` is displayed. +* Click `Drain Node`. + +You can also select from the following conditions before draining a node: + +| Name | Usage | +| --- | --- | +| **Grace Period** | Period of time in seconds given to each pod to terminate gracefully. If negative, the default value specified in the pod will be used. | +| **Delete empty directory data** | Enabling this field will delete the pods using empty directory data when the node is drained. | +| **Disable eviction (use with caution** | Enabling this field will force drain to use delete, even if eviction is supported. This will bypass checking `PodDisruptionBudgets`.
Note: Make sure to use with caution.
| +| **Force drain** | Enabling this field will force drain a node even if there are pods that do not declare a controller. | +| **Ignore DaemonSets** | Enabling this field will ignore DaemonSet-managed pods. | + +### Tainting a Node + +Taints are `key:value` pairs associated with effect. After you add taints to nodes, you can set tolerations on a pod to allow the pod to be scheduled to nodes with certain taints. When you taint a node, it will repel all the pods except those that have a toleration for that taint. A node can have one or many taints associated with it. + +**Note**: Make sure to check taint validations before you add a taint. + +![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/edit-taints.jpg) + +* On the node, click the ellipsis button and then click `Edit taints`. +* Click `Add taint`. +* On the `Key` and `Value` fields, enter the `key:value` pairs and select the [taint effect](#taint-effects) from the drop-down list. +* Click `Save`. +* You can also delete the added taint by clicking delete button. + +#### Taint Effects + +A taint can produce three possible effects: + +| Effect | Description | +| --- | --- | +| **NoSchedule** | The Kubernetes scheduler will only allow scheduling pods that have tolerations for the tainted nodes. | +| **PreferNoSchedule** | The Kubernetes scheduler will try to avoid scheduling pods that do not have tolerations for the tainted nodes. | +| **NoExecute** | Kubernetes will evict the running pods from the nodes if the pods do not have tolerations for the tainted nodes. | + +### Editing a Node Config + +`Edit node config` allows you to directly edit any node. It will open the editor which contains all the configuration settings in which the default format is YAML. You can edit multiple objects, although changes are applied one at a time. + +![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/edit-yaml-node.jpg) + +* You can edit or modify the parameters or values of a node by clicking `Edit node config`. +* Click `Review Changes` to compare the changes in the YAML file. +* Click `Update Node`. + + +### Deleting a Node + +* Search a node by name or label in the search bar. +* On the node, click the ellipsis button and then click `Delete`. + +The node will be deleted from the cluster. + +--- + +## Pods + +--- + +## Other Resource Kinds + +--- + +## Terminal + +User with [Super admins](./global-configurations/authorization/user-access.md#assign-super-admin-permission) access can now troubleshoot cluster issues by accessing the cluster terminal from Devtron. You can select an image from the list that has all CLI utilities like kubectl, helm, netshoot etc. or can use a custom image, which is publicly available. + +To troubleshoot a cluster or a specific node in a cluster, click the terminal symbol on the right side. + +![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/cluster-terminal-access.jpg) + +* You will see the user-defined name for the cluster in Devtron. E.g. `default-cluster`. +* In the `Nodes` field, select the node from the drop-down list you want to troubleshoot. E.g. `demo-new`. +* Select the namespace from the drop-down list which you have added in the [Environment](./global-configurations/cluster-and-environments.md#add-environment) section. +* Select the image from the drop-down list which includes all CLI utilities or you can use a custom image, which is publicly available. +* Select the terminal shell from the drop-down list (e.g. `sh`, `bash`) to troubleshoot a node. + + +### Example: Debug Pod + +You can also create pod for debugging which will connect to pod terminal. To find out why a particular pod is not running, you can check `Pod Events` and `Pod Manifest` for details. + +* Check the current state of the Pod and recent events with the following command: + +```bash +kubectl get pods +``` + +* To know more information about each of these pods and to debug a pod depending on the state of the pods, run the following command: + +```bash +kubectl describe pod +``` + +| Pod Status | Description | Common Causes | +| ---------------- | --------------------------------------- | ------------------------------------------ | +| Pending | Pod cannot be scheduled onto a node | Insufficient resources (CPU, memory, etc.) | +| Waiting | Pod has been scheduled but cannot run | Failed to pull container image | +| CrashLoopBackOff | Container keeps crashing and restarting | Incorrect access token for API interaction | + + +Here, you can see configuration information about the container(s) and Pod (labels, resource requirements, etc.), as well as status information about the container(s) and Pod (state, readiness, restart count, events, etc.). + + + **Note**: A container can have no shells or multiple shells running in it. If you are unable to create a successful connection, try changing the shell, as the container may not have that shell running. + +--- + +## Creating Resources + + + From 3b06c8c9873571fa1ddee5f0795f4c0081d0b3eb Mon Sep 17 00:00:00 2001 From: ashokdevtron Date: Tue, 30 Apr 2024 19:25:51 +0530 Subject: [PATCH 3/8] Resource Browser - Latest Draft --- .../app-details/ephemeral-containers.md | 9 +- docs/user-guide/resource-browser.md | 329 +++++++++++++----- 2 files changed, 241 insertions(+), 97 deletions(-) diff --git a/docs/user-guide/app-details/ephemeral-containers.md b/docs/user-guide/app-details/ephemeral-containers.md index 9a98525a4f..be4dde86e5 100644 --- a/docs/user-guide/app-details/ephemeral-containers.md +++ b/docs/user-guide/app-details/ephemeral-containers.md @@ -57,14 +57,7 @@ Wherever you can access pod resources in Devtron, you can launch an ephemeral co ### From Devtron (Resource Browser) -{% embed url="https://www.youtube.com/watch?v=Ml19i29Ivc4" caption="Launching Ephemeral Containers from Resource Browser" %} - -1. In the left sidebar, go to **Resource Browser**. -2. Select **Pod** inside `Workloads`. -3. Use the searchbar to find and locate the pod you wish to debug. Click the pod. -4. Go to the **Terminal** tab - -The rest is same as steps 6, 7, and 8 mentioned in the [previous section](#from-devtron-app-details). +Click [here](../resource-browser.md#launching-ephemeral-container) to know more. ### From Devtron's Cluster Terminal diff --git a/docs/user-guide/resource-browser.md b/docs/user-guide/resource-browser.md index 0d06126b50..f1ba69aea1 100644 --- a/docs/user-guide/resource-browser.md +++ b/docs/user-guide/resource-browser.md @@ -6,42 +6,83 @@ The Devtron Resource Browser provides you a central interface to view and manage First, the Resource Browser shows you a list of clusters added to your Devtron setup. By default, it displays a cluster named '*default_cluster*' after the [initial setup](../../setup/install/README.md) is successful. -![Devtron Resource Browser - List of Clusters](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/resource-browser.jpg) +![Figure 1: Devtron Resource Browser - List of Clusters](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/resource-browser.jpg) You can easily connect more clusters by clicking the **Add Cluster** button located at the top of the browser. This will take you to the [Cluster & Environments](../global-configurations/cluster-and-environments.md) configuration within [Global Configurations](../global-configurations/README.md). You may click a cluster to view and manage all its resources as shown below. -![Resources within Cluster](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/resource-list.jpg) +![Figure 2: Resources within Cluster](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/resource-list.jpg) --- ## Overview -| Fields | Description | -| --- | --- | -| **Cluster** | User-defined name for the cluster in Devtron. E.g. `default-cluster` | -| **Connection Status** | Status of the cluster. The status can be either `Successful` or `Failed`. | -| **Nodes** | Shows the number of nodes in a cluster. | -| **Node Errors** | Shows the error in nodes. | -| **K8s Version** | Shows the version of Kubernetes cluster. | -| **CPU Capacity** | Shows the CPU capacity in your cluster in milicore. E.g., 8000m where 1000 milicore equals to 1 core. | -| **Memory Capacity** | Shows the memory capacity in your cluster in mebibytes. | +![Figure 3: Resource Browser - Overview Page](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/rb-overview.jpg) + +### Resource Utilization + +This shows the combined CPU and memory consumption of all running pods in the cluster. -To see the details of resource allocation and usage of the cluster, click the particular cluster. +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------| +| CPU Usage | Percentage of CPU resources currently being used across all the pods in the cluster. | +| CPU Capacity | Total amount of CPU resources available across all the nodes in the cluster. Measured in millicores (m). | +| CPU Requests | Total amount of CPU resources requested by all the pods in the cluster. | +| CPU Limits | Maximum amount of CPU resources that a pod can use. | +| Memory Usage | Percentage of memory resources currently being used across all the pods in the cluster. | +| Memory Capacity | Total amount of memory resources available across all the nodes in the cluster. Measured in Megabytes (Mi). | +| Memory Requests | Total amount of memory resources requested by all the pods in the cluster. | +| Memory Limits | Maximum amount of memory resources that a pod can use. | -On the `Resource allocation and usage`, you can see the details of compute resources or resources. +### Errors -* CPU resources -* Memory resources +This shows errors in the cluster. If no error is present in the cluster, Resource Browser will not display this section. -If you specify a `request` and `limits` in the container resource manifest file, then the respective values will appear on the `Resource allocation and usage` section. +### Catalog Framework -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/resource-allocation-usage-latest.jpg) +Based on the schema provided in the catalog framework, you can add relevant details for each cluster. Refer [Catalog Framework](./global-configurations/catalog-framework.md) for more details. + +### Readme + +You can also include additional information about your cluster using the Markdown editor. --- -## Browsing Resources +## Discovering Resources + +### Search and Filter + +You can use the searchbox to browse the resources you are looking for. + +![Figure 4: Locate Resources using Searchbox](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/discover-resource.gif) + +Moreover, you can use filters that allow you to quickly filter your workload as per labels, field selectors, or [CEL expression](https://kubernetes.io/docs/reference/using-api/cel/) as shown below. + +{% embed url="https://www.youtube.com/watch?v=E-V-ELCXtfs" caption="Filtering Workloads in Devtron" %} + +### Edit Manifest + +You can edit the [manifest](../reference/glossary.md#manifest) of a Kubernetes object. This can be for fixing errors, scaling resources, or changing configuration. + +![Figure 5: Editing a Live Manifest](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/edit-live-manifest.gif) + +### View Events + +You can monitor activities like creation, deletion, updation, scaling, or errors in the resources involved. + +![Figure 6: Viewing All Events](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/events.gif) + +### Delete + +You can delete an unwanted resource if it is orphaned and no longer required by your applications. + +![Figure 7: Deleting a Resource](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/delete.gif) + +You can perform all the actions on the following: +* [Nodes](#nodes) +* [Pods](#pods) +* [Other Resource Kinds](#other-resource-kinds) --- @@ -51,99 +92,100 @@ You can see the list of nodes available in your cluster. Typically you have seve The components on a typical node include the `kubelet`, a `container runtime`, and the `kube-proxy`. -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/cluster-nodes.jpg) +If you have multiple nodes, you can search a node by name or label in the search bar. The search result will display the following information of the node. To display a parameter of a node, use `Columns` on the right side, select the parameter to display from the drop-down list, and click **Apply**. -If you have multiple nodes, you can search a node by name or label in the search bar. +![Figure 8: Searching and Filtering Nodes](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/cluster-nodes.jpg) | Fields | Description | | --- | --- | -| **Node** | User-defined name for the node in Devtron. E.g. `demo-new`.
Note: Two nodes cannot have the same name at the same time.
| -| **Status** | Status of a node. It can be either `Ready` or `Not Ready`. | -| **Roles** | Shows the roles of a node. | -| **Errors** | Shows the error in nodes. | -| **K8s Version** | Shows the version of Kubernetes cluster. | -| **No. of Pods** | Shows the number of namespaces or pods in a node. | -| **CPU Usage** | Shows the CPU consumption in a node. | -| **Mem Usage** | Shows the memory consumption in a node | -| **Age** | Shows the time that the pod has been running since the last restart. | - -To display a parameter of a node, use the `Columns` on the right side, select the parameter you want to display from the drop-down list and click `Apply`. +| Node | User-defined name for the node in Devtron. E.g. `demo-new`.
Note: Two nodes cannot have the same name at the same time.
| +| Status | Status of a node. It can be either `Ready` or `Not Ready`. | +| Roles | Shows the roles of a node. | +| Errors | Shows the error in nodes. | +| K8s Version | Shows the version of Kubernetes cluster. | +| Node Group | Shows which collection of worker nodes it belongs to. | -### Manage Nodes +Clicking on a node shows you a number of details such as: -Your applications run on pods, and pods run on Nodes. But sometimes, Kubernetes scheduler cannot deploy a pod on a Node for several reasons. As an example, node is not ready, node is not reachable, network is unavailable etc. +* CPU Usage and Memory Usage of Node +* CPU Usage and Memory Usage of Each Pod +* Number of Pods in the Node +* List of Pods +* Age of Pods +* Labels, Annotations, and Taints +* Node IP -Using the Devtron UI, you will be able to: -* [Debugging a Node](#debug-a-node) -* [Cordoning a Node](#cordon-a-node) -* [Draining a Node](#drain-a-node) -* [Tainting a Node](#taint-a-node) -* [Editing a Node Config](#edit-a-node-config) -* [Deleting a Node](#delete-a-node) +![Figure 9: Checking Node Summary](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/node-summary.jpg) -To see the summary of a node, click the specific node. +Further using the Devtron UI, you will be able to: +* [Debug a Node](#debug-a-node) +* [Cordon a Node](#cordon-a-node) +* [Drain a Node](#drain-a-node) +* [Taint a Node](#taint-a-node) +* [Edit a Node Config](#edit-a-node-config) +* [Delete a Node](#delete-a-node) -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/summary-of-a-node.jpg) +Your applications run on pods, and pods run on nodes. But sometimes, Kubernetes scheduler cannot deploy a pod on a node for several reasons, e.g., node is not ready, node is not reachable, network is unavailable, etc. -### Debugging a Node +### Debug a Node -You can debug a node via Terminal by selecting your namespace and image from the list that has all CLI utilities like kubectl, helm, netshoot etc. or can use a custom image, which is publicly available. +You can debug a node via [Cluster Terminal](#cluster-terminal) by selecting your namespace and image from the list that has all CLI utilities like kubectl, helm, netshoot etc. or can use a custom image, which is publicly available. -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/node-terminal.png) +![Figure 10: Debugging a Node](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/node-terminal.png) -* Go to the `Clusters` section from the left navigation pane. +* Go to the **Clusters** section from the left navigation pane. * Select your cluster. * Search a node by name or label in the search bar. -* On the node, click the ellipsis button and then click `Terminal`. +* On the node, click the ellipsis button and then click **Terminal**. * Debug a node by selecting the terminal shell `bash` or `sh`. -### Cordoning a Node +### Cordon a Node Cordoning a node means making the node unschedulable. After cordoning a node, new Pods cannot be scheduled on this node. -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/node-cordon.jpg) +![Figure 11: Cordoning a Node](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/node-cordon.jpg) -* On the node, click the ellipsis button and then click `Cordon`. -* A dialog box with message `Cordoning this node will mark this node as unschedulable. By cordoning a node, you can be sure that no new pods will be scheduled on this node` is displayed. +* On the node, click the ellipsis button and then click **Cordon**. +* A confirmation dialog box will appear, click **Cordon Node** to proceed. * The status of the node shows `SchedulingDisabled` with `Unschedulable` parameter set as `true`. Similarly, you can uncordon a node by clicking `Uncordon`. After a node is uncordoned, new Pods can be scheduled on the node. -### Draining a Node +### Drain a Node Before performing maintenance on a node, draining a node evicts all of your pods safely from a node. Safe evictions allow the pod’s containers to gracefully terminate and honour the `PodDisruptionBudgets` you have specified (if relevant). After the node is drained, all Pods (including those managed by DaemonSets) in the node will be automatically drained to other nodes in the cluster, and the drained node will be set to cordoned status. -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/drain-node.jpg) +![Figure 12: Draining a Node](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/drain-node.jpg) -* On the node, click the ellipsis button and then click `Drain`. -* A dialog box with message `Drain will cordon off the node and evict all pods of the node` is displayed. -* Click `Drain Node`. +* On the node, click the ellipsis button and then click **Drain**. +* A confirmation dialog box will appear, click **Drain Node** to proceed. +* Click **Drain Node**. You can also select from the following conditions before draining a node: | Name | Usage | | --- | --- | -| **Grace Period** | Period of time in seconds given to each pod to terminate gracefully. If negative, the default value specified in the pod will be used. | -| **Delete empty directory data** | Enabling this field will delete the pods using empty directory data when the node is drained. | -| **Disable eviction (use with caution** | Enabling this field will force drain to use delete, even if eviction is supported. This will bypass checking `PodDisruptionBudgets`.
Note: Make sure to use with caution.
| -| **Force drain** | Enabling this field will force drain a node even if there are pods that do not declare a controller. | -| **Ignore DaemonSets** | Enabling this field will ignore DaemonSet-managed pods. | +| Grace Period | Period of time in seconds given to each pod to terminate gracefully. If negative, the default value specified in the pod will be used. | +| Delete empty directory data | Enabling this field will delete the pods using empty directory data when the node is drained. | +| Disable eviction (use with caution) | Enabling this field will force drain to use delete, even if eviction is supported. This will bypass checking `PodDisruptionBudgets`.
Note: Make sure to use with caution.
| +| Force drain | Enabling this field will force drain a node even if there are pods that do not declare a controller. | +| Ignore DaemonSets | Enabling this field will ignore DaemonSet-managed pods. | -### Tainting a Node +### Taint a Node Taints are `key:value` pairs associated with effect. After you add taints to nodes, you can set tolerations on a pod to allow the pod to be scheduled to nodes with certain taints. When you taint a node, it will repel all the pods except those that have a toleration for that taint. A node can have one or many taints associated with it. **Note**: Make sure to check taint validations before you add a taint. -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/edit-taints.jpg) +![Figure 13: Tainting a Node](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/edit-taints.jpg) -* On the node, click the ellipsis button and then click `Edit taints`. -* Click `Add taint`. +* On the node, click the ellipsis button and then click **Edit taints**. +* Click **Add taint**. * On the `Key` and `Value` fields, enter the `key:value` pairs and select the [taint effect](#taint-effects) from the drop-down list. -* Click `Save`. -* You can also delete the added taint by clicking delete button. +* Click **Save**. +* You can also delete the added taint by clicking the delete button. #### Taint Effects @@ -151,57 +193,132 @@ A taint can produce three possible effects: | Effect | Description | | --- | --- | -| **NoSchedule** | The Kubernetes scheduler will only allow scheduling pods that have tolerations for the tainted nodes. | -| **PreferNoSchedule** | The Kubernetes scheduler will try to avoid scheduling pods that do not have tolerations for the tainted nodes. | -| **NoExecute** | Kubernetes will evict the running pods from the nodes if the pods do not have tolerations for the tainted nodes. | +| NoSchedule | The Kubernetes scheduler will only allow scheduling pods that have tolerations for the tainted nodes. | +| PreferNoSchedule | The Kubernetes scheduler will try to avoid scheduling pods that do not have tolerations for the tainted nodes. | +| NoExecute | Kubernetes will evict the running pods from the nodes if the pods do not have tolerations for the tainted nodes. | -### Editing a Node Config +### Edit a Node Config `Edit node config` allows you to directly edit any node. It will open the editor which contains all the configuration settings in which the default format is YAML. You can edit multiple objects, although changes are applied one at a time. -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/edit-yaml-node.jpg) +![Figure 14: Editing Node Config](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/edit-yaml-node.jpg) -* You can edit or modify the parameters or values of a node by clicking `Edit node config`. -* Click `Review Changes` to compare the changes in the YAML file. -* Click `Update Node`. +* You can edit or modify the parameters or values of a node by clicking **Edit node config**. +* Click **Review Changes** to compare the changes in the YAML file. +* Click **Update Node**. -### Deleting a Node +### Delete a Node * Search a node by name or label in the search bar. -* On the node, click the ellipsis button and then click `Delete`. +* On the node, click the ellipsis button and then click **Delete**. The node will be deleted from the cluster. +{% hint style="info" %} +You can also access [Cluster Terminal](#cluster-terminal) from your node. +{% endhint %} + + --- ## Pods +### Manifest + +Shows you the [configuration](../reference/glossary.md#manifest) of the selected pod and allows you to edit it. Refer [Edit Manifest](#edit-manifest) to know more. + +### Events + +Shows you all the activities (create/update/delete) of the selected pod. Refer [View Events](#view-events) to know more. + +### Logs + +Examining your cluster's pods helps you understand the health of your application. By inspecting pod logs, you can check the performance and identify if there are any failures. This is especially useful for debugging any issues effectively. + +Moreover, you can download the pod logs for ease of sharing and troubleshooting as shown in the below video. + +{% embed url="https://www.youtube.com/watch?v=PP0ZKAZCT58" caption="Downloading Pod Logs" %} + +#### Last Restart Pod Log + +In case any of your pod restarts, you can determine the cause by viewing its container log, time, status, node events in the pod listing screen as shown below: + +![Figure 15: Checking Restart Pod Log](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/restart-pod-log.gif) + +### Terminal + +You can access the terminal within a running container of a pod to view its logs, troubleshoot issues, or execute commands directly. This is different from the [cluster terminal](#cluster-terminal) you get at node level. + +#### Launching Ephemeral Container + +This is a part of [Pod Terminal](#pod-terminal). It is especially useful when `kubectl exec` is insufficient because a container has crashed or a container image doesn't include debugging utilities. + +{% embed url="https://www.youtube.com/watch?v=Ml19i29Ivc4" caption="Launching Ephemeral Containers from Resource Browser" %} + +1. In the Resource Browser, select **Pod** within `Workloads`. +2. Use the searchbar to find and locate the pod you wish to debug. Click the pod. +3. Go to the **Terminal** tab +4. Click **Launch Ephemeral Container** as shown below. + + You get 2 tabs: + 1. **Basic** - It provides the bare minimum configurations required to launch an ephemeral container. + + ![Figure 16: Basic Tab](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/debugging-deployment-and-monitoring/basic.jpg) + + It contains 3 mandatory fields: + + * **Container name prefix** - Type a prefix to give to your ephemeral container, for e.g., *debug*. Your container name would look like `debug-jndvs`. + + * **Image** - Choose an image to run from the dropdown. Ephemeral containers need an image to run and provide the capability to debug, such as `curl`. You can use a custom image too. + + * **Target Container name** - Since a pod can have one or more containers, choose a target container you wish to debug, from the dropdown. + + 2. **Advanced** - It is particularly useful for advanced users that wish to use labels or annotations since it provides additional key-value options. Refer [Ephemeral Container Spec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#ephemeralcontainer-v1-core) to view the supported options. + + {% hint style="info" %} + Devtron ignores the `command` field while launching an ephemeral container + {% endhint %} + --- ## Other Resource Kinds +Other resources in the cluster are grouped under the following categories: + +* Namespace +* Workloads +* Config & Storage +* Networking +* RBAC +* Administration +* Other Resources +* Custom Resource + +![Figure 17: Resources within Cluster](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/resource-list.jpg) + --- -## Terminal +## Cluster Terminal -User with [Super admins](./global-configurations/authorization/user-access.md#assign-super-admin-permission) access can now troubleshoot cluster issues by accessing the cluster terminal from Devtron. You can select an image from the list that has all CLI utilities like kubectl, helm, netshoot etc. or can use a custom image, which is publicly available. +User with [super-admin](./global-configurations/authorization/user-access.md#assign-super-admin-permission) access can now troubleshoot cluster issues by accessing the cluster terminal from Devtron. You can select an image from the list that has all CLI utilities like kubectl, helm, netshoot etc. or can use a custom image, which is publicly available. -To troubleshoot a cluster or a specific node in a cluster, click the terminal symbol on the right side. +To troubleshoot a cluster or a specific node in a cluster, click the terminal icon on the right side. -![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/cluster-terminal-access.jpg) +![Figure 18: Terminal Icon](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/cluster-terminal.gif) * You will see the user-defined name for the cluster in Devtron. E.g. `default-cluster`. -* In the `Nodes` field, select the node from the drop-down list you want to troubleshoot. E.g. `demo-new`. +* Select the node you wish to troubleshoot from the `Node` drop-down. E.g. `demo-new`. * Select the namespace from the drop-down list which you have added in the [Environment](./global-configurations/cluster-and-environments.md#add-environment) section. * Select the image from the drop-down list which includes all CLI utilities or you can use a custom image, which is publicly available. * Select the terminal shell from the drop-down list (e.g. `sh`, `bash`) to troubleshoot a node. - -### Example: Debug Pod +### Use Case - Debugging Pods You can also create pod for debugging which will connect to pod terminal. To find out why a particular pod is not running, you can check `Pod Events` and `Pod Manifest` for details. +The **Debug Mode** is helpful in scenarios where you can't access your Node by using an SSH connection. When enabled, a pod is created on the node, which opens an interactive shell on the Node. + * Check the current state of the Pod and recent events with the following command: ```bash @@ -220,15 +337,49 @@ kubectl describe pod | Waiting | Pod has been scheduled but cannot run | Failed to pull container image | | CrashLoopBackOff | Container keeps crashing and restarting | Incorrect access token for API interaction | - Here, you can see configuration information about the container(s) and Pod (labels, resource requirements, etc.), as well as status information about the container(s) and Pod (state, readiness, restart count, events, etc.). - - **Note**: A container can have no shells or multiple shells running in it. If you are unable to create a successful connection, try changing the shell, as the container may not have that shell running. +{% hint style="info" %} +A container can have no shells or multiple shells running in it. If you are unable to create a successful connection, try changing the shell, as the container may not have that shell running. +{% endhint %} --- ## Creating Resources - - +You can create one or more [Kubernetes objects](../reference/glossary.md#objects) in your cluster using YAML. In case you wish to create multiple objects, separate each resource definition by three dashes (---). + +Once you select a cluster in Resource Browser, click **+ Create Resource**, and add the resource definition. + +In the below example, we have created a simple pod named `nginx`: + +![Figure 19: Creating Resources within Cluster](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/create-resource.gif) + +Here's one more example that shows the required fields and object specifications for a Kubernetes Deployment: + +{% code title="Spec File" overflow="wrap" lineNumbers="true" %} + +```javascript +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-deployment + labels: + app: nginx +spec: + replicas: 2 + selector: + matchLabels: + app: nginx + template: + metadata: + labels: + app: nginx + spec: + containers: + - name: nginx + image: nginx:1.14.2 + ports: + - containerPort: 80 +``` +{% endcode %} From b154915ce99c3bf0d2b2fe3039c1db2b60dab603 Mon Sep 17 00:00:00 2001 From: ashokdevtron Date: Thu, 2 May 2024 18:31:25 +0530 Subject: [PATCH 4/8] Added new snaps and creatives for node operations --- docs/user-guide/resource-browser.md | 89 ++++++++++++++++++----------- 1 file changed, 56 insertions(+), 33 deletions(-) diff --git a/docs/user-guide/resource-browser.md b/docs/user-guide/resource-browser.md index f1ba69aea1..f0ec0bdf6e 100644 --- a/docs/user-guide/resource-browser.md +++ b/docs/user-guide/resource-browser.md @@ -53,7 +53,7 @@ You can also include additional information about your cluster using the Markdow ### Search and Filter -You can use the searchbox to browse the resources you are looking for. +You can use the searchbox to browse the resources. ![Figure 4: Locate Resources using Searchbox](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/discover-resource.gif) @@ -125,43 +125,56 @@ Further using the Devtron UI, you will be able to: * [Edit a Node Config](#edit-a-node-config) * [Delete a Node](#delete-a-node) -Your applications run on pods, and pods run on nodes. But sometimes, Kubernetes scheduler cannot deploy a pod on a node for several reasons, e.g., node is not ready, node is not reachable, network is unavailable, etc. +{% hint style="info" %} +### Why are node operations required? +Your applications run on pods, and pods run on nodes. But sometimes, Kubernetes scheduler cannot deploy a pod on a node for several reasons, e.g., node is not ready, node is not reachable, network is unavailable, etc. In such cases, node operations help you manage the nodes better. +{% endhint %} ### Debug a Node You can debug a node via [Cluster Terminal](#cluster-terminal) by selecting your namespace and image from the list that has all CLI utilities like kubectl, helm, netshoot etc. or can use a custom image, which is publicly available. -![Figure 10: Debugging a Node](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/node-terminal.png) +* Click **Debug**. -* Go to the **Clusters** section from the left navigation pane. -* Select your cluster. -* Search a node by name or label in the search bar. -* On the node, click the ellipsis button and then click **Terminal**. -* Debug a node by selecting the terminal shell `bash` or `sh`. + ![Figure 10a: Debugging a Node](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/debug.jpg) + +* Debug a node by selecting the terminal shell, i.e., `bash` or `sh`. + + ![Figure 10b: Debug Terminal](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/debug-terminal.jpg) ### Cordon a Node -Cordoning a node means making the node unschedulable. After cordoning a node, new Pods cannot be scheduled on this node. +Cordoning a node means making the node unschedulable. After cordoning a node, new pods cannot be scheduled on this node. -![Figure 11: Cordoning a Node](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/node-cordon.jpg) +![Figure 11a: Visual Representation - Cordoning a Node](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/cordon-visual.jpg) + +* Click **Cordon**. + + ![Figure 11b: Cordoning a Node](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/cordon.jpg) -* On the node, click the ellipsis button and then click **Cordon**. * A confirmation dialog box will appear, click **Cordon Node** to proceed. -* The status of the node shows `SchedulingDisabled` with `Unschedulable` parameter set as `true`. -Similarly, you can uncordon a node by clicking `Uncordon`. After a node is uncordoned, new Pods can be scheduled on the node. + ![Figure 11c: Cordon Confirmation](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/cordon-dialog.jpg) + +The status of the node shows `SchedulingDisabled` with `Unschedulable` parameter set as `true`. + +Similarly, you can uncordon a node by clicking `Uncordon`. After a node is uncordoned, new pods can be scheduled on the node. ### Drain a Node Before performing maintenance on a node, draining a node evicts all of your pods safely from a node. Safe evictions allow the pod’s containers to gracefully terminate and honour the `PodDisruptionBudgets` you have specified (if relevant). -After the node is drained, all Pods (including those managed by DaemonSets) in the node will be automatically drained to other nodes in the cluster, and the drained node will be set to cordoned status. +![Figure 12a: Visual Representation - Draining a Node](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/drain-visual.jpg) + +After the node is drained, all pods (including those managed by DaemonSets) in the node will be automatically drained to other nodes in the cluster, and the drained node will be set to cordoned status. -![Figure 12: Draining a Node](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/drain-node.jpg) +* Click **Drain**. + + ![Figure 12b: Draining a Node](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/drain.jpg) -* On the node, click the ellipsis button and then click **Drain**. * A confirmation dialog box will appear, click **Drain Node** to proceed. -* Click **Drain Node**. + + ![Figure 12c: Drain Confirmation](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/drain-dialog.jpg) You can also select from the following conditions before draining a node: @@ -177,15 +190,21 @@ You can also select from the following conditions before draining a node: Taints are `key:value` pairs associated with effect. After you add taints to nodes, you can set tolerations on a pod to allow the pod to be scheduled to nodes with certain taints. When you taint a node, it will repel all the pods except those that have a toleration for that taint. A node can have one or many taints associated with it. +![Figure 13a: Visual Representation - Tainting a Node](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/taint-visual.jpg) + **Note**: Make sure to check taint validations before you add a taint. -![Figure 13: Tainting a Node](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/edit-taints.jpg) +* Click **Edit taints**. + + ![Figure 13b: Tainting a Node](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/edit-taints.jpg) + +* Enter the `key:value` pairs and select the [taint effect](#taint-effects) from the drop-down list. + + ![Figure 13c: Adding Taints](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/taint-dialog.jpg) -* On the node, click the ellipsis button and then click **Edit taints**. -* Click **Add taint**. -* On the `Key` and `Value` fields, enter the `key:value` pairs and select the [taint effect](#taint-effects) from the drop-down list. * Click **Save**. -* You can also delete the added taint by clicking the delete button. + +You can also add more taints using **+ Add taint button**, or delete the existing taint by using the delete icon. #### Taint Effects @@ -201,7 +220,7 @@ A taint can produce three possible effects: `Edit node config` allows you to directly edit any node. It will open the editor which contains all the configuration settings in which the default format is YAML. You can edit multiple objects, although changes are applied one at a time. -![Figure 14: Editing Node Config](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/clusters/edit-yaml-node.jpg) +![Figure 14: Editing Node Config](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/edit-config.gif) * You can edit or modify the parameters or values of a node by clicking **Edit node config**. * Click **Review Changes** to compare the changes in the YAML file. @@ -213,6 +232,10 @@ A taint can produce three possible effects: * Search a node by name or label in the search bar. * On the node, click the ellipsis button and then click **Delete**. +![Figure 15a: Deleting a Node](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/delete-node.jpg) + +![Figure 15b: Delete Confirmation](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/delete-dialog.jpg) + The node will be deleted from the cluster. {% hint style="info" %} @@ -244,7 +267,7 @@ Moreover, you can download the pod logs for ease of sharing and troubleshooting In case any of your pod restarts, you can determine the cause by viewing its container log, time, status, node events in the pod listing screen as shown below: -![Figure 15: Checking Restart Pod Log](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/restart-pod-log.gif) +![Figure 16: Checking Restart Pod Log](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/restart-pod-log.gif) ### Terminal @@ -264,7 +287,7 @@ This is a part of [Pod Terminal](#pod-terminal). It is especially useful when `k You get 2 tabs: 1. **Basic** - It provides the bare minimum configurations required to launch an ephemeral container. - ![Figure 16: Basic Tab](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/debugging-deployment-and-monitoring/basic.jpg) + ![Figure 17: Basic Tab](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/debugging-deployment-and-monitoring/basic.jpg) It contains 3 mandatory fields: @@ -277,7 +300,7 @@ This is a part of [Pod Terminal](#pod-terminal). It is especially useful when `k 2. **Advanced** - It is particularly useful for advanced users that wish to use labels or annotations since it provides additional key-value options. Refer [Ephemeral Container Spec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#ephemeralcontainer-v1-core) to view the supported options. {% hint style="info" %} - Devtron ignores the `command` field while launching an ephemeral container + Devtron ignores the 'command' field while launching an ephemeral container {% endhint %} --- @@ -295,7 +318,7 @@ Other resources in the cluster are grouped under the following categories: * Other Resources * Custom Resource -![Figure 17: Resources within Cluster](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/resource-list.jpg) +![Figure 18: Resources within Cluster](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/resource-list.jpg) --- @@ -305,7 +328,7 @@ User with [super-admin](./global-configurations/authorization/user-access.md#ass To troubleshoot a cluster or a specific node in a cluster, click the terminal icon on the right side. -![Figure 18: Terminal Icon](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/cluster-terminal.gif) +![Figure 19: Terminal Icon](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/cluster-terminal.gif) * You will see the user-defined name for the cluster in Devtron. E.g. `default-cluster`. * Select the node you wish to troubleshoot from the `Node` drop-down. E.g. `demo-new`. @@ -319,7 +342,7 @@ You can also create pod for debugging which will connect to pod terminal. To fin The **Debug Mode** is helpful in scenarios where you can't access your Node by using an SSH connection. When enabled, a pod is created on the node, which opens an interactive shell on the Node. -* Check the current state of the Pod and recent events with the following command: +* Check the current state of the pod and recent events with the following command: ```bash kubectl get pods @@ -337,7 +360,7 @@ kubectl describe pod | Waiting | Pod has been scheduled but cannot run | Failed to pull container image | | CrashLoopBackOff | Container keeps crashing and restarting | Incorrect access token for API interaction | -Here, you can see configuration information about the container(s) and Pod (labels, resource requirements, etc.), as well as status information about the container(s) and Pod (state, readiness, restart count, events, etc.). +Here, you can see configuration information about the container(s) and pod (labels, resource requirements, etc.), as well as status information about the container(s) and pod (state, readiness, restart count, events, etc.). {% hint style="info" %} A container can have no shells or multiple shells running in it. If you are unable to create a successful connection, try changing the shell, as the container may not have that shell running. @@ -353,18 +376,18 @@ Once you select a cluster in Resource Browser, click **+ Create Resource**, and In the below example, we have created a simple pod named `nginx`: -![Figure 19: Creating Resources within Cluster](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/create-resource.gif) +![Figure 20: Creating Resources within Cluster](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/create-resource.gif) Here's one more example that shows the required fields and object specifications for a Kubernetes Deployment: {% code title="Spec File" overflow="wrap" lineNumbers="true" %} -```javascript +```yaml apiVersion: apps/v1 kind: Deployment metadata: name: nginx-deployment - labels: + labels: app: nginx spec: replicas: 2 From 3db86bfadd9f2a808a297a8f0acddaf65c440be9 Mon Sep 17 00:00:00 2001 From: ashokdevtron Date: Thu, 2 May 2024 19:49:28 +0530 Subject: [PATCH 5/8] RBAC Added --- docs/user-guide/resource-browser.md | 41 ++++++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/resource-browser.md b/docs/user-guide/resource-browser.md index f0ec0bdf6e..8482b5b675 100644 --- a/docs/user-guide/resource-browser.md +++ b/docs/user-guide/resource-browser.md @@ -41,16 +41,21 @@ This shows errors in the cluster. If no error is present in the cluster, Resourc ### Catalog Framework -Based on the schema provided in the catalog framework, you can add relevant details for each cluster. Refer [Catalog Framework](./global-configurations/catalog-framework.md) for more details. +Based on the schema provided in the catalog framework, you can add relevant details for each cluster. Refer [Catalog Framework](./global-configurations/catalog-framework.md) for more details. Users need to have super-admin permission to edit the catalog framework. ### Readme -You can also include additional information about your cluster using the Markdown editor. +You can also include additional information about your cluster using the Markdown editor. You will need superadmin permission to edit it. Users need to have super-admin permission to edit the readme file. --- ## Discovering Resources +{% hint style="warning" %} +### Who Can Perform These Actions? +Users need to have [access to the cluster](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to discover its resources. +{% endhint %} + ### Search and Filter You can use the searchbox to browse the resources. @@ -63,6 +68,11 @@ Moreover, you can use filters that allow you to quickly filter your workload as ### Edit Manifest +{% hint style="warning" %} +### Who Can Perform This Action? +Users need to have super-admin permission to edit a manifest. +{% endhint %} + You can edit the [manifest](../reference/glossary.md#manifest) of a Kubernetes object. This can be for fixing errors, scaling resources, or changing configuration. ![Figure 5: Editing a Live Manifest](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/edit-live-manifest.gif) @@ -75,6 +85,11 @@ You can monitor activities like creation, deletion, updation, scaling, or errors ### Delete +{% hint style="warning" %} +### Who Can Perform This Action? +Users need to have super-admin permission to delete a resource. +{% endhint %} + You can delete an unwanted resource if it is orphaned and no longer required by your applications. ![Figure 7: Deleting a Resource](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/delete.gif) @@ -126,10 +141,15 @@ Further using the Devtron UI, you will be able to: * [Delete a Node](#delete-a-node) {% hint style="info" %} -### Why are node operations required? +### Why Are Node Operations Required? Your applications run on pods, and pods run on nodes. But sometimes, Kubernetes scheduler cannot deploy a pod on a node for several reasons, e.g., node is not ready, node is not reachable, network is unavailable, etc. In such cases, node operations help you manage the nodes better. {% endhint %} +{% hint style="warning" %} +### Who Can Perform These Actions? +Users need to have super-admin permission to perform node operations. +{% endhint %} + ### Debug a Node You can debug a node via [Cluster Terminal](#cluster-terminal) by selecting your namespace and image from the list that has all CLI utilities like kubectl, helm, netshoot etc. or can use a custom image, which is publicly available. @@ -247,6 +267,11 @@ You can also access [Cluster Terminal](#cluster-terminal) from your node. ## Pods +{% hint style="warning" %} +### Who Can Perform These Actions? +Users need to have [access to the cluster](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to view its pods and its data. +{% endhint %} + ### Manifest Shows you the [configuration](../reference/glossary.md#manifest) of the selected pod and allows you to edit it. Refer [Edit Manifest](#edit-manifest) to know more. @@ -271,6 +296,11 @@ In case any of your pod restarts, you can determine the cause by viewing its con ### Terminal +{% hint style="warning" %} +### Who Can Perform These Actions? +Users need to have super-admin permission to access the pod terminal. +{% endhint %} + You can access the terminal within a running container of a pod to view its logs, troubleshoot issues, or execute commands directly. This is different from the [cluster terminal](#cluster-terminal) you get at node level. #### Launching Ephemeral Container @@ -370,6 +400,11 @@ A container can have no shells or multiple shells running in it. If you are unab ## Creating Resources +{% hint style="warning" %} +### Who Can Perform These Actions? +Users need to have super-admin permission to create resources. +{% endhint %} + You can create one or more [Kubernetes objects](../reference/glossary.md#objects) in your cluster using YAML. In case you wish to create multiple objects, separate each resource definition by three dashes (---). Once you select a cluster in Resource Browser, click **+ Create Resource**, and add the resource definition. From 1438f34d87afd9b55aef7ce89a430e7dca5a035c Mon Sep 17 00:00:00 2001 From: ashokdevtron Date: Thu, 2 May 2024 19:54:55 +0530 Subject: [PATCH 6/8] Fixes --- docs/user-guide/resource-browser.md | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/user-guide/resource-browser.md b/docs/user-guide/resource-browser.md index 8482b5b675..d32abc74d6 100644 --- a/docs/user-guide/resource-browser.md +++ b/docs/user-guide/resource-browser.md @@ -41,19 +41,29 @@ This shows errors in the cluster. If no error is present in the cluster, Resourc ### Catalog Framework -Based on the schema provided in the catalog framework, you can add relevant details for each cluster. Refer [Catalog Framework](./global-configurations/catalog-framework.md) for more details. Users need to have super-admin permission to edit the catalog framework. +{% hint style="warning" %} +### Who Can Perform This Action? +Users need to have super-admin permission to edit the catalog framework. +{% endhint %} + +Based on the schema provided in the catalog framework, you can add relevant details for each cluster. Refer [Catalog Framework](./global-configurations/catalog-framework.md) for more details. ### Readme -You can also include additional information about your cluster using the Markdown editor. You will need superadmin permission to edit it. Users need to have super-admin permission to edit the readme file. +{% hint style="warning" %} +### Who Can Perform This Action? +Users need to have super-admin permission to edit the readme file. +{% endhint %} + +You can also include additional information about your cluster using the Markdown editor. --- ## Discovering Resources {% hint style="warning" %} -### Who Can Perform These Actions? -Users need to have [access to the cluster](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to discover its resources. +### Who Can Perform This Action? +Users need to have [access to the cluster](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to discover resources. {% endhint %} ### Search and Filter @@ -268,7 +278,7 @@ You can also access [Cluster Terminal](#cluster-terminal) from your node. ## Pods {% hint style="warning" %} -### Who Can Perform These Actions? +### Who Can Perform This Action? Users need to have [access to the cluster](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to view its pods and its data. {% endhint %} @@ -297,7 +307,7 @@ In case any of your pod restarts, you can determine the cause by viewing its con ### Terminal {% hint style="warning" %} -### Who Can Perform These Actions? +### Who Can Perform This Action? Users need to have super-admin permission to access the pod terminal. {% endhint %} @@ -401,7 +411,7 @@ A container can have no shells or multiple shells running in it. If you are unab ## Creating Resources {% hint style="warning" %} -### Who Can Perform These Actions? +### Who Can Perform This Action? Users need to have super-admin permission to create resources. {% endhint %} From 54782c0f68f6bdce489e2b33103cb1bd95fa386f Mon Sep 17 00:00:00 2001 From: ashokdevtron <141001279+ashokdevtron@users.noreply.github.com> Date: Wed, 8 May 2024 11:54:01 +0000 Subject: [PATCH 7/8] Incorporated PM Feedback + Fixed RBAC --- docs/user-guide/resource-browser.md | 71 ++++++++++++++--------------- 1 file changed, 35 insertions(+), 36 deletions(-) diff --git a/docs/user-guide/resource-browser.md b/docs/user-guide/resource-browser.md index d32abc74d6..5c6c7668a7 100644 --- a/docs/user-guide/resource-browser.md +++ b/docs/user-guide/resource-browser.md @@ -4,6 +4,12 @@ The Devtron Resource Browser provides you a central interface to view and manage all your [Kubernetes objects](../../reference/glossary.md#objects) across clusters. It helps you perform key actions like viewing logs, editing live manifests, and even creating/deleting resources directly from the user interface. This is especially useful for troubleshooting purposes as it supports multi-cluster too. +{% hint style="info" %} +### Additional References +* [Resource browser versus traditional tools like kubectl](https://devtron.ai/blog/managing-kubernetes-resources-across-multiple-clusters) +* [Why you should use Devtron's Resource Browser](https://devtron.ai/blog/what-is-the-kubernetes-resource-browser-in-devtron) +{% endhint %} + First, the Resource Browser shows you a list of clusters added to your Devtron setup. By default, it displays a cluster named '*default_cluster*' after the [initial setup](../../setup/install/README.md) is successful. ![Figure 1: Devtron Resource Browser - List of Clusters](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/resource-browser.jpg) @@ -29,11 +35,11 @@ This shows the combined CPU and memory consumption of all running pods in the cl | CPU Usage | Percentage of CPU resources currently being used across all the pods in the cluster. | | CPU Capacity | Total amount of CPU resources available across all the nodes in the cluster. Measured in millicores (m). | | CPU Requests | Total amount of CPU resources requested by all the pods in the cluster. | -| CPU Limits | Maximum amount of CPU resources that a pod can use. | +| CPU Limits | Maximum amount of CPU resources that a total number of pods can use in the cluster. | | Memory Usage | Percentage of memory resources currently being used across all the pods in the cluster. | | Memory Capacity | Total amount of memory resources available across all the nodes in the cluster. Measured in Megabytes (Mi). | | Memory Requests | Total amount of memory resources requested by all the pods in the cluster. | -| Memory Limits | Maximum amount of memory resources that a pod can use. | +| Memory Limits | Maximum amount of memory resources that a total number of pods can use in the cluster. | ### Errors @@ -80,7 +86,7 @@ Moreover, you can use filters that allow you to quickly filter your workload as {% hint style="warning" %} ### Who Can Perform This Action? -Users need to have super-admin permission to edit a manifest. +Users need to be [admin of the Kubernetes resource](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to edit its manifest. {% endhint %} You can edit the [manifest](../reference/glossary.md#manifest) of a Kubernetes object. This can be for fixing errors, scaling resources, or changing configuration. @@ -97,18 +103,13 @@ You can monitor activities like creation, deletion, updation, scaling, or errors {% hint style="warning" %} ### Who Can Perform This Action? -Users need to have super-admin permission to delete a resource. +Users need to be [admin of the Kubernetes resource](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to delete it. {% endhint %} You can delete an unwanted resource if it is orphaned and no longer required by your applications. ![Figure 7: Deleting a Resource](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/delete.gif) -You can perform all the actions on the following: -* [Nodes](#nodes) -* [Pods](#pods) -* [Other Resource Kinds](#other-resource-kinds) - --- ## Nodes @@ -123,12 +124,13 @@ If you have multiple nodes, you can search a node by name or label in the search | Fields | Description | | --- | --- | -| Node | User-defined name for the node in Devtron. E.g. `demo-new`.
Note: Two nodes cannot have the same name at the same time.
| +| Node | Alphanumeric name of the node | | Status | Status of a node. It can be either `Ready` or `Not Ready`. | -| Roles | Shows the roles of a node. | -| Errors | Shows the error in nodes. | -| K8s Version | Shows the version of Kubernetes cluster. | -| Node Group | Shows which collection of worker nodes it belongs to. | +| Roles | Shows the roles of a node, e.g., agent | +| Errors | Shows the number of errors in nodes (if any) | +| K8s Version | Shows the version of Kubernetes cluster | +| Node Group | Shows which collection of worker nodes it belongs to | +| No. of Pods | Shows the total number of pods present in the node | Clicking on a node shows you a number of details such as: @@ -234,17 +236,12 @@ Taints are `key:value` pairs associated with effect. After you add taints to nod * Click **Save**. -You can also add more taints using **+ Add taint button**, or delete the existing taint by using the delete icon. - -#### Taint Effects - -A taint can produce three possible effects: +You can also add more taints using **+ Add taint button**, or delete the existing taint by using the delete icon. -| Effect | Description | -| --- | --- | -| NoSchedule | The Kubernetes scheduler will only allow scheduling pods that have tolerations for the tainted nodes. | -| PreferNoSchedule | The Kubernetes scheduler will try to avoid scheduling pods that do not have tolerations for the tainted nodes. | -| NoExecute | Kubernetes will evict the running pods from the nodes if the pods do not have tolerations for the tainted nodes. | +{% hint style="info" %} +### Additional Reference +[Click here](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/#concepts) to read about taint effects. +{% endhint %} ### Edit a Node Config @@ -298,9 +295,15 @@ Moreover, you can download the pod logs for ease of sharing and troubleshooting {% embed url="https://www.youtube.com/watch?v=PP0ZKAZCT58" caption="Downloading Pod Logs" %} -#### Last Restart Pod Log +#### Pod Last Restart Snapshot -In case any of your pod restarts, you can determine the cause by viewing its container log, time, status, node events in the pod listing screen as shown below: +Frequent pod restarts can impact your application as it might lead to an unexpected downtime. In such cases, it is important to determine the root cause and take actions (both preventive and corrective) if needed. + +In case any of your pod restarts, you can view its details from the pod listing screen: +* Last pod restart event, along with timestamp and message +* Reason behind restart +* Container log before restart +* Node status and events ![Figure 16: Checking Restart Pod Log](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/restart-pod-log.gif) @@ -308,7 +311,7 @@ In case any of your pod restarts, you can determine the cause by viewing its con {% hint style="warning" %} ### Who Can Perform This Action? -Users need to have super-admin permission to access the pod terminal. +Users need to be [admin of the Kubernetes resource](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to access pod terminal. {% endhint %} You can access the terminal within a running container of a pod to view its logs, troubleshoot issues, or execute commands directly. This is different from the [cluster terminal](#cluster-terminal) you get at node level. @@ -380,7 +383,9 @@ To troubleshoot a cluster or a specific node in a cluster, click the terminal ic You can also create pod for debugging which will connect to pod terminal. To find out why a particular pod is not running, you can check `Pod Events` and `Pod Manifest` for details. -The **Debug Mode** is helpful in scenarios where you can't access your Node by using an SSH connection. When enabled, a pod is created on the node, which opens an interactive shell on the Node. +The **Auto select** option selects a node automatically from a list of nodes, and then creates a pod. + +The **Debug Mode** is helpful in scenarios where you can't access your Node by using an SSH connection. When enabled, a pod is created on the selected node, which opens an interactive shell on the Node. * Check the current state of the pod and recent events with the following command: @@ -394,13 +399,7 @@ kubectl get pods kubectl describe pod ``` -| Pod Status | Description | Common Causes | -| ---------------- | --------------------------------------- | ------------------------------------------ | -| Pending | Pod cannot be scheduled onto a node | Insufficient resources (CPU, memory, etc.) | -| Waiting | Pod has been scheduled but cannot run | Failed to pull container image | -| CrashLoopBackOff | Container keeps crashing and restarting | Incorrect access token for API interaction | - -Here, you can see configuration information about the container(s) and pod (labels, resource requirements, etc.), as well as status information about the container(s) and pod (state, readiness, restart count, events, etc.). +Here, you can see configuration information about the container(s) and pod (labels, resource requirements, etc.), as well as status information about the container(s) and pod (state, readiness, restart count, events, etc.). [Click here](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/) to know more about pod lifecycle. {% hint style="info" %} A container can have no shells or multiple shells running in it. If you are unable to create a successful connection, try changing the shell, as the container may not have that shell running. @@ -412,7 +411,7 @@ A container can have no shells or multiple shells running in it. If you are unab {% hint style="warning" %} ### Who Can Perform This Action? -Users need to have super-admin permission to create resources. +Users need to be [admin of the Kubernetes resources](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to create resources. {% endhint %} You can create one or more [Kubernetes objects](../reference/glossary.md#objects) in your cluster using YAML. In case you wish to create multiple objects, separate each resource definition by three dashes (---). From 792a1e9fdb48b66f703a082d3f8f785d05b8c8db Mon Sep 17 00:00:00 2001 From: ashokdevtron <141001279+ashokdevtron@users.noreply.github.com> Date: Tue, 14 May 2024 11:18:15 +0000 Subject: [PATCH 8/8] Added links + Proofreading + Fixes --- docs/user-guide/resource-browser.md | 41 ++++++++++++++--------------- 1 file changed, 20 insertions(+), 21 deletions(-) diff --git a/docs/user-guide/resource-browser.md b/docs/user-guide/resource-browser.md index 5c6c7668a7..6385bb0237 100644 --- a/docs/user-guide/resource-browser.md +++ b/docs/user-guide/resource-browser.md @@ -86,7 +86,7 @@ Moreover, you can use filters that allow you to quickly filter your workload as {% hint style="warning" %} ### Who Can Perform This Action? -Users need to be [admin of the Kubernetes resource](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to edit its manifest. +User needs to be an [admin of the Kubernetes resource](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to edit its manifest. {% endhint %} You can edit the [manifest](../reference/glossary.md#manifest) of a Kubernetes object. This can be for fixing errors, scaling resources, or changing configuration. @@ -95,7 +95,7 @@ You can edit the [manifest](../reference/glossary.md#manifest) of a Kubernetes o ### View Events -You can monitor activities like creation, deletion, updation, scaling, or errors in the resources involved. +You can monitor activities like creation, deletion, updation, scaling, or errors in the resources involved. Refer [Events](https://kubernetes.io/docs/reference/kubernetes-api/cluster-resources/event-v1/) to learn more. ![Figure 6: Viewing All Events](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/events.gif) @@ -103,7 +103,7 @@ You can monitor activities like creation, deletion, updation, scaling, or errors {% hint style="warning" %} ### Who Can Perform This Action? -Users need to be [admin of the Kubernetes resource](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to delete it. +User needs to be an [admin of the Kubernetes resource](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to delete it. {% endhint %} You can delete an unwanted resource if it is orphaned and no longer required by your applications. @@ -118,7 +118,7 @@ You can see the list of nodes available in your cluster. Typically you have seve The components on a typical node include the `kubelet`, a `container runtime`, and the `kube-proxy`. -If you have multiple nodes, you can search a node by name or label in the search bar. The search result will display the following information of the node. To display a parameter of a node, use `Columns` on the right side, select the parameter to display from the drop-down list, and click **Apply**. +If you have multiple nodes, you can search a node by name or label in the search bar. The search result will display the following information about the node. To display a parameter of a node, use `Columns` on the right side, select the parameter to display from the drop-down list, and click **Apply**. ![Figure 8: Searching and Filtering Nodes](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/cluster-nodes.jpg) @@ -176,7 +176,7 @@ You can debug a node via [Cluster Terminal](#cluster-terminal) by selecting your ### Cordon a Node -Cordoning a node means making the node unschedulable. After cordoning a node, new pods cannot be scheduled on this node. +Cordoning a node means making the node unschedulable. After [cordoning a node](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_cordon/), new pods cannot be scheduled on this node. ![Figure 11a: Visual Representation - Cordoning a Node](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/cordon-visual.jpg) @@ -194,7 +194,7 @@ Similarly, you can uncordon a node by clicking `Uncordon`. After a node is uncor ### Drain a Node -Before performing maintenance on a node, draining a node evicts all of your pods safely from a node. Safe evictions allow the pod’s containers to gracefully terminate and honour the `PodDisruptionBudgets` you have specified (if relevant). +Before performing maintenance on a node, [draining a node](https://kubernetes.io/docs/tasks/administer-cluster/safely-drain-node/) evicts all of your pods safely from a node. Safe evictions allow the pod’s containers to gracefully terminate and honour the `PodDisruptionBudgets` you have specified (if relevant). ![Figure 12a: Visual Representation - Draining a Node](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/drain-visual.jpg) @@ -245,19 +245,19 @@ You can also add more taints using **+ Add taint button**, or delete the existin ### Edit a Node Config -`Edit node config` allows you to directly edit any node. It will open the editor which contains all the configuration settings in which the default format is YAML. You can edit multiple objects, although changes are applied one at a time. +This allows you to directly edit any node. It will open the editor which contains all the configuration settings in which the default format is YAML. You can edit multiple objects, although changes are applied one at a time. ![Figure 14: Editing Node Config](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/edit-config.gif) -* You can edit or modify the parameters or values of a node by clicking **Edit node config**. -* Click **Review Changes** to compare the changes in the YAML file. -* Click **Update Node**. +* Go to the `YAML` tab and click **Edit YAML**. +* Make the changes using the editor. +* Click **Review & Save changes** to compare the changes in the YAML file. +* Click **Apply changes** to confirm. ### Delete a Node -* Search a node by name or label in the search bar. -* On the node, click the ellipsis button and then click **Delete**. +You can also delete a node by clicking the **Delete** button present on the right-hand side. ![Figure 15a: Deleting a Node](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/delete-node.jpg) @@ -269,7 +269,6 @@ The node will be deleted from the cluster. You can also access [Cluster Terminal](#cluster-terminal) from your node. {% endhint %} - --- ## Pods @@ -281,7 +280,7 @@ Users need to have [access to the cluster](./global-configurations/authorization ### Manifest -Shows you the [configuration](../reference/glossary.md#manifest) of the selected pod and allows you to edit it. Refer [Edit Manifest](#edit-manifest) to know more. +Shows you the [configuration](../reference/glossary.md#manifest) of the selected pod and allows you to edit it. Refer [Edit Manifest](#edit-manifest) to learn more. ### Events @@ -297,10 +296,10 @@ Moreover, you can download the pod logs for ease of sharing and troubleshooting #### Pod Last Restart Snapshot -Frequent pod restarts can impact your application as it might lead to an unexpected downtime. In such cases, it is important to determine the root cause and take actions (both preventive and corrective) if needed. +Frequent pod restarts can impact your application as it might lead to unexpected downtimes. In such cases, it is important to determine the root cause and take actions (both preventive and corrective) if needed. In case any of your pod restarts, you can view its details from the pod listing screen: -* Last pod restart event, along with timestamp and message +* Last pod restart event, along with the timestamp and message * Reason behind restart * Container log before restart * Node status and events @@ -311,7 +310,7 @@ In case any of your pod restarts, you can view its details from the pod listing {% hint style="warning" %} ### Who Can Perform This Action? -Users need to be [admin of the Kubernetes resource](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to access pod terminal. +User needs to be an [admin of the Kubernetes resource](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to access pod terminal. {% endhint %} You can access the terminal within a running container of a pod to view its logs, troubleshoot issues, or execute commands directly. This is different from the [cluster terminal](#cluster-terminal) you get at node level. @@ -381,11 +380,11 @@ To troubleshoot a cluster or a specific node in a cluster, click the terminal ic ### Use Case - Debugging Pods -You can also create pod for debugging which will connect to pod terminal. To find out why a particular pod is not running, you can check `Pod Events` and `Pod Manifest` for details. +You can also create a pod for debugging which will connect to the pod terminal. To find out why a particular pod is not running, you can check `Pod Events` and `Pod Manifest` for details. -The **Auto select** option selects a node automatically from a list of nodes, and then creates a pod. +The **Auto select** option automatically selects a node from a list of nodes and then creates a pod. Alternatively, you can choose a node of your choice from the same dropdown for debugging. -The **Debug Mode** is helpful in scenarios where you can't access your Node by using an SSH connection. When enabled, a pod is created on the selected node, which opens an interactive shell on the Node. +The **Debug Mode** is helpful in scenarios where you can't access your node by using an SSH connection. Enabling this feature opens an interactive shell directly on the node. This shell provides unrestricted access to the node, giving you enhanced debugging capabilities. * Check the current state of the pod and recent events with the following command: @@ -411,7 +410,7 @@ A container can have no shells or multiple shells running in it. If you are unab {% hint style="warning" %} ### Who Can Perform This Action? -Users need to be [admin of the Kubernetes resources](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to create resources. +User needs to be an [admin of the Kubernetes resources](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to create resources. {% endhint %} You can create one or more [Kubernetes objects](../reference/glossary.md#objects) in your cluster using YAML. In case you wish to create multiple objects, separate each resource definition by three dashes (---).