(DOCSP-11805): custom roles for database resources (#359)

jwilliams-mongo · web-flow · commit 9e6bb16641d7 · 2020-09-02T10:06:19.000-04:00
* (DOCSP-11805): custom roles for database resources * (DOCSP-11805): add sample * (DOCSP-11805): fix path to sample * (DOCSP-11805): copy and tech review feedback * (DOCSP-11805): fix pre-existing typo * (DOCSP-11805): move roles settings back to security section
diff --git a/source/includes/code-examples/yaml-files/example-custom-role.yaml b/source/includes/code-examples/yaml-files/example-custom-role.yaml
@@ -0,0 +1,35 @@
+---
+apiVersion: mongodb.com/v1
+kind: MongoDB
+metadata:
+  name: <my-replica-set>
+spec:
+  members: 3
+  version: 4.2.2-ent
+  type: ReplicaSet
+  opsManager:
+    configMapRef:
+      name: <configMap.metadata.name>
+  credentials: <mycredentials>
+  persistent: true
+  security:
+    authentication:
+      enabled: true
+      modes:
+        - "SCRAM"
+    roles:
+      - role: "customRole"
+        db: admin    
+        privileges:
+        - actions:
+          - insert
+          resource:
+            collection: cats
+            db: pets
+        - actions:
+          - insert
+          - find
+          resource:
+            collection: dogs
+            db: pets
+...
diff --git a/source/includes/options-k8s-replica-set.yaml b/source/includes/options-k8s-replica-set.yaml
@@ -345,6 +345,90 @@ inherit:
   file: options-k8s-shared.yaml
 ---
 program: k8sRsConf
+name: spec.security.roles
+inherit:
+  name: spec.security.roles
+  program: _shared
+  file: options-k8s-shared.yaml
+---
+program: k8sRsConf
+name: spec.security.roles.role
+inherit:
+  name: spec.security.roles.role
+  program: _shared
+  file: options-k8s-shared.yaml
+---
+program: k8sRsConf
+name: spec.security.roles.db
+inherit:
+  name: spec.security.roles.db
+  program: _shared
+  file: options-k8s-shared.yaml
+---
+program: k8sRsConf
+name: spec.security.roles.authenticationRestrictions
+inherit:
+  name: spec.security.roles.authenticationRestrictions
+  program: _shared
+  file: options-k8s-shared.yaml
+---
+program: k8sRsConf
+name: spec.security.roles.authenticationRestrictions.clientSource
+inherit:
+  name: spec.security.roles.authenticationRestrictions.clientSource
+  program: _shared
+  file: options-k8s-shared.yaml
+---
+program: k8sRsConf
+name: spec.security.roles.authenticationRestrictions.serverAddress
+inherit:
+  name: spec.security.roles.authenticationRestrictions.serverAddress
+  program: _shared
+  file: options-k8s-shared.yaml
+---
+program: k8sRsConf
+name: spec.security.roles.privileges
+inherit:
+  name: spec.security.roles.privileges
+  program: _shared
+  file: options-k8s-shared.yaml
+---
+program: k8sRsConf
+name: spec.security.roles.privileges.actions
+inherit:
+  name: spec.security.roles.privileges.actions
+  program: _shared
+  file: options-k8s-shared.yaml
+---
+program: k8sRsConf
+name: spec.security.roles.privileges.resource
+inherit:
+  name: spec.security.roles.privileges.resource
+  program: _shared
+  file: options-k8s-shared.yaml
+---
+program: k8sRsConf
+name: spec.security.roles.privileges.resource.database
+inherit:
+  name: spec.security.roles.privileges.resource.database
+  program: _shared
+  file: options-k8s-shared.yaml
+---
+program: k8sRsConf
+name: spec.security.roles.privileges.resource.collection
+inherit:
+  name: spec.security.roles.privileges.resource.collection
+  program: _shared
+  file: options-k8s-shared.yaml
+---
+program: k8sRsConf
+name: spec.security.roles.privileges.resource.cluster
+inherit:
+  name: spec.security.roles.privileges.resource.cluster
+  program: _shared
+  file: options-k8s-shared.yaml
+---
+program: k8sRsConf
 name: spec.security.tls.enabled
 inherit:
   name: spec.security.tls.enabled
diff --git a/source/includes/options-k8s-shared.yaml b/source/includes/options-k8s-shared.yaml
@@ -583,6 +583,205 @@ description: |
   To manage database users directly through the |mongod| or |mongos|, set to ``true``.
 ---
 program: _shared
+name: spec.security.roles
+type: array
+optional: true
+directive: setting
+description: |
+
+  Array that defines :manual:`User-defined roles
+  </manual/core/security-user-defined-roles/>` that give you
+  fine-grained access control over your MongoDB deployment.
+
+  To enable user-defined roles, the
+  :setting:`spec.security.authentication.enabled` must be ``true``.
+
+  .. example::
+
+     In this example, a user-defined role named ``customRole`` allows
+     users assigned this role to:
+
+     - Insert documents into the ``cats`` collection in the ``pets``
+       database, and
+     - Find and insert documents into the ``dogs`` collection in the
+       ``pets`` database.
+
+     .. literalinclude:: /includes/code-examples/yaml-files/example-custom-role.yaml
+        :language: yaml
+        :linenos:
+        :emphasize-lines: 15-34
+
+---
+program: _shared
+name: spec.security.roles.role
+type: string
+directive: setting
+optional: true
+description: |
+
+  Name of the user-defined role.
+
+---
+program: _shared
+name: spec.security.roles.db
+type: string
+directive: setting
+optional: true
+description: |
+
+  The database in which you want to store the user-defined role.
+
+  .. example::
+
+     ``admin``
+
+---
+program: _shared
+name: spec.security.roles.authenticationRestrictions
+type: array
+directive: setting
+optional: true
+description: |
+  Array that defines the IP address from which and to which users
+  assigned this :setting:`spec.security.roles.role` can
+  connect.
+
+---
+program: _shared
+name: spec.security.roles.authenticationRestrictions.clientSource
+type: array
+directive: setting
+optional: true
+description: |
+
+  Array of IP addresses or CIDR blocks from which users assigned this
+  :setting:`spec.security.roles.role` can connect. 
+
+  MongoDB servers reject connection requests from users with this role
+  if the requests come from a client that is not present in this array.
+
+---
+program: _shared
+name: spec.security.roles.authenticationRestrictions.serverAddress
+type: array
+directive: setting
+optional: true
+description: |
+
+  Array of IP addresses or CIDR blocks to which users assigned this
+  :setting:`spec.security.roles.role` can connect. 
+
+  Users *can not* connect to this MongoDB deployment if they possess
+  this role and they sent the connection request to a server that is not
+  present in this array.
+
+  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.
+
+---
+program: _shared
+name: spec.security.roles.privileges
+type: array
+directive: setting
+optional: true
+description: |
+
+  Array that describes the privileges that users granted this role
+  possess.
+
+---
+program: _shared
+name: spec.security.roles.privileges.actions
+type: array
+directive: setting
+optional: true
+description: |
+
+  List of actions that users granted this role can perform. For a list
+  of accepted values, see :manual:`Privilege Actions
+  </reference/privilege-actions/#database-management-actions>` in the
+  MongoDB Manual for the MongoDB versions you deploy with the
+  |k8s-op-short|.
+
+---
+program: _shared
+name: spec.security.roles.privileges.resource
+type: collection
+directive: setting
+optional: true
+description: |
+
+  Resources for which the privilege
+  :setting:`~spec.security.roles.privileges.actions`
+  apply.
+
+  This collection must include either:
+
+  - The
+    :setting:`spec.security.roles.privileges.resource.database`
+    and
+    :setting:`spec.security.roles.privileges.resource.collection`
+    settings, or
+  - The
+    :setting:`spec.security.roles.privileges.resource.cluster`
+    setting with a value of ``true``.
+
+---
+program: _shared
+name: spec.security.roles.privileges.resource.database
+type: string
+directive: setting
+optional: true
+description: |
+
+  Database for which the privilege
+  :setting:`~spec.security.roles.privileges.actions`
+  apply.
+
+  If you provide a value for this setting, you must also provide a value
+  for
+  :setting:`spec.security.roles.privileges.resource.collection`.
+
+---
+program: _shared
+name: spec.security.roles.privileges.resource.collection
+type: string
+directive: setting
+optional: true
+description: |
+
+  Collection in the
+  :setting:`~spec.security.roles.privileges.resource.database`
+  for which the privilege
+  :setting:`~spec.security.roles.privileges.actions`
+  apply.
+
+  If you provide a value for this setting, you must also provide a value
+  for
+  :setting:`spec.security.roles.privileges.resource.database`.
+
+---
+program: _shared
+name: spec.security.roles.privileges.resource.cluster
+type: boolean
+directive: setting
+optional: true
+default: false
+description: |
+
+  Flag that indicates that the privilege
+  :setting:`~spec.security.roles.privileges.actions`
+  apply to all databases and collections in the MongoDB deployment. If
+  omitted, defaults to ``false``.
+
+  If set to true, do not provide values for
+  :setting:`spec.security.roles.privileges.resource.database`
+  and 
+  :setting:`spec.security.roles.privileges.resource.collection`.
+
+---
+program: _shared
 name: spec.security.authentication.ldap
 type: collection
 directive: setting
diff --git a/source/reference/k8s-operator-specification.txt b/source/reference/k8s-operator-specification.txt
@@ -234,6 +234,18 @@ cluster resource types:
 .. include:: /includes/option/setting-k8sRsConf-spec.security.authentication.agents.automationPasswordSecretRef.rst
 .. include:: /includes/option/setting-k8sRsConf-spec.security.authentication.agents.automationPasswordSecretRef.name.rst
 .. include:: /includes/option/setting-k8sRsConf-spec.security.authentication.agents.automationPasswordSecretRef.key.rst
+.. include:: /includes/option/setting-k8sRsConf-spec.security.roles.rst
+.. include:: /includes/option/setting-k8sRsConf-spec.security.roles.role.rst
+.. include:: /includes/option/setting-k8sRsConf-spec.security.roles.db.rst
+.. include:: /includes/option/setting-k8sRsConf-spec.security.roles.authenticationRestrictions.rst
+.. include:: /includes/option/setting-k8sRsConf-spec.security.roles.authenticationRestrictions.clientSource.rst
+.. include:: /includes/option/setting-k8sRsConf-spec.security.roles.authenticationRestrictions.serverAddress.rst
+.. include:: /includes/option/setting-k8sRsConf-spec.security.roles.privileges.rst
+.. include:: /includes/option/setting-k8sRsConf-spec.security.roles.privileges.actions.rst
+.. include:: /includes/option/setting-k8sRsConf-spec.security.roles.privileges.resource.rst
+.. include:: /includes/option/setting-k8sRsConf-spec.security.roles.privileges.resource.database.rst
+.. include:: /includes/option/setting-k8sRsConf-spec.security.roles.privileges.resource.collection.rst
+.. include:: /includes/option/setting-k8sRsConf-spec.security.roles.privileges.resource.cluster.rst
 
 Examples
 --------
@@ -246,7 +258,7 @@ Examples
        content: |
 
          The following example shows a resource specification for a
-         standlone deployment with every setting provided:
+         standalone deployment with every setting provided:
 
          .. literalinclude:: /reference/k8s/standalonepodspec.yaml
             :language: yaml
