From 9def2d6f9a1aa321e834615e2da224e318c9d926 Mon Sep 17 00:00:00 2001 From: "Jonathan Gonzalez V." Date: Wed, 30 Oct 2024 13:48:22 +0100 Subject: [PATCH] docs: add permissions required by kubectl CNPG plugin (#5829) document every permission required by every command in the CNPG plugin to let users assign specific permissions for specific tasks. Closes #5330 Signed-off-by: Gabriele Quaresima Signed-off-by: Jonathan Gonzalez V. Signed-off-by: Jaime Silvela Signed-off-by: Francesco Canovai --- .wordlist-en-custom.txt | 5 ++ docs/mkdocs.yml | 4 +- docs/src/kubectl-plugin.md | 115 ++++++++++++++++++++++++++++++ internal/cmd/plugin/report/olm.go | 2 +- 4 files changed, 124 insertions(+), 2 deletions(-) diff --git a/.wordlist-en-custom.txt b/.wordlist-en-custom.txt index e564fc34f0..df5953f2a3 100644 --- a/.wordlist-en-custom.txt +++ b/.wordlist-en-custom.txt @@ -525,6 +525,7 @@ authQuery authQuerySecret authn authz +autocompletion autoscaler autovacuum availableArchitectures @@ -610,6 +611,7 @@ clusterName clusterimagecatalogs clusterlist clusterrole +clusterserviceversions clusterspec clusterstatus cmd @@ -818,6 +820,7 @@ initdb initialise initializingPVC inplace +installplans instanceID instanceName instanceNames @@ -923,6 +926,7 @@ mountPath msg mspan multinamespace +mutatingwebhookconfigurations myAKSCluster myResourceGroup namespace @@ -1279,6 +1283,7 @@ usernamepassword usr utils validUntil +validatingwebhookconfigurations valueFrom viceversa virtualized diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index b3dd9c55f7..471250cf7d 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -2,7 +2,8 @@ site_name: CloudNativePG site_author: The CloudNativePG Contributors docs_dir: src -theme: readthedocs +theme: + name: readthedocs extra_css: - css/override.css @@ -11,6 +12,7 @@ markdown_extensions: - admonition - def_list - attr_list + - footnotes nav: - index.md diff --git a/docs/src/kubectl-plugin.md b/docs/src/kubectl-plugin.md index a9564d545d..35c66f2494 100755 --- a/docs/src/kubectl-plugin.md +++ b/docs/src/kubectl-plugin.md @@ -1366,3 +1366,118 @@ The `cnpg` plugin can be easily integrated in [K9s](https://k9scli.io/), a popular terminal-based UI to interact with Kubernetes clusters. See [`k9s/plugins.yml`](samples/k9s/plugins.yml) for details. + +## Permissions required by the plugin + +The plugin requires a set of Kubernetes permissions that depends on the command +to execute. These permissions may affect resources and sub-resources like Pods, +PDBs, PVCs, and enable actions like `get`, `delete`, `patch`. The following +table contains the full details: + +| Command | Resource Permissions | +|:----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| backup | clusters: get
backups: create | +| certificate | clusters: get
secrets: get,create | +| destroy | pods: get,delete
jobs: delete,list
PVCs: list,delete,update | +| fencing | clusters: get,patch
pods: get | +| fio | PVCs: create
configmaps: create
deployment: create | +| hibernate | clusters: get,patch,delete
pods: list,get,delete
pods/exec: create
jobs: list
PVCs: get,list,update,patch,delete | +| install | none | +| logs | clusters: get
pods: list
pods/log: get | +| maintenance | clusters: get,patch,list
| +| pgadmin4 | clusters: get
configmaps: create
deployments: create
services: create
secrets: create | +| pgbench | clusters: get
jobs: create
| +| promote | clusters: get
clusters/status: patch
pods: get | +| psql | pods: get,list
pods/exec: create | +| publication | clusters: get
pods: get,list
pods/exec: create | +| reload | clusters: get,patch | +| report cluster | clusters: get
pods: list
pods/log: get
jobs: list
events: list
PVCs: list | +| report operator | configmaps: get
deployments: get
events: list
pods: list
pods/log: get
secrets: get
services: get
mutatingwebhookconfigurations: list[^1]
validatingwebhookconfigurations: list[^1]
If OLM is present on the K8s cluster, also:
clusterserviceversions: list
installplans: list
subscriptions: list | +| restart | clusters: get,patch
pods: get,delete | +| status | clusters: get
pods: list
pods/exec: create
pods/proxy: create
PDBs: list | +| subscription | clusters: get
pods: get,list
pods/exec: create | +| version | none | + +[^1]: The permissions are cluster scope ClusterRole resources. + +///Footnotes Go Here/// + +Additionally, assigning the `list` permission on the `clusters` will enable +autocompletion for multiple commands. + +### Role examples + +It is possible to create roles with restricted permissions. +The following example creates a role that only has access to the cluster logs: + +```yaml +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: cnpg-log +rules: + - verbs: + - get + apiGroups: + - postgresql.cnpg.io + resources: + - clusters + - verbs: + - list + apiGroups: + - '' + resources: + - pods + - verbs: + - get + apiGroups: + - '' + resources: + - pods/log +``` + +The next example shows a role with the minimal permissions required to get +the cluster status using the plugin's `status` command: + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: cnpg-status +rules: + - verbs: + - get + apiGroups: + - postgresql.cnpg.io + resources: + - clusters + - verbs: + - list + apiGroups: + - '' + resources: + - pods + - verbs: + - create + apiGroups: + - '' + resources: + - pods/exec + - verbs: + - create + apiGroups: + - '' + resources: + - pods/proxy + - verbs: + - list + apiGroups: + - policy + resources: + - poddisruptionbudgets +``` + +!!! Important + Keeping the verbs restricted per `resources` and per `apiGroups` helps to + prevent inadvertently granting more than intended permissions. diff --git a/internal/cmd/plugin/report/olm.go b/internal/cmd/plugin/report/olm.go index cc20ff54ae..5e179540cc 100644 --- a/internal/cmd/plugin/report/olm.go +++ b/internal/cmd/plugin/report/olm.go @@ -46,7 +46,7 @@ func getOlmResourceList( resourceList, err := dynamicClient.Resource(gvr).Namespace(namespace). List(ctx, metav1.ListOptions{LabelSelector: getLabelOperatorsNamespace()}) if err != nil { - return nil, fmt.Errorf("could note get resource: %v, %v", gvr, err) + return nil, fmt.Errorf("could not list resource: %v, %v", gvr, err) } return resourceList, nil