Skip to content

Commit

Permalink
docs: add permissions required by kubectl CNPG plugin (cloudnative-pg…
Browse files Browse the repository at this point in the history 
…#5829)

document every permission required by every command in the
CNPG plugin to let users assign specific permissions for specific
tasks.

Closes cloudnative-pg#5330

Signed-off-by: Gabriele Quaresima <[email protected]>
Signed-off-by: Jonathan Gonzalez V. <[email protected]>
Signed-off-by: Jaime Silvela <[email protected]>
Signed-off-by: Francesco Canovai <[email protected]>
  • Loading branch information
@sxd
sxd authored Oct 30, 2024
1 parent 5b80e21 commit 9def2d6
Show file tree
Hide file tree
Showing 4 changed files with 124 additions and 2 deletions.
5 changes: 5 additions & 0 deletions .wordlist-en-custom.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -525,6 +525,7 @@ authQuery
authQuerySecret
authn
authz
autocompletion
autoscaler
autovacuum
availableArchitectures
Expand Down Expand Up @@ -610,6 +611,7 @@ clusterName
clusterimagecatalogs
clusterlist
clusterrole
clusterserviceversions
clusterspec
clusterstatus
cmd
Expand Down Expand Up @@ -818,6 +820,7 @@ initdb
initialise
initializingPVC
inplace
installplans
instanceID
instanceName
instanceNames
Expand Down Expand Up @@ -923,6 +926,7 @@ mountPath
msg
mspan
multinamespace
mutatingwebhookconfigurations
myAKSCluster
myResourceGroup
namespace
Expand Down Expand Up @@ -1279,6 +1283,7 @@ usernamepassword
usr
utils
validUntil
validatingwebhookconfigurations
valueFrom
viceversa
virtualized
Expand Down
4 changes: 3 additions & 1 deletion docs/mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -11,6 +12,7 @@ markdown_extensions:
- admonition
- def_list
- attr_list
- footnotes

nav:
- index.md
Expand Down
115 changes: 115 additions & 0 deletions docs/src/kubectl-plugin.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<br/>backups: create |
| certificate | clusters: get<br/>secrets: get,create |
| destroy | pods: get,delete<br/>jobs: delete,list<br/>PVCs: list,delete,update |
| fencing | clusters: get,patch<br/>pods: get |
| fio | PVCs: create<br/>configmaps: create<br/>deployment: create |
| hibernate | clusters: get,patch,delete<br/>pods: list,get,delete<br/>pods/exec: create<br/>jobs: list<br/>PVCs: get,list,update,patch,delete |
| install | none |
| logs | clusters: get<br/>pods: list<br/>pods/log: get |
| maintenance | clusters: get,patch,list<br/> |
| pgadmin4 | clusters: get<br/>configmaps: create<br/>deployments: create<br/>services: create<br/>secrets: create |
| pgbench | clusters: get<br/>jobs: create<br/> |
| promote | clusters: get<br/>clusters/status: patch<br/>pods: get |
| psql | pods: get,list<br/>pods/exec: create |
| publication | clusters: get<br/>pods: get,list<br/>pods/exec: create |
| reload | clusters: get,patch |
| report cluster | clusters: get<br/>pods: list<br/>pods/log: get<br/>jobs: list<br/>events: list<br/>PVCs: list |
| report operator | configmaps: get<br/>deployments: get<br/>events: list<br/>pods: list<br/>pods/log: get<br/>secrets: get<br/>services: get<br/>mutatingwebhookconfigurations: list[^1]<br/> validatingwebhookconfigurations: list[^1]<br/> If OLM is present on the K8s cluster, also:<br/>clusterserviceversions: list<br/>installplans: list<br/>subscriptions: list |
| restart | clusters: get,patch<br/>pods: get,delete |
| status | clusters: get<br/>pods: list<br/>pods/exec: create<br/>pods/proxy: create<br/>PDBs: list |
| subscription | clusters: get<br/>pods: get,list<br/>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.
2 changes: 1 addition & 1 deletion internal/cmd/plugin/report/olm.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 9def2d6

Please sign in to comment.