# Manual setup

{% 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](https://docs.kubolabs.io/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](https://docs.kubolabs.io/getting-started/kubovisor/cloud-mode/..#add-your-cluster).