Skip to content

Commit ea9d932

Browse files
jwilliams-mongojwilliams-mongo
authored
(DOCSP-14079): document custom roles (#298)
* (DOCSP-14079): document custom roles * (DOCSP-14079): fix tocs altered by vscode markdown extension * (DOCSP-14079): copy review feedback
1 parent 5595f74 commit ea9d932

File tree

3 files changed

+81
-5
lines changed

3 files changed

+81
-5
lines changed

‎README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ Here is a talk from MongoDB Live 2020 about the Community Operator:
1313

1414
- [Documentation](#documentation)
1515
- [Supported Features](#supported-features)
16+
- [Planned Features](#planned-features)
1617
- [Contribute](#contribute)
1718
- [License](#license)
1819

@@ -38,6 +39,7 @@ The MongoDB Community Kubernetes Operator supports the following features:
3839
- Connect to the replica set from inside the Kubernetes cluster (no external connectivity)
3940
- Secure client-to-server and server-to-server connections with TLS
4041
- Create users with [SCRAM](https://docs.mongodb.com/manual/core/security-scram/) authentication
42+
- Create custom roles
4143

4244
### Planned Features
4345
- Server internal authentication via keyfile

‎docs/deploy-configure.md

Lines changed: 76 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,10 @@ The [`/deploy/crds`](../deploy/crds) directory contains example MongoDB resource
66

77
- [Deploy a Replica Set](#deploy-a-replica-set)
88
- [Scale a Replica Set](#scale-a-replica-set)
9-
- [Upgrade MongoDB Version & FCV](#upgrade-your-mongodb-resource-version-and-feature-compatibility-version)
10-
- [Deploying on Openshift](#deploying-on-openshift)
9+
- [Upgrade your MongoDB Resource Version and Feature Compatibility Version](#upgrade-your-mongodb-resource-version-and-feature-compatibility-version)
10+
- [Example](#example)
11+
- [Deploy Replica Sets on OpenShift](#deploy-replica-sets-on-openshift)
12+
- [Define a Custom Database Role](#define-a-custom-database-role)
1113

1214
## Deploy a Replica Set
1315

@@ -132,3 +134,75 @@ an example of how to provide the required configuration for a MongoDB
132134
replica set.
133135

134136
See [here](../deploy/openshift/operator_openshift.yaml) for an example of how to configure the Operator deployment.
137+
138+
## Define a Custom Database Role
139+
140+
You can define [custom roles](https://docs.mongodb.com/manual/core/security-user-defined-roles/) to give you fine-grained access control over your MongoDB database resource.
141+
142+
**NOTE**: Custom roles are scoped to a single MongoDB database resource.
143+
144+
To define a custom role:
145+
146+
1. Add the following fields to the MongoDB resource definition:
147+
148+
| Key | Type | Description | Required? |
149+
|----|----|----|----|
150+
| `spec.security.roles` | array | Array that defines [custom roles](https://docs.mongodb.com/manual/core/security-user-defined-roles/) roles that give you fine-grained access control over your MongoDB deployment. | Yes |
151+
| `spec.security.roles.role` | string | Name of the custom role. | Yes |
152+
| `spec.security.roles.db` | string | Database in which you want to store the user-defined role. | Yes |
153+
| `spec.security.roles.authenticationRestrictions` | array | Array that defines the IP address from which and to which users assigned this role can connect. | No |
154+
| `spec.security.roles.authenticationRestrictions.clientSource` | array | Array of IP addresses or CIDR blocks from which users assigned this role can connect. <br><br> MongoDB servers reject connection requests from users with this role if the requests come from a client that is not present in this array. | No |
155+
| `spec.security.roles.authenticationRestrictions.serverAddress` | array | Array of IP addresses or CIDR blocks to which users assigned this role can connect. <br><br> MongoDB servers reject connection requests from users with this role if the client requests to connect to a server that is not present in this array. | No |
156+
| `spec.security.roles.privileges` | array | List of actions that users granted this role can perform. For a list of accepted values, see [Privilege Actions](https://docs.mongodb.com/manual/reference/privilege-actions/#database-management-actions) in the MongoDB Manual for the MongoDB versions you deploy with the Kubernetes Operator. | Yes |
157+
| `spec.security.roles.privileges.actions` | array | Name of the role. Valid values are [built-in roles](https://docs.mongodb.com/manual/reference/built-in-roles/#built-in-roles). | Yes |
158+
| `spec.security.roles.privileges.resource.database`| string | Database for which the privilege `spec.security.roles.privileges.actions` apply. An empty string (`""`) indicates that the privilege actions apply to all databases. <br><br> If you provide a value for this setting, you must also provide a value for `spec.security.roles.privileges.resource.collection`. | Conditional |
159+
| `spec.security.roles.privileges.resource.collection`| string | Collection for which the privilege `spec.security.roles.privileges.actions` apply. An empty string (`""`) indicates that the privilege actions apply to all of the database's collections.<br><br> If you provide a value for this setting, you must also provide a value for `spec.security.roles.privileges.resource.database`. | Conditional |
160+
| `spec.security.roles.privileges.resource.cluster`| string | Flag that indicates that the privilege `spec.security.roles.privileges.actions` apply to all databases and collections in the MongoDB deployment. If omitted, defaults to `false`.<br><br> If set to `true`, do not provide values for `spec.security.roles.privileges.resource.database` and `spec.security.roles.privileges.resource.collection`. | Conditional |
161+
| `spec.security.roles.roles`| array | An array of roles from which this role inherits privileges. <br><br> You must include the roles field. Use an empty array (`[]`) to specify no roles to inherit from. | Yes |
162+
| `spec.security.roles.roles.role` | string | Name of the role to inherit from. | Conditional |
163+
| `spec.security.roles.roles.database` | string | Name of database that contains the role to inherit from. | Conditional |
164+
165+
```yaml
166+
---
167+
apiVersion: mongodb.com/v1
168+
kind: MongoDB
169+
metadata:
170+
name: custom-role-mongodb
171+
spec:
172+
members: 3
173+
type: ReplicaSet
174+
version: "4.2.6"
175+
security:
176+
authentication:
177+
modes: ["SCRAM"]
178+
roles: # custom roles are defined here
179+
- role: testRole
180+
db: admin
181+
privileges:
182+
- resource:
183+
db: "test"
184+
collection: "" # an empty string indicates any collection
185+
actions:
186+
- find
187+
roles: []
188+
users:
189+
- name: my-user
190+
db: admin
191+
passwordSecretRef: # a reference to the secret that will be used to generate the user's password
192+
name: my-user-password
193+
roles:
194+
- name: clusterAdmin
195+
db: admin
196+
- name: userAdminAnyDatabase
197+
db: admin
198+
- name: testRole # apply the custom role to the user
199+
db: admin
200+
scramCredentialsSecretName: my-scram
201+
```
202+
203+
2. Save the file.
204+
3. Apply the updated MongoDB resource definition:
205+
206+
```
207+
kubectl apply -f <mongodb-crd>.yaml --namespace <my-namespace>
208+
```

‎docs/users.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ You cannot disable SCRAM authentication.
4040
| `spec.users.passwordSecretRef.key` | string| Key in the secret that corresponds to the value of the user's password. Defaults to `password`. | No |
4141
| `spec.users.scramCredentialsSecretName` | string| ScramCredentialsSecretName appended by string "scram-credentials" is the name of the secret object created by the operator for storing SCRAM credentials for the user. The name should comply with [DNS1123 subdomain](https://tools.ietf.org/html/rfc1123). Also, please make sure the name is unique among `users`. | Yes |
4242
| `spec.users.roles` | array of objects | Configures roles assigned to the user. | Yes |
43-
| `spec.users.roles.role.name` | string | Name of the role. Valid values are [built-in roles](https://docs.mongodb.com/manual/reference/built-in-roles/#built-in-roles). | Yes |
43+
| `spec.users.roles.role.name` | string | Name of the role. Valid values are [built-in roles](https://docs.mongodb.com/manual/reference/built-in-roles/#built-in-roles) and [custom roles](deploy-configure.md#define-a-custom-database-role) that you have defined. | Yes |
4444
| `spec.users.roles.role.db` | string | Database that the role applies to. | Yes |
4545
4646
```
@@ -68,8 +68,8 @@ You cannot disable SCRAM authentication.
6868
db: <role-2-database>
6969
...
7070
```
71-
1. Save the file.
72-
1. Apply the updated MongoDB resource definition:
71+
2. Save the file.
72+
3. Apply the updated MongoDB resource definition:
7373
7474
```
7575
kubectl apply -f <mongodb-crd>.yaml --namespace <my-namespace>

0 commit comments

Comments
 (0)