Note: Doc team updates the current version of the documentation and the
two previous versions (n-2), but we address *only high-priority, or
customer-reported issues* for -2 releases in support.
Describe the changes in the doc and link to your dev story:

1. - [x] Mandatory: Add the required version to the Fix version/s field.

2. - [ ] Mandatory: Choose the type of documentation change or review.

• [x] We need to update to an existing topic

• [x] We need to add a new document to an existing section

• [ ] We need a whole new section; this is a function not
  documented before and doesn't belong in any current section

• [ ] We need an Operator Advisory review and approval

• [ ] We need a z-Stream (Errata) Advisory and Release note for
  MCE and/or ACM

3. - [x] Mandatory: Find the link to where the documentation update
should go and add it to the recommended changes. You can either use the
published doc or the staged repo for this step:

Note: As the feature and doc is understood, this recommendation may
change. If this is new documentation, link to the section where you think
it should be placed.

https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.13/html/clusters/cluster_mce_overview#cluster-proxy-addon

(The new content)

Using the cluster-proxy-addon allows users to:

• Access the managed cluster's kube API server using a managed cluster user token.
• Access the managed cluster's kube API server using a hub user token (requires both the hub and the managed cluster to use the same external IDP).
• Access managed cluster services (the managed cluster must be OCP, and the service must use `services-serving-certificates` to generate server certificates).

1. Accessing the managed cluster’s kube-apiserver using a managed cluster user token.

The following command demonstrates how to use the cluster-proxy-addon to list pods in the default namespace of a managed cluster.

Ensure that the TOKEN used in the final step belongs to a user with permission to list pods in the default namespace of this managed cluster.

export CLUSTER_PROXY_URL=https://$(oc get route -n multicluster-engine cluster-proxy-addon-user -o=jsonpath='{.spec.host}')/<managed-cluster-name>

oc get configmap kube-root-ca.crt -o=jsonpath='{.data.ca\.crt}' > hub-ca.crt

curl --cacert hub-ca.crt -H "Authorization: Bearer $TOKEN" https://$CLUSTER_PROXY_URL/api/v1/namespaces/default/pods 

2. Accessing the managed cluster’s kube-apiserver using a hub user token.

This scenario requires both the hub and the target managed cluster to use the same external IDP, so that the same user can be recognized by both sides.
And if a user wants to list pods in the default namespace using the TOKEN of the hub user `developer`, the user must first create the appropriate Role and RoleBinding for the `developer` on the managed cluster.

ACM provides the `ClusterPermission` API to help users easily create Roles and RoleBindings from the hub side. Here is an example that binds the get and list permissions for pods to the user `developer`:

apiVersion: rbac.open-cluster-management.io/v1alpha1
kind: ClusterPermission
metadata:
  name: test
  namespace: cluster1
spec:
  roles:
  - namespace: default
    rules:
    - apiGroups: [""]
      resources: ["pods"]
      verbs: ["get","list"]
  roleBindings:
  - namespace: default
    roleRef:
      kind: Role
    subject:
      apiGroup: rbac.authorization.k8s.io
      kind: User
      name: developer 

3. Accessing managed cluster services(requires managed cluster must be OCP, and the service must user services-serving-certificate to generate server certificates)

Using Prometheus for example, first you need to get the token of prometheus service from the managed cluster side:

export PROMETHEUS_TOKEN=$(kubectl get secret -n openshift-monitoring $(kubectl get serviceaccount -n openshift-monitoring prometheus-k8s -o=jsonpath='{.secrets[0].name}') -o=jsonpath='{.data.token}' | base64 -d) 

Then you can get Prometheus metrics of the managed cluster from the hub side by using the following commands:

export SERVICE_NAMESPACE=openshift-monitoring
export SERVICE_NAME=prometheus-k8s
export SERVICE_PORT=9091
export SERVICE_PATH="api/v1/query?query=machine_cpu_sockets"

curl --cacert hub-ca.crt $CLUSTER_PROXY_URL/api/v1/namespaces/$SERVICE_NAMESPACE/services/$SERVICE_NAME:$SERVICE_PORT/proxy-service/$SERVICE_PATH -H "Authorization: Bearer $PROMETHEUS_TOKEN" 

Customer Portal published version

https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.12

Doc staged repo within the ACM Workspace:
https://github.com/stolostron/rhacm-docs

4. - [ ] Mandatory for GA content:

• [ ] Add steps, the diff, known issue, and/or other important
  conceptual information in the following space:

• [ ] *Add Required access level *(example, *Cluster
  Administrator*) for the user to complete the task:

• [ ] Add verification at the end of the task, how does the user
  verify success (a command to run or a result to see?)

• [x] Add link to dev story here: https://issues.redhat.com/browse/ACM-19584 

5. - [ ] Mandatory for bugs: What is the diff? Clearly define what the
problem is, what the change is, and link to the current documentation. Only
use this for a documentation bug.