rbac: deprecate RbacConfig with ClusterRbacConfig (#2761)

.spelling

@@ -364,6 +364,7 @@ qps
 quay.io
 radis
 ratelimit-handler
+rbac
 reachability
 rearchitect
 readinessProbe

content/about/notes/1.1/index.md

@@ -11,3 +11,9 @@ TODO announcement
 ## Policies and Telemetry
 
 - **Kiali**. The Service Graph addon has been [deprecated](https://github.com/istio/istio/issues/9066) in favor of [Kiali](https://www.kiali.io). See the [Kiali Task](/docs/tasks/telemetry/kiali/) for more details about Kiali.
+
+## Security
+
+- Deprecated `RbacConfig` replacing it with `ClusterRbacConfig` to implement the correct cluster scope.
+  Refer to our guide on [Migrating the `RbacConfig` to `ClusterRbacConfig`](/docs/setup/kubernetes/upgrading-istio#migrating-the-rbacconfig-to-clusterrbacconfig)
+  for migration instructions.

content/docs/concepts/security/index.md

@@ -585,7 +585,7 @@ In the following example, Istio authorization permissive mode is set on global c
 
 {{< text yaml >}}
 apiVersion: "rbac.istio.io/v1alpha1"
-kind: RbacConfig
+kind: ClusterRbacConfig
 metadata:
   name: default
 spec:
@@ -614,14 +614,14 @@ spec:
 
 ### Enabling authorization
 
-You enable Istio Authorization using a `RbacConfig` object. The `RbacConfig`
-object is a mesh-wide singleton with a fixed name value of `default`. You can
-only use one `RbacConfig` instance in the mesh. Like other Istio configuration
-objects, `RbacConfig` is defined as a
+You enable Istio Authorization using a `ClusterRbacConfig` object. The `ClusterRbacConfig`
+object is a cluster-scoped singleton with a fixed name value of `default`. You can
+only use one `ClusterRbacConfig` instance in the mesh. Like other Istio configuration
+objects, `ClusterRbacConfig` is defined as a
 Kubernetes `CustomResourceDefinition`
 [(CRD)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) object.
 
-In the `RbacConfig` object, the operator can specify a `mode` value, which can
+In the `ClusterRbacConfig` object, the operator can specify a `mode` value, which can
 be:
 
 - **`OFF`**: Istio authorization is disabled.
@@ -637,7 +637,7 @@ namespace.
 
 {{< text yaml >}}
 apiVersion: "rbac.istio.io/v1alpha1"
-kind: RbacConfig
+kind: ClusterRbacConfig
 metadata:
   name: default
 spec:

content/docs/setup/kubernetes/upgrading-istio/index.md

@@ -255,3 +255,55 @@ spec:
     tls:
       mode: DISABLE
 {{< /text >}}
+
+## Migrating the `RbacConfig` to `ClusterRbacConfig`
+
+The `RbacConfig` is deprecated due to a [bug](https://github.com/istio/istio/issues/8825). You must
+migrate to `ClusterRbacConfig` if you are currently using `RbacConfig`. The bug reduces the scope of
+the object to be namespace-scoped in some cases. The `ClusterRbacConfig` follows the exact same
+specification as the `RbacConfig` but with the correct cluster scope implementation.
+
+To automate the migration, we developed the `convert_RbacConfig_to_ClusterRbacConfig.sh` script.
+The script is included in the [Istio installation package](/docs/setup/kubernetes/download-release).
+
+Download and run the script with the following command:
+
+{{< text bash >}}
+$ curl -L https://raw.githubusercontent.com/istio/istio/master/tools/convert_RbacConfig_to_ClusterRbacConfig.sh | sh -
+{{< /text >}}
+
+The script automates the following operations:
+
+1. The script creates the cluster RBAC configuration with same specification as the existing RBAC configuration
+   because Kubernetes doesn't allow the value of `kind:` in a custom resource to change after it's created.
+
+    For example, if you have the following RBAC configuration:
+
+    {{< text yaml >}}
+    apiVersion: "rbac.istio.io/v1alpha1"
+    kind: RbacConfig
+    metadata:
+      name: default
+    spec:
+      mode: 'ON_WITH_INCLUSION'
+      inclusion:
+        namespaces: ["default"]
+    {{< /text >}}
+
+    The script creates the following cluster RBAC configuration:
+
+    {{< text yaml >}}
+    apiVersion: "rbac.istio.io/v1alpha1"
+    kind: ClusterRbacConfig
+    metadata:
+      name: default
+    spec:
+      mode: 'ON_WITH_INCLUSION'
+      inclusion:
+        namespaces: ["default"]
+    {{< /text >}}
+
+1. The script applies the configuration and waits for a few seconds to let the configuration to take effect.
+
+1. The script deletes the previous RBAC configuration custom resource after applying the cluster RBAC
+   configuration successfully.

content/docs/tasks/security/authz-http/index.md

@@ -89,7 +89,7 @@ Before you start, please make sure that you have finished [preparation task](#be
     {{< text bash >}}
     $ kubectl apply -f - <<EOF
     apiVersion: "rbac.istio.io/v1alpha1"
-    kind: RbacConfig
+    kind: ClusterRbacConfig
     metadata:
       name: default
     spec:

content/docs/tasks/security/rbac-groups/index.md

@@ -139,7 +139,7 @@ wait until the newly defined RBAC policy to take effect.
     {{< text bash >}}
     $ cat <<EOF | kubectl apply -n $NS -f -
     apiVersion: "rbac.istio.io/v1alpha1"
-    kind: RbacConfig
+    kind: ClusterRbacConfig
     metadata:
       name: default
     spec:

content/help/ops/security/debugging-authorization/index.md

@@ -14,15 +14,15 @@ It would be very helpful to also include a cluster state archive in your email b
 
 ## Ensure Authorization is Enabled Correctly
 
-The `rbacConfig` default cluster level singleton custom resource controls the authorization functionality globally.
+The `ClusterRbacConfig` default cluster level singleton custom resource controls the authorization functionality globally.
 
-1. Run the following command to list existing `RbacConfig`:
+1. Run the following command to list existing `ClusterRbacConfig`:
 
     {{< text bash >}}
-    $ kubectl get rbacconfigs.rbac.istio.io --all-namespaces
+    $ kubectl get clusterrbacconfigs.rbac.istio.io --all-namespaces
     {{< /text >}}
 
-1. Verify there is only **one** instance of `RbacConfig` with name `default`. Otherwise, Istio disables the
+1. Verify there is only **one** instance of `ClusterRbacConfig` with name `default`. Otherwise, Istio disables the
 authorization functionality and ignores all policies.
 
     {{< text plain >}}
@@ -30,7 +30,7 @@ authorization functionality and ignores all policies.
     default     default   1d
     {{< /text >}}
 
-1. If there is more than one `RbacConfig` instance, remove any additional `RbacConfig` instances and
+1. If there is more than one `ClusterRbacConfig` instance, remove any additional `ClusterRbacConfig` instances and
 ensure **only one** instance is named `default`.
 
 ## Ensure Pilot Accepts the Policies