# Introduction Kubo Labs delivers a powerful toolset that help you identify and solve issues on your Kubernetes clusters. Kubernetes can be **complex and cumbersome** sometimes. With our products, most of the **painful points** of its day-to-day management can be addressed, while bringing you closer to meeting **best practices and recommendations** at the same time. Start to **identify issues** on your clusters with a **free** [**KuboScore**](https://www.kuboscore.io/) **report** and 15 days of **free trial** – *no credit card required* – on [**KuboVisor**](https://www.kubovisor.io/)!
Discover KuboScore/pages/sEiawvQ5snNanQyHJGGa/files/TrVea3s1GeZHOoQpix0r
Discover KuboVisor/pages/5VbTWboZzaj82bxiOaO8/files/A2IsxdCjWov8uFJrtFZz
# KuboScore Identify problems and misconfigurations on your Kubernetes cluster, without the expertise. {% hint style="info" %} **Looking to get started with KuboScore?** Head to the [getting started](/getting-started/kuboscore) page. {% endhint %}
KuboScore runs multiple scenarios on your clusters to check for potential **misconfigurations and bad practices** that will lead to **security incidents or performance issues**. These scenarios are based on our extensive consulting experiences and years of practice. We crafted some **real life scenarios** that can be executed on your cluster to audit its **state, health, security level, configuration**, and much more. It’s **free to use**, [**start analyzing your cluster configuration right away**](https://www.kuboscore.io/)**!** ## Features ### Real-life scenarios KuboScore will run various scenarios that will check the configuration of: * general cluster components * core Kubernetes features for applications * applications communications and traffic restrictions * external traffic support * Kubernetes restrictions mechanisms * cloud services interconnections * storage support * security and compliance with security best practices * important administrative features * cluster configuration and availability of important add-ons * existing workloads’ health and compliance with best practices It will take about **20 to 30 minutes** to perform a complete analysis.

Follow an ongoing analysis (cloud mode).

### Review the results At the end of the process, you will be provided with a **global score** and some details regarding the scenarios that passed or failed.

Example of a free KuboScore page results.

### Get your report For more in-depth details about each scenario – like root causes, potential consequences or how to fix – you can purchase a **professional report** as well as an **enterprise grade report** to help you investigate and resolve reported configuration issues.

Excerpt from a professional report.

## How does it work? KuboScore is available in two different modes: * **cloud** mode * **local** mode ### Cloud mode In **cloud mode**, we use the **Kubernetes API** to connect to your cluster and run our scenarios. Your cluster must be **publicly** reachable or behind a [*SSH bastion* to which we can connect](/guides/grant-access-to-a-private-network).

Connect KuboScore to your cluster.

### Standalone mode With KuboScore in **local mode**, you can perform a scoring of **any** cluster, as long as **you** can reach it. You just need to install [KuboScore CLI](/getting-started/kuboscore/local-mode) and run it with [sufficient privileges on your cluster](/getting-started/kuboscore/cloud-mode#permissions)! At the end of the scoring, you will get a **file** containing the **scoring results**. You can import this file in [KuboScore](https://kuboscore.io) to **review your results** and **get your report**.

Follow an ongoing analysis (local mode).

*** When the analysis is running, whatever mode you chose, **a bunch of resources will be created** on your cluster in order to **assess its state**. You will be able to **follow the execution** and see the **scenarios outcome**. **Resources that we create are deleted** at the end of the scenarios, by the end of the analysis your cluster will be left **as if we were never there!** # KuboVisor Detect emerging issues before they spread out and affect your applications. {% hint style="info" %} **Looking to get started with KuboVisor?** Head to the [getting started](/getting-started/kubovisor) page. {% endhint %}
Thanks to **real time** scanning and a beautifully crafted dashboard, KuboVisor identifies **pods anomalies**, **failed deployments** and other **health issues** of all your Kubernetes clusters **in one place**, with the context you need to troubleshoot efficiently your clusters. Keep an eye on all your **clusters’ health** and **be notified** as soon as an issue occurs! You can set your **own triggers** to decide when we should send you an alert. Emails, in-app and system notifications are supported so you **never gets startled** when something goes wrong! Take advantage of our free trial and [**start detecting issues on your clusters**](https://kubovisor.io)! ## Features ### One view to rule them all With KuboVisor, you will be able to see **6 key issues** indicators – system health, nodes availability, CPU and RAM usage, workload health and reservation state – for **all your cluster in one place**, whether your cluster is on a **private or public cloud**. This overview allows you to **quickly know which one of your clusters needs your immediate attention**.

See all your clusters.

### Troubleshoot with context Once you know which cluster needs your attention, you will be able to **see in detail the ongoing issues** on that cluster. For each issue, you will be provided the following information: * issue **description** * potential **consequences** if not solved * the list of **involved/affected ressources** * **fixing** guidance and tips

Get details of a cluster.

### Hassle free with alerting You can set up notifications to be **alerted by email in case of problems**.

Configure your alerts preferences.

### Take control with custom settings If our defaults do not suit your needs, you can set custom **indicator triggers** and **resources filters** to your taste.

Set custom indicators triggers.

Set custom filters.

### Resolve issues like a pro If an **issue is spotted**, we will give you some **leads and advice to fix it**.

Fix issues.

### Experts at your fingertips If you cannot resolve the issue by yourself, we are always **happy to help**! You can **contact our experts** by email or via our in-app chat.

Discussion with one of our experts.

## How does it work? We use the **Kubernetes API** to connect to your cluster and gather the data we need. In the eventuality that your cluster is only accessible through a **SSH tunnel**, do not worry: we got that covered, too. In order to be as **disturbingless** as possible, we only **get the data when we need to**. This process only takes **a few seconds and will not disrupt** your existing workload. We then process the results on **our servers** before handing them to you in our user interface. # KuboScore Identify problems and misconfigurations on your Kubernetes cluster, without the expertise. The **easiest way** to enjoy KuboScore is to use our [**cloud mode**](/getting-started/kuboscore/cloud-mode), you only need: * a publicly reachable cluster (with optional SSH authentication) * a *kubeconfig* file with sufficient permissions to run our scenarios However, if your cluster is completely private or you don’t want to provide us with your cluster credentials, you can still use the [**local mode**](/getting-started/kuboscore/local-mode) of KuboScore. In this mode, **you interact** with a command line interface to launch our scenarios from **your machine**. # Cloud mode Run KuboScore on your cluster in cloud mode. {% hint style="warning" %} The following content assumes you have [**`kubectl` binary**](https://kubernetes.io/docs/tasks/tools/#kubectl) **installed**, as well as a **privileged access** to your cluster. {% endhint %} {% hint style="info" %} If you already have a *kubeconfig* file with enough [permissions](#permissions), you can [score your cluster](#score-your-cluster) right away! {% endhint %} ## :construction\_worker: Service account We recommend to create a specific ***ServiceAccount*** object in your cluster to authenticate KuboScore and grant it specific permissions, but nothing prevents you from using an already existing *ServiceAccount*. In this example, the *ServiceAccount* `ksa-kuboscore` will be created in the `default` *Namespace*. You are free to rename the *ServiceAccount* and/or to create it in another *Namespace*. ```bash kubectl create serviceaccount ksa-kuboscore --namespace default ``` {% hint style="warning" %} **Kubernetes ≥ 1.24** If your cluster version equals or is over 1.24 (or if you have the *`LegacyServiceAccountTokenNoAutoGeneration`* feature gate enabled), you will have to manually generate an authentication token for the *ServiceAccount*. To get your cluster’s Kubernetes version, you can use this `kubectl` command: ```bash kubectl version --short=true ``` To generate an authentication token for the *ServiceAccount*, you need to create a *Secret* defined by the following YAML. Save its content in a **`kuboscore-secret.yaml`** file: ```yaml apiVersion: v1 kind: Secret metadata: namespace: default name: ksa-kuboscore annotations: kubernetes.io/service-account.name: ksa-kuboscore type: kubernetes.io/service-account-token ``` Apply the *Secret* on your cluster to generate the *ServiceAccount* token: ```bash kubectl apply -f kuboscore-secret.yaml ``` {% endhint %} References: * [Managing Service Accounts](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/) * [Service account tokens](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#service-account-tokens) * [ServiceAccount reference](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/service-account-v1/) ## :scales: Permissions {% hint style="info" %} If you are using an already existing *ServiceAccount* that has broader permissions than what is listed below, you can skip this section. {% endhint %} KuboScore needs some privileges to be able to perform its analysis, therefore we need to create a ***ClusterRole*** and a ***ClusterRoleBinding*** object. You will find below the *ClusterRole* definition. Create a new file called `kuboscore-clusterrole.yaml` and paste the content of this definition in it: {% code title="kuboscore-clusterrole.yaml" lineNumbers="true" %} ```yaml apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: kuboscore rules: - apiGroups: - '*' resources: - '*' verbs: - list - get - apiGroups: - '*' resources: - configmaps - daemonsets - deployments - horizontalpodautoscalers - limitranges - namespaces - networkpolicies - persistentvolumeclaims - pods - pods/exec - pods/portforward - resourcequotas - secrets - services - statefulsets verbs: - create - delete - nonResourceURLs: - /metrics verbs: - get ``` {% endcode %} Likewise, create a `kuboscore-clusterrolebinding.yaml` file and paste the content of the following *ClusterRoleBinding* definition in it: {% hint style="warning" %} If you want to use a different *ServiceAccount*, update the values of `subjects[0].name` and `subjects[0].namespace` to match your *ServiceAccount* name and its *Namespace*. {% endhint %} {% code title="kuboscore-clusterrolebinding.yaml" lineNumbers="true" %} ```yaml apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: kuboscore roleRef: apiGroup: rbac.authorization.k8s.io kind: ClusterRole name: kuboscore subjects: - kind: ServiceAccount name: ksa-kuboscore apiGroup: '' namespace: default ``` {% endcode %} References: * [Using RBAC Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) * [ClusterRole reference](https://kubernetes.io/docs/reference/kubernetes-api/authorization-resources/cluster-role-v1/) * [ClusterRoleBinding reference](https://kubernetes.io/docs/reference/kubernetes-api/authorization-resources/cluster-role-binding-v1/) ## :key: Generate your *kubeconfig* {% hint style="warning" %} If you want to use a different *ServiceAccount*, update the parameters provided to the script to match your *ServiceAccount* name and its *Namespace*. {% endhint %} ```bash curl -sO https://download.kubolabs.io/scripts/create_kubeconfig chmod +x create_kubeconfig ./create_kubeconfig ksa-kuboscore --namespace default ``` ## :rocket: Score your cluster To score your cluster, we need to be able to reach it. You will find below the network restrictions that we support: | Restriction | Supported | Comment | | ----------------- | :------------------: | -------------------------------------------------------------------------------- | | None | :white\_check\_mark: | — | | Network whitelist | :white\_check\_mark: | Add the following IP to the list of authorized networks: **34.141.253.143**. | | SSH bastion | :white\_check\_mark: | [Learn how you can grant us access](/guides/grant-access-to-a-private-network) | | Fully private | :x: | Use KuboScore in [**local mode**](/getting-started/kuboscore/local-mode) instead | Once access to your cluster is configured, scoring it is pretty easy: 1. Go to [KuboScore](https://www.kuboscore.io) 2. Signing to your account 3. Upload your *kubeconfig* file 4. Fill in the form 5. Launch the scoring! ### How to fill the form?

Cluster credentials form.

On the cluster credentials form, we ask you for a bunch of information to be able to connect to your cluster. **Cluster description** This is a description that you can set to quickly find your cluster among other analysis. **Kubeconfig file** This is the *kubeconfig* file you should have generated for the [service account that we created in the prerequisites section](#service-account). {% hint style="info" %} If your cluster sits in a private network only reachable through a bastion host, you must tick the **« This cluster is only reachable through an SSH tunnel »** checkbox and add the following additional information. {% endhint %} **Bastion host** This is the IP address or DNS hostname on which your bastion is publicly exposed. **Bastion port** This is the port used for SSH connections by your bastion. **Bastion login** This is the user login that we should use to authenticate on your bastion. If you followed [our guide](/guides/grant-access-to-a-private-network) to the letter, it should be `kubolabs`. **Bastion SSH key** This is the SSH private key that was generated through [our guide](/guides/grant-access-to-a-private-network) for the `kubolabs` user. **KubeApi address** This is the Kubernetes API endpoint to use **from inside your network** in the following form: ``` protocol://hostname:port ``` Example: ``` https://10.1.1.10:6443 ``` # Local mode Run KuboScore directly from your local machine with kuboscore-cli. {% hint style="warning" %} The following content assumes you have [**`kubectl` binary**](https://kubernetes.io/docs/tasks/tools/#kubectl) **installed**, as well as a **privileged access** to your cluster. {% endhint %} ## Get KuboScore [Download KuboScore CLI](https://www.kuboscore.io/client) on a machine that has access to your cluster. {% tabs %} {% tab title="Linux" %} ```bash # Retrieve KuboScore CLI latest version string export KS_VERSION=$(curl -s https://download.kuboscore.io/binaries/kuboscore-cli-latest.txt) # Download latest version of KuboScore CLI with curl curl -O https://download.kuboscore.io/binaries/kuboscore-cli-$KS_VERSION-linux-amd64 # Allow binary execution chmod +x ./kuboscore-cli-$KS_VERSION-linux-amd64 ``` {% endtab %} {% tab title="MacOS" %} ```bash # Retrieve KuboScore CLI latest version string export KS_VERSION=$(curl -s https://download.kuboscore.io/binaries/kuboscore-cli-latest.txt) # Download latest version of KuboScore CLI with curl curl -O https://download.kuboscore.io/binaries/kuboscore-cli-$KS_VERSION-darwin-amd64 # Allow binary execution chmod +x ./kuboscore-cli-$KS_VERSION-darwin-amd64 ``` {% endtab %} {% tab title="Windows (PowerShell)" %} ```powershell # Retrieve KuboScore CLI latest version string Set-Variable -Name "KSVersion" -Value (Invoke-WebRequest -UseBasicParsing -URI https://download.kuboscore.io/binaries/kuboscore-cli-latest.txt).Content # Download latest version of KuboScore CLI with Invoke-WebRequest Invoke-WebRequest -URI "https://download.kuboscore.io/binaries/kuboscore-cli-$(Get-Variable -Name "KSVersion" -ValueOnly)-windows.exe" -OutFile ".\kuboscore-cli-$(Get-Variable -Name "KSVersion" -ValueOnly)-windows.exe" ``` {% endtab %} {% endtabs %} > Note: you can check the integrity of your download with the following [checksum file](https://download.kuboscore.io/binaries/sha256.sum). ## Usage {% tabs %} {% tab title="Linux" %} ```bash # Execute KuboScore CLI ./kuboscore-cli-$KS_VERSION-linux-amd64 --kubeconfig ~/.kube/config ``` {% endtab %} {% tab title="MacOS" %} ```bash # Execute KuboScore CLI ./kuboscore-cli-$KS_VERSION-darwin-amd64 --kubeconfig ~/.kube/config ``` {% endtab %} {% tab title="Windows (PowerShell)" %} ```powershell # Retrieve KuboScore CLI latest version string Set-Variable -Name "KSVersion" -Value (Invoke-WebRequest -UseBasicParsing -URI https://download.kuboscore.io/binaries/kuboscore-cli-latest.txt).Content # Execute KuboScore CLI .\kuboscore-cli-$(Get-Variable -Name "KSVersion" -ValueOnly)-windows.exe ` --kubeconfig %USERPROFILE%\.kube\config ``` {% endtab %} {% endtabs %} | Option | Description | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--kubeconfig`, `-k` |

Set kubeconfig file to use
Defaults to value of KUBECONFIG environment variable or default config file location (usually $HOME/.kube/config).

| | `--export`, `-e` |

Set exported results filename
Defaults to kuboscore-results-YYYYMMDD-HHmmss (eg: kuboscore-results-20230126-181857).

| | `--confirm-target`, `-y` | **Automatically confirm target cluster** | | `--accept-license` |

Automatically accept license
(make sure to review the license before using this flag).

| | `--cleanup` |

Clean remaining KuboScore resources (if needed)
Keep in mind that resources are automatically removed after the execution. This option is only useful if you killed the process while it was running.

| ## Import results in KuboScore After the scoring is done, you will get a **results file** that you can import on the KuboScore website. {% hint style="info" %} Uploading your results file will allow you to **get more details** and **keep track** of your previous analysis from one **central place**. {% endhint %} 1. Go to [KuboScore](https://www.kuboscore.io) 2. Sign in to your account 3. Go to [your scorings](https://www.kuboscore.io/scores) 4. Use the import feature to upload the results file 5. Review your results!

Import results file.

# KuboVisor Detect emerging issues before they spread out and affect your applications. We provide two different installation types for KuboVisor: * [**cloud installation**](/getting-started/kubovisor/cloud-mode): we connect to your cluster from our infrastructure * :person\_lifting\_weights: we do the heavy lifting for you * :feather: nothing runs on your cluster * :chart\_with\_downwards\_trend: you save resources * [**local agent installation**](/getting-started/kubovisor/agent-mode): you deploy a KuboVisor agent workload on your cluster * :police\_officer: you are in charge * :hammer\_pick: additional configuration * :lock: more secure * :chart\_with\_upwards\_trend: use more resources The **easiest way** to setup KuboVisor is to use the [cloud installation](/getting-started/kubovisor/cloud-mode), you only need: * a publicly reachable cluster (with optional SSH authentication) * a *kubeconfig* file with sufficient permissions However, if your cluster is completely private or you don’t want to provide us with your cluster credentials, you can still [install the agent on your cluster](/getting-started/kubovisor/agent-mode). # Cloud mode Step-by-step instructions to setup KuboVisor cloud on your cluster. Go to your clusters list, click on the « Add » button and select the « Cloud » installation type.

Add cluster button.

## :construction\_site: Prepare your cluster Before going further, you need to prepare your cluster for KuboVisor. This preparation involves the creation of several authorization related resources (RBAC) needed to grant enough permissions for KuboVisor. To perform the preparation, please choose between: * using our [automatic install script](/getting-started/kubovisor/cloud-mode/automatic-setup) for an easy setup * following our guided [manual instructions](/getting-started/kubovisor/cloud-mode/manual-setup) to get more details {% hint style="info" %} Both methods generate a *kubeconfig* file that **you will need in the next steps.** {% endhint %} {% hint style="warning" %} If your cluster is exposed to the internet through a SSH bastion, please make sure to review the documentation on [how to configure your bastion for KuboVisor](/guides/grant-access-to-a-private-network). If your cluster is fully private, you cannot use KuboVisor in cloud mode, [use KuboVisor agent](/getting-started/kubovisor/agent-mode) instead. {% endhint %} ## :heavy\_plus\_sign: Add your cluster

Cluster configuration acknowledgement.

When your cluster is configured as requested by [previous section](#prepare-your-cluster), you can click on « My cluster is configured ». On the next screen, you will be requested to fill your cluster details: * **name:** cluster name as displayed in KuboVisor * **provider:** provider for your cluster, be it a cloud provider or on premise * **kubeconfig:** file to use to authenticate with your cluster

Add cluster form (cloud mode).

If you have a **private cluster behind a SSH bastion host**, you need to set the following fields in addition to others: * **bastion host:** IP/DNS name where your bastion is publicly exposed * **bastion login:** user login to use to authenticate with your bastion * **bastion SSH key:** SSH private key to use to authenticate with your bastion * **API endpoint:** Kubernetes API endpoint to use **from inside your network**

Add cluster form (cloud mode behind SSH bastion).

You can check the connection to your cluster with the « Check connection » button. To confirm your cluster details click on « Add cluster ». After your cluster has been added, it will be displayed in the user interface as “disabled” until data is received.

Cluster waiting for data.

This process can take up to 5 minutes. If it takes more time than that, please review the [troubleshooting](/getting-started/kubovisor/troubleshooting) page. If you can’t resolve the issue by yourself, feel free to contact us via [email](mailto:techsupport@kubolabs.io) or our in-app chat. ## :rocket: Get to know your cluster When data is available, you’ll see colored indicators regarding your cluster's state, health and security. Go ahead, click on them to display the details! Elements shown in **red** are issues that should be addressed **as soon as possible**. While elements shown in **orange** are problems that **should still be addressed**, they don’t threaten your cluster nor your workloads. If everything is **green**, congratulations! That means your cluster is in very good shape :sunglasses: **Try to keep it this way!** # Automatic setup Setup KuboVisor cloud in less than 30 seconds. {% hint style="info" %} The following content assumes you have [**`kubectl` binary**](https://kubernetes.io/docs/tasks/tools/#kubectl) **installed**, as well as a **privileged access** to your cluster to create listed resources. {% endhint %} For your convenience, we provide a [hand-crafted Bash script](https://download.kubolabs.io/scripts/setup_kubovisor) that will perform all the actions described in the [manual setup instructions](/getting-started/kubovisor/cloud-mode/manual-setup). {% hint style="warning" %} If you are using Windows, you will have to execute these commands in a [WSL system](https://learn.microsoft.com/en-us/windows/wsl/install) or some application like [Git Bash](https://gitforwindows.org/). {% endhint %} ## :scroll: Download the script {% tabs %} {% tab title="curl" %} ```bash curl -sO https://download.kubolabs.io/scripts/setup_kubovisor chmod +x setup_kubovisor ``` {% endtab %} {% tab title="wget" %} ```bash wget -q https://download.kubolabs.io/scripts/setup_kubovisor chmod +x setup_kubovisor ``` {% endtab %} {% endtabs %} ## :face\_with\_monocle: Check current context Make sure that your current kubecontext points to the correct cluster by, for example, checking the cluster Nodes: ```bash kubectl get nodes ``` {% hint style="warning" %} If this is not the correct cluster, you need to update your `KUBECONFIG` environment variable to point to the correct *kubeconfig* file: ```bash export KUBECONFIG=/path/to/kubeconfig.yaml ``` {% endhint %} ## :zap: Execute the script To setup KuboVisor on your cluster, you need to choose between the `limited` and `read-only` [permission levels](/getting-started/kubovisor/troubleshooting#what-are-permission-levels). {% hint style="warning" %} This script will create resources on your behalf in your cluster. If you want to know what is actually done, you can review the resources created in the [manual setup instructions](/getting-started/kubovisor/cloud-mode/manual-setup). **Please make sure that your current context targets the cluster where you want to setup KuboVisor.** {% endhint %} ```bash # Use limited permissions ./setup_kubovisor limited # Use read-only permissions ./setup_kubovisor read-only ``` At the end of the execution, a *kubeconfig* file will be generated in the current directory. Use this *kubeconfig* on KuboVisor to [add your cluster](/getting-started/kubovisor/cloud-mode#add-your-cluster). # Manual setup Setup KuboVisor cloud manually. {% hint style="info" %} The following content assumes you have [**`kubectl` binary**](https://kubernetes.io/docs/tasks/tools/#kubectl) **installed**, as well as a **privileged access** to your cluster to create listed resources. {% endhint %} ## :construction\_worker: Service account We recommend to create a specific **ServiceAccount** object in your cluster to authenticate KuboVisor and grant it specific permissions, but nothing prevents you from using an already existing service account. In this example, the service account `ksa-kubovisor` will be created in the `kubovisor` namespace. You are free to rename the service account and/or to create it in another namespace. ```bash kubectl create namespace kubovisor kubectl create serviceaccount ksa-kubovisor --namespace kubovisor ``` {% hint style="warning" %} **Kubernetes ≥ 1.24** If your cluster version equals or is over 1.24 (or if you have the *`LegacyServiceAccountTokenNoAutoGeneration`* feature gate enabled), you will have to manually generate an authentication token for the *ServiceAccount*. To get your cluster’s Kubernetes version, you can use this `kubectl` command: ```bash kubectl version --short=true ``` To generate an authentication token for the *ServiceAccount*, you need to create a *Secret* defined by the following YAML. Save its content in a **`kubovisor-secret.yaml`** file: ```yaml apiVersion: v1 kind: Secret metadata: namespace: kubovisor name: ksa-kubovisor annotations: kubernetes.io/service-account.name: ksa-kubovisor type: kubernetes.io/service-account-token ``` Apply the *Secret* on your cluster to generate the *ServiceAccount* token: ```bash kubectl apply -f kubovisor-secret.yaml ``` {% endhint %} References: * [Managing Service Accounts](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/) * [Service account tokens](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#service-account-tokens) * [ServiceAccount reference](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/service-account-v1/) ## :scales: Permissions {% hint style="info" %} This section uses the `kubovisor` namespace to reference and create objects. Be sure to update the namespace references if you used another name. {% endhint %} We currently provide two different set of permissions: * \*\*\*\*[**limited permissions**](#limited) that will allow us to **dig deeper** in our analysis of your cluster. * \*\*\*\*[**read-only permissions**](#read-only) that will enable a **base set** of features. {% hint style="warning" %} Permissions may **evolve** as we introduce **new features**. If you encounter permissions-related issues, be sure to review the minimum required permissions listed below before [asking for support](mailto:techsupport@kubolabs.io). Note that we currently only provide permissions definition for [**Role Based Access Control**](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) authorization mode. Make sure that your cluster supports it. {% endhint %} ### Limited write This set of permissions grants us read-only access to all deployed resources on your cluster, in all namespaces, as well as read-write access to pods in `kubovisor` namespace. We won’t be able to temper with resources outside of `kubovisor` namespace, only see them. To define these permissions, we use the **ClusterRole**, **ClusterRoleBinding**, **Role** and **RoleBinding** objects and link them to the service account we created earlier. This is the YAML definition of these objects: {% code title="kubovisor-limited-permissions.yaml" lineNumbers="true" %} ```yaml apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: kubovisor rules: - apiGroups: - '*' resources: - '*' verbs: - list - get - watch - nonResourceURLs: - /metrics verbs: - get --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: kubovisor roleRef: apiGroup: rbac.authorization.k8s.io kind: ClusterRole name: kubovisor subjects: - kind: ServiceAccount name: ksa-kubovisor apiGroup: '' namespace: kubovisor --- apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: namespace: kubovisor name: kubovisor-limited rules: - apiGroups: - '' resources: - pods - pods/log verbs: - create - get - delete --- apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: namespace: kubovisor name: kubovisor-limited roleRef: apiGroup: rbac.authorization.k8s.io kind: Role name: kubovisor-limited subjects: - kind: ServiceAccount name: ksa-kubovisor apiGroup: '' namespace: kubovisor ``` {% endcode %} You can create them by applying the YAML definition or with the following commands: ```bash kubectl create clusterrole kubovisor \ --verb=list,get,watch \ --resource='*.*' kubectl patch clusterrole kubovisor \ --patch '{"rules":[{"apiGroups":["*"],"resources":["*"],"verbs":["list","get","watch"]},{"nonResourceURLs":["/metrics"],"verbs":["get"]}]}' kubectl create clusterrolebinding kubovisor \ --clusterrole=kubovisor \ --serviceaccount=kubovisor:ksa-kubovisor kubectl create role kubovisor-limited \ --namespace kubovisor \ --verb=create,get,delete \ --resource=pods,pods/log kubectl create rolebinding kubovisor-limited \ --namespace kubovisor \ --role=kubovisor-limited \ --serviceaccount=kubovisor:ksa-kubovisor ``` ### Read-only This set of permissions grants us read-only access to all deployed resources on your cluster, in all namespaces. We won’t be able to temper with them, only see them. To define these permissions, we use the **ClusterRole** and **ClusterRoleBinding** objects and link them to the service account we created earlier. This is the YAML definition of these objects: {% code title="kubovisor-readonly-permissions.yaml" lineNumbers="true" %} ```yaml apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: kubovisor rules: - apiGroups: - '*' resources: - '*' verbs: - list - get - watch - nonResourceURLs: - /metrics verbs: - get --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: kubovisor roleRef: apiGroup: rbac.authorization.k8s.io kind: ClusterRole name: kubovisor subjects: - kind: ServiceAccount name: ksa-kubovisor apiGroup: '' namespace: kubovisor ``` {% endcode %} You can create them by applying the YAML definition or with the following commands: ```bash kubectl create clusterrole kubovisor \ --verb=list,get,watch \ --resource='*.*' kubectl patch clusterrole kubovisor \ --patch '{"rules":[{"apiGroups":["*"],"resources":["*"],"verbs":["list","get","watch"]},{"nonResourceURLs":["/metrics"],"verbs":["get"]}]}' kubectl create clusterrolebinding kubovisor \ --clusterrole=kubovisor \ --serviceaccount=kubovisor:ksa-kubovisor ``` ## :key: Credentials generation Last step is to generate a *kubeconfig* file for the `ksa-kubovisor` *ServiceAccount* that we created earlier. You can use our [hand-crafted Bash script](https://download.kubolabs.io/scripts/create_kubeconfig) to quickly generate one: {% hint style="warning" %} If you want to use a different *ServiceAccount*, update the parameters provided to the script to match your *ServiceAccount* name and its *Namespace*. {% endhint %} ```bash curl -sO https://download.kubolabs.io/scripts/create_kubeconfig chmod +x create_kubeconfig ./create_kubeconfig ksa-kubovisor --namespace kubovisor ``` {% hint style="info" %} Learn more about what this script does on our [dedicated article](/guides/generate-kubernetes-credentials). {% endhint %} At the end of the execution, a *kubeconfig* file will be generated in the current directory. Use this *kubeconfig* on KuboVisor to [add your cluster](/getting-started/kubovisor/cloud-mode#add-your-cluster). # Agent mode Step-by-step instructions to setup KuboVisor local agent on your cluster. ## :heavy\_plus\_sign: Add your cluster Go to your clusters list, click on the « Add » button and select the « Agent » installation type.

Add cluster button.

Fill the cluster details and click on « Add cluster ».

Add cluster form for local agent installation.

After your cluster has been added, you will receive some credentials needed for the installation of the agent on your cluster.

Cluster credentials.

If you close this window by mistake or want to install the agent later on, you can always get back your cluster credentials until you [complete the agent installation](#install-the-agent).

Click on the wrench icon to get your cluster credentials.

## :tools: Install the agent {% hint style="info" %} The following content assumes that: * you have [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl) and [`helm`](https://helm.sh/docs/intro/install/) binaries installed * your current context is set to the correct cluster * you have enough privileges on your cluster to create resources {% endhint %} {% hint style="warning" %} Replace `YOUR_CLUSTER_NAME`, `YOUR_CLUSTER_ACCESS_KEY` and `YOUR_CLUSTER_SECRET_KEY` with the values for your cluster. {% endhint %} ```bash # Check connection to your cluster kubectl get nodes # Add our Helm charts repository helm repo add kubolabs https://download.kubolabs.io/charts # Update local repositories helm repo update # Install KuboVisor local agent helm install kubovisor-agent kubolabs/kubovisor --create-namespace \ --namespace kubovisor \ --set agent.permissions=read-only \ --set cluster.name=YOUR_CLUSTER_NAME \ --set cluster.accessKey=YOUR_CLUSTER_ACCESS_KEY \ --set cluster.secretKey=YOUR_CLUSTER_SECRET_KEY ``` ### Helm chart values | Value | Default | Description | | ---------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `agent.permissions` | `read-only` | Define the [permission level](/getting-started/kubovisor/troubleshooting#what-are-permission-levels) to use. | | `agent.schedule` | `*/5 * * * *` (every 5 minutes) | Define the running periodicity. | | `agent.historyLimit` | `1` | Define the history limit of agent jobs. | | `cluster.name` | `local` |

Define the cluster name.
You will most likely want to use the same name that you used when adding your cluster.

| | `cluster.accessKey` | **Required** | Define the cluster access key. | | `cluster.secretKey` | **Required** | Define the cluster secret key. | | `serviceAccount.create` | `true` | Define if a ServiceAccount should be created. | | `serviceAccount.name` | `ksa-kubovisor` |

Set the ServiceAccount name to use.
If serviceAccount.create is set to false, this ServiceAccount must already exist.

| | `serviceAccount.annotations` | `{}` | Define the ServiceAccount annotations. | | `image.registry` | `gcr.io/kubolabs-public` | Define container image registry to use. | | `image.name` | `kubovisor/agent` | Define container image name to use. | | `image.tag` | **Value of `Chart.appVersion`** | Define container image tag to use. | | `image.pullPolicy` | `IfNotPresent` | Define container image pull policy to use. | | `image.pullSecrets` | `[]` | Define container image registry pull secret to use. | | `resources.limits.cpu` | `500m` | Define container CPU limits. | | `resources.limits.memory` | `512Mi` | Define container memory limits. | | `resources.requests.cpu` | `100m` | Define container CPU requests. | | `resources.requests.memory` | `320Mi` | Define container memory requests. | | `labels` | `{}` | Define custom labels to apply to resources. | | `annotations` | `{}` | Define custom annotations to apply to resources. | | `nodeSelector` | `{}` | Define custom node selectors. | | `tolerations` | `[]` | Define custom tolerations. | | `affinity` | `{}` | Define custom affinities. | ## :rocket: Get to know your cluster When data is available, you’ll see colored indicators regarding your cluster's state, health and security. Go ahead, click on them to display the details! Elements shown in **red** are issues that should be addressed **as soon as possible**. While elements shown in **orange** are problems that **should still be addressed**, they don’t threaten your cluster nor your workloads. If everything is **green**, congratulations! That means your cluster is in very good shape :sunglasses: **Try to keep it this way!** # Troubleshooting Common questions and issues related to KuboVisor. ## What are permission levels? KuboVisor currently supports two different set of permissions to analyze your cluster: * limited write permissions * read-only permissions With **limited write permissions**, KuboVisor has **read-only access** to all deployed resources on your cluster, in all namespaces. Additionally, **read-write access to pods in a specific namespace is granted**. We won’t be able to temper with resources outside of this namespace, only see them. With **read-only permissions**, KuboVisor has **read-only access** to all deployed resources on your cluster, in all namespaces. We won’t be able to temper with resources, only see them. {% hint style="info" %} For extended details on permission levels, refer to the [cloud installation manual setup](/getting-started/kubovisor/cloud-mode/manual-setup) specific instructions. {% endhint %} ## Is my cluster network access restriction supported? In order to use KuboVisor with your cluster, we need to be able to reach it. Below are the network restrictions that we currently support: | Restriction | Cloud | Agent | Comment | | ----------------- | :------------------: | :------------------: | -------------------------------------------------------------------------------------------------- | | None | :white\_check\_mark: | :white\_check\_mark: | You don’t have anything more to do! | | Network whitelist | :white\_check\_mark: | :white\_check\_mark: |

Add the following IP to the list of authorized networks:
34.141.253.143

| | SSH bastion | :white\_check\_mark: | :white\_check\_mark: | [**Learn how you can grant us access**](/guides/grant-access-to-a-private-network) | | Fully private | :x: | :white\_check\_mark: | Only supported with [**KuboVisor local agent**](/getting-started/kubovisor/agent-mode) | ## Agent Helm chart issues ### Cloud mode conflicting resources If you have the following error: ```bash Error: INSTALLATION FAILED: rendered manifests contain a resource that already exists. Unable to continue with install: ServiceAccount "ksa-kubovisor" in namespace "kubovisor" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "kubovisor-agent"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "kubovisor" ``` It indicates that resources that would be created by the Helm chart already exists in the cluster, but are not managed by Helm. In this case, it indicates that KuboVisor is already configured for [cloud mode](/getting-started/kubovisor/cloud-mode) in this Namespace. If this is not your installation, contact your cluster administrator. If this is your installation and you wish to use KuboVisor agent instead of cloud mode, you can follow these steps: 1. Delete the cluster on which you want to install the agent from KuboVisor. 2. Delete the following resources from the Namespace where you want to install the agent. {% hint style="warning" %} Make sure that your current context is set to the right Namespace, or add `--namespace myns` to all the following commands, replacing `myns` by the Namespace name. {% endhint %} ServiceAccount `ksa-kubovisor`: ```bash kubectl delete sa ksa-kubovisor ``` Role `kubovisor-limited`: ```bash kubectl delete role kubovisor-limited ``` RoleBinding `kubovisor-limited`: ```bash kubectl delete rolebinding kubovisor-limited ``` 3. Once all these resources are deleted, you can [install the agent](/getting-started/kubovisor/agent-mode). ### Multiple KuboVisor agent releases If you have the following error: ```bash Error: INSTALLATION FAILED: rendered manifests contain a resource that already exists. Unable to continue with install: ServiceAccount "ksa-kubovisor" in namespace "kubovisor" exists and cannot be imported into the current release: invalid ownership metadata; annotation validation error: key "meta.helm.sh/release-name" must equal "kubovisor-agent2": current value is "kubovisor-agent" ``` It indicates that another Helm release of KuboVisor agent is installed on the cluster in this Namespace. You can list installed Helm releases with: ```bash helm list ``` # Generate Kubernetes credentials In order to use our products, a Kubernetes credentials file – commonly called *kubeconfig* file – is required to **grant us access and permissions** to your cluster. This guide will walk you through the generation process of a *kubeconfig* file for a specific service account of your cluster. ## :bullettrain\_front: Automatic generation If you’re in a hurry, or don’t want to get lost in commands, you can use our [hand-crafted Bash script](https://download.kubolabs.io/scripts/create_kubeconfig) which will do the heavy lifting for you! It takes the service account name as its sole argument and will generate the file in the current directory. {% tabs %} {% tab title="curl" %} ```bash curl -sO https://download.kubolabs.io/scripts/create_kubeconfig chmod +x create_kubeconfig ./create_kubeconfig ``` {% endtab %} {% tab title="wget" %} ```bash wget -q https://download.kubolabs.io/scripts/create_kubeconfig chmod +x create_kubeconfig ./create_kubeconfig ``` {% endtab %} {% endtabs %} {% hint style="warning" %} Change `` with the name of the service account you wish to create a *kubeconfig* file for. For KuboScore, it should be `ksa-kuboscore`. For KuboVisor, it should be `ksa-kubovisor`. {% endhint %} {% hint style="info" %} If you want to use a different namespace, cluster or context, just use the `--namespace`, `--cluster` and `--context` flags like you would normally do with `kubectl`. {% endhint %} ## :snail: Manual generation *Don’t trust our Bash script? Don’t have Bash? We got you covered!* ### :pencil: Prerequisites Following content assumes that [**`kubectl` binary**](https://kubernetes.io/docs/tasks/tools/#kubectl) **is installed** on your system and you have permissions to **get** the following objects from the namespace where the service account lives: * *ServiceAccounts* * *Secrets* Execute the following commands to make sure you have enough permissions. {% hint style="warning" %} Replace `` with the actual name of the namespace. {% endhint %} ```shell kubectl auth can-i get serviceaccount --namespace= kubectl auth can-i get secret --namespace= ``` If you have the right permissions, both commands should return `yes` as a result. If the output to one of these commands is `no`, it means the credentials you’re using don’t have enough permissions to get the requested resource. Make sure you’re using the correct credentials or contact your cluster administrator. ### :key: Credentials generation #### Prepare your environment {% hint style="warning" %} Replace `` by the actual namespace name and `` by the actual service account name. {% endhint %}
Differences between Kubernetes 1.24+ and before If your cluster version is 1.24+ (or if you have the *`LegacyServiceAccountTokenNoAutoGeneration`* feature gate enabled), you will have to manually generate an authentication token by creating the following Secret for the ServiceAccount. {% code title="sa-secret.yaml" %} ```yaml apiVersion: v1 kind: Secret metadata: namespace: name: annotations: kubernetes.io/service-account.name: type: kubernetes.io/service-account-token ``` {% endcode %} Apply the Secret on your cluster to generate the ServiceAccount token: ```bash kubectl apply -f sa-secret.yaml ``` **Replace `` by the name of this Secret.** If your cluster version is below 1.24, **the Secret is created by Kubernetes with the same name as the ServiceAccount.**
```shell export NS= export SA= export SEC_NAME= export SEC_TK=$(kubectl -n ${NS} get secret ${SEC_NAME} -o jsonpath='{.data.token}' | base64 --decode) export CA=$(kubectl -n ${NS} get secret ${SEC_NAME} -o jsonpath='{.data.ca\.crt}') export CUR_CTX=$(kubectl config current-context) export CUR_CLUST=$(kubectl config view -o "jsonpath={.contexts[?(@.name==\"${CUR_CTX}\")].context.cluster}") export CUR_SRV=$(kubectl config view -o "jsonpath={.clusters[?(@.name==\"${CUR_CLUST}\")].cluster.server}") ``` #### Generate the file ```shell cat < kubeconfig-$SA.yaml apiVersion: v1 kind: Config clusters: - name: ${CUR_CLUST} cluster: certificate-authority-data: ${CA} server: ${CUR_SRV} contexts: - name: ${CUR_CTX} context: cluster: ${CUR_CLUST} namespace: default user: ${SA} current-context: ${CUR_CTX} users: - name: ${SA} user: token: ${SEC_TK} EOF ``` ## :weary: Troubleshooting #### I can’t connect to my cluster ``` The connection to the server XXX was refused - did you specify the right host or port? ``` In this case, make sure that you’re connected to the internet or to a network (eg. VPN) from which you can access your cluster. If the problem persists, please contact your cluster administrator. #### I can’t use the generated credentials file with your products! ``` Error from server (Forbidden): XXX is forbidden: User "system:serviceaccount:kube-system:ksa-kuboscore" cannot ``` The service account you specified doesn’t have enough permissions. [Please contact us](mailto:techsupport@kubolabs.io). # Grant access to a private network In some cases, your cluster sits in a private network. Although this is a **very good practice**, it means **additional steps needs to be taken** in order to allow our products to connect to your cluster. Before following this guide, make sure that there is a way to reach your private network from a machine that is publicly exposed. This machine is commonly called a **bastion host** and it controls all access to your private network. We will walk you through the creation of a specific user on the bastion host that will be used by our products to reach your cluster. ## :pencil: Prerequisites Following content assumes that your bastion is a **Linux machine** and **`ssh-keygen` binary is installed** on it. {% hint style="warning" %} Next commands needs to be executed **on your bastion with superuser privileges**. Make sure you have the permissions to perform such commands or use `sudo` command if it’s available. {% endhint %} ## :bust\_in\_silhouette: Create a new user This command will create a new `kubolabs` system user. {% tabs %} {% tab title="RHEL" %} ```bash useradd --system --create-home kubolabs ``` {% endtab %} {% tab title="Debian" %} ```bash useradd --disabled-password --system kubolabs ``` {% endtab %} {% endtabs %} ## :closed\_lock\_with\_key: Generate SSH keys This command will generate a SSH key pair that will be used by our products to authenticate on your bastion. ```bash ssh-keygen -t rsa -b 4096 -C "kubolabs" -N "" -q -f kubolabs-key ``` If the command is successful, two files would have been generated in the current directory: * `kubolabs-key`: private key file * `kubolabs-key.pub`: public key file {% hint style="danger" %} Make sure to store `kubolabs-key` file somewhere safe and do not share it publicly nor without encryption. {% endhint %} ## :passport\_control: Authorize SSH key to authenticate This command will add the SSH public key that we just created to the list of `kubolabs`’s authorized SSH keys. ```bash mkdir /home/kubolabs/.ssh/ cat kubolabs-key.pub | tee -a /home/kubolabs/.ssh/authorized_keys chown -R kubolabs:kubolabs /home/kubolabs/.ssh chmod 0700 /home/kubolabs/.ssh chmod 0644 /home/kubolabs/.ssh/authorized_keys ``` {% hint style="danger" %} Anyone in possession of the private key will be allowed to connect on your bastion as `kubolabs` user. {% endhint %} ## :white\_check\_mark: Check public key authentication is enabled This command will make sure that the public key authentication is enabled. ```bash grep -E '^PubkeyAuthentication' /etc/ssh/sshd_config ``` If public key authentication is enabled, command output will be the following: ``` PubkeyAuthentication yes ``` If the output is either: ``` #PubkeyAuthentication yes ``` Or: ``` PubkeyAuthentication no ``` You must enable it: ```bash sed -i=backup 's/#\?PubkeyAuthentication.*/PubkeyAuthentication yes/' /etc/ssh/sshd_config ``` {% hint style="info" %} If something went wrong with this command, a backup of the original file is available at `/etc/ssh/sshd_config.backup`. {% endhint %} ## :police\_officer: Allow access from our products {% hint style="info" %} This step is only required if your bastion is filtering the allowed incoming IPs. If you are not sure, ask your administrator. {% endhint %} Add the following IP to the list of authorized networks: **34.141.253.143**. # FAQ Find answers about most frequently asked questions about our products. ## KuboScore ### Is it free? Yes, getting your KuboScore and high level details of the analysis is **completely free**. If you want a **more detailed analysis** of the issues we have identified, you can still **purchase a professional report**. For more details, please visit [our pricing page](https://www.kubolabs.io/pricing). If you have any additional questions, please reach out to us at . ### Do I have to install anything? No, you have **nothing to install**. Our analysis is running **fully remotely** through your cluster’s Kubernetes API. ## KuboVisor ### Is it free? No, but we offer a **15 days free trial** – *no credit card required* – so you can test it on your clusters **without any restrictions** and see if we really help you detect new issues. For more details, please visit [our pricing page](https://www.kubolabs.io/pricing). ## All products ### Is my cloud provider supported? Yes, as long as we can reach your cluster’s Kubernetes API, the underlying **cloud provider does not matter**. ### Are on-premise environments supported? Yes, as long as we can **reach your cluster’s Kubernetes API**. ### **What happens if my cluster is** restrained to a specific set of authorized networks\*\*?\*\* All you need to do is to add the following IP to the list of authorized networks: **34.141.253.143**. ### What happens if my cluster sits in a fully private network? If you are using a bastion host to control access to this network, all you need to do is to [**grant us access to it**](/guides/grant-access-to-a-private-network). If you have a different setup, our support team will be happy to help! You can contact us at .