Merge pull request openshift#9858 from kalexand-rh/t-3.10-auth-reconcile

fixing auth reconcile command for 3.10

Author: kalexand-rh

admin_guide/manage_rbac.adoc

@@ -20,7 +20,7 @@ xref:../architecture/additional_concepts/authorization.adoc#architecture-additio
 and bindings].
 
 ifdef::openshift-dedicated[]
-Dedicated administrators can view but not manage cluster roles.  They can manage cluster role bindings
+Dedicated administrators can view but not manage cluster roles. They can manage cluster role bindings
 and manage local roles and bindings.
 endif::[]
 

architecture/additional_concepts/authorization.adoc

@@ -430,14 +430,15 @@ ifdef::openshift-enterprise,openshift-origin[]
 
 After any xref:../../upgrading/index.adoc#install-config-upgrading-index[{product-title} cluster
 upgrade], the default roles are updated and automatically reconciled when the
-server is started. Additionally, see
-xref:../../upgrading/manual_upgrades.adoc#updating-policy-definitions[Updating
-Policy Definitions] for instructions on getting other recommendations
-using:
-
-----
-$ oc adm policy reconcile-cluster-roles
-----
+server is started. During reconciliation, any permissions that are missing from
+the default roles are added. If you added more permissions to the role, they are
+not removed.
+
+If you customized the default roles and configured them to prevent automatic
+role reconciliation, you must
+xref:../../upgrading/manual_upgrades.adoc#updating-policy-definitions[manually
+update
+policy definitions] when you upgrade {product-title}.
 
 [[applying-custom-roles-and-permissions]]
 

upgrading/manual_upgrades.adoc

@@ -507,80 +507,42 @@ updated.
 [[updating-policy-definitions]]
 == Updating Policy Definitions
 
-After a cluster upgrade, the default roles
+During a cluster upgrade, and on every restart of any master, the 
 xref:../architecture/additional_concepts/authorization.adoc#roles[default
-cluster roles] are automatically updated. To check if all defaults are set as
-recommended for your environment, run:
+cluster roles] are automatically reconciled to restore any missing permissions.
 
+. If you customized default cluster roles and want to ensure a role reconciliation
+does not modify them, protect each role from reconciliation:
++
 ----
-# oc adm policy reconcile-cluster-roles
+$ oc annotate clusterrole.rbac <role_name> --overwrite rbac.authorization.kubernetes.io/autoupdate=false
 ----
-
++
 [WARNING]
 ====
-If you have customized default cluster roles and want to ensure a role reconciliation
-does not modify those customized roles, annotate them with `openshift.io/reconcile-protect`
-set to `true` when using the old Openshift policy format. When using the new RBAC
-roles, use `rbac.authorization.kubernetes.io/autoupdate` set to `false` instead.
-In doing so, you are responsible for manually updating those roles with any new
-or required permissions during upgrades.
+You must manually update the roles that contain this setting to include any new
+or required permissions after upgrading.
 ====
 
-This command outputs a list of roles that are out of date and their new proposed
-values. For example:
-
-----
-# oc adm policy reconcile-cluster-roles
-apiVersion: v1
-items:
-- apiVersion: v1
-  kind: ClusterRole
-  metadata:
-    creationTimestamp: null
-    name: admin
-  rules:
-  - attributeRestrictions: null
-    resources:
-    - builds/custom
-...
+. Generate a default bootstrap policy template file:
++
 ----
-
+$ oc adm create-bootstrap-policy-file --filename=policy.json
+----
++
 [NOTE]
 ====
-Your output will vary based on the OpenShift version and any local
-customizations you have made. Review the proposed policy carefully.
+The contents of the file vary based on the {product-title} version, but the file 
+contains only the default policies.
 ====
 
-You can either modify this output to re-apply any local policy changes you have
-made, or you can automatically apply the new policy using the following process:
-
-. Reconcile the cluster roles:
-+
-----
-# oc adm policy reconcile-cluster-roles \
-    --additive-only=true \
-    --confirm
-----
+. Update the *_policy.json_* file to include any cluster role customizations.
 
-. Reconcile the cluster role bindings:
-+
-----
-# oc adm policy reconcile-cluster-role-bindings \
-    --exclude-groups=system:authenticated \
-    --exclude-groups=system:authenticated:oauth \
-    --exclude-groups=system:unauthenticated \
-    --exclude-users=system:anonymous \
-    --additive-only=true \
-    --confirm
-----
-+
-Also run:
+. Use the policy file to automatically reconcile roles and role bindings that 
+are not reconcile protected:
 +
 ----
-# oc adm policy reconcile-cluster-role-bindings \
-    system:build-strategy-jenkinspipeline \
-    --confirm \
-    -o name
+$ oc auth reconcile -f policy.json
 ----
 
 . Reconcile security context constraints: