https://issues.redhat.com/browse/ACM-20220 Access apiserver token doc

clusters/cluster_lifecycle/adv_config_cluster.adoc

@@ -474,4 +474,4 @@ spec:
 
 * link:../support_troubleshooting/trouble_cluster_offline_cert_mce.adoc#troubleshooting-imported-clusters-offline-after-certificate-change-mce[Troubleshooting imported clusters offline after certificate change]
 
-* xref:../cluster_lifecycle/cluster_proxy_addon.adoc#cluster-proxy-addon-settings[Configuring proxy settings for cluster proxy add-ons]
+* xref:../cluster_lifecycle/cluster_proxy_addon_config.adoc#cluster-proxy-addon-settings[Enabling proxy settings for cluster proxy add-ons]

clusters/cluster_lifecycle/cluster_lifecycle_intro.adoc

@@ -14,7 +14,7 @@ See the following documentation:
 * xref:../cluster_lifecycle/scale_managed_intro.adoc#scaling-managed-intro[Scaling managed clusters]
 * xref:../cluster_lifecycle/hibernate_created_cluster.adoc#hibernating-a-created-cluster[Hibernating a created cluster]
 * xref:../cluster_lifecycle/upgrade_cluster.adoc#upgrading-your-cluster[Upgrading your cluster]
-* xref:../cluster_lifecycle/cluster_proxy_addon.adoc#cluster-proxy-addon[Enabling cluster proxy add-ons]
+* xref:../cluster_lifecycle/cluster_proxy_addon_config.ado#config-cluster-proxy-addon[Enabling cluster proxy add-ons]
 * xref:../cluster_lifecycle/ansible_config_cluster.adoc#ansible-config-cluster[Configuring {aap-short} tasks to run on managed clusters]
 * xref:../cluster_lifecycle/clusterclaims.adoc#clusterclaims[ClusterClaims]
 * xref:../cluster_lifecycle/clusterset_intro.adoc#managedclustersets-intro[_ManagedClusterSets_]

clusters/cluster_lifecycle/cluster_proxy_addon.adoc → clusters/cluster_lifecycle/cluster_proxy_addon_config.adoc

@@ -1,13 +1,16 @@
-[#cluster-proxy-addon]
-= Using cluster proxy add-ons
+[#config-cluster-proxy-addon]
+= Enabling cluster proxy add-ons
 
-In some environments, a managed cluster is behind a firewall and cannot be accessed directly by the hub cluster. To gain access, you can set up a proxy add-on to access the `kube-apiserver` of the managed cluster to provide a more secure connection.
+In some environments, a managed cluster is behind a firewall and that you cannot access directly through the hub cluster. To gain access, you can set up a proxy add-on to access the `kube-apiserver` of the managed cluster with a more secure connection.
 
-*Important:* There must not be a cluster-wide proxy configuration on your hub cluster.
+*Important:* To use cluster proxy add-ons, you cannot have a cluster-wide proxy configuration on your hub cluster.
 
 *Required access:* Editor
 
-To configure a cluster proxy add-on for a hub cluster and a managed cluster, complete the following steps:
+[#config-cluster-proxy-addon]
+= Configuring cluster proxy add-ons for hub clusters and managed clusters
+
+To configure a cluster proxy add-on for a hub cluster or managed cluster, complete the following steps:
 
 . Configure the `kubeconfig` file to access the managed cluster `kube-apiserver` by completing the following steps:
 
@@ -121,6 +124,7 @@ You can configure the proxy settings for cluster proxy add-ons to allow a manage
 To configure the proxy settings for the cluster proxy add-on, complete the following steps:
 
 . Create an `AddOnDeploymentConfig` resource on your hub cluster and add the `spec.proxyConfig` parameter. See the following example:
+
 +
 [source,yaml]
 ----
@@ -143,6 +147,7 @@ spec:
 <5> If you specify a HTTPS proxy in the `httpsProxy` field, set the proxy server CA bundle.
 
 . Update the `ManagedClusterAddOn` resource by referencing the `AddOnDeploymentConfig` resource that you created. See the following example:
+
 +
 [source,yaml]
 ----

clusters/cluster_lifecycle/cluster_proxy_addon_use.adoc

@@ -0,0 +1,109 @@
+[#use-cluster-proxy-addon]
+= Using cluster proxy add-ons
+
+Use cluster proxy add-ons to access the managed cluster kube API server or managed cluster services by using different methods. See the following topics to learn more about the different ways you can use cluster proxy add-ons:
+
+* <<use-cluster-proxy-addon-prereq,Prerequisites>>
+* <<access-kube-apiserver-managed-token,Accessing the managed cluster `kube-apiserver` by using a managed cluster user token>>
+* <<access-kube-apiserver-hub-token,Accessing the managed cluster `kube-apiserver` by using a hub cluster user token>>
+* <<access-managed-cluster-services,Accessing managed cluster services>>
+
+*Required access:* Editor
+
+[#use-cluster-proxy-addon-prereq]
+== Prerequisites
+
+* You must xref:../cluster_proxy_addon_config#config-cluster-proxy-addon[enable cluster proxy add-ons].
+
+[#access-kube-apiserver-managed-token]
+== Accessing the managed cluster `kube-apiserver` by using a managed cluster user token
+
+Use the cluster proxy add-on to list pods in the default namespace of a managed cluster by completing the following steps:
+
+. Export your cluster proxy URL by running the following command. Replace values where needed:
+
++
+[source,bash]
+----
+export CLUSTER_PROXY_URL=https://$(oc get route -n multicluster-engine cluster-proxy-addon-user -o=jsonpath='{.spec.host}')/<managed-cluster-name>
+----
+
+. Get the `ConfigMap` by running the following command:
+
++
+[source,bash]
+----
+oc get configmap kube-root-ca.crt -o=jsonpath='{.data.ca\.crt}' > hub-ca.crt
+----
+
+. Transfer your certificate authority (CA) certificate by running the following command:
+
++
+[source,bash]
+----
+curl --cacert hub-ca.crt -H "Authorization: Bearer $TOKEN" https://$CLUSTER_PROXY_URL/api/v1/namespaces/default/pods 
+----
++
+*Note:* You need a user token that has permission to list pods in the default namespace of the managed cluster.
+
+[#access-kube-apiserver-hub-token]
+== Accessing the `kube-apiserver` of a managed cluster by using a hub cluster user token
+
+The target hub cluster and target managed cluster both need to use the same external identity provider so that both clusters can recognize the same user.
+
+To list pods in the default namespace by using the the hub cluster `developer` user token, you must first create the correct `Role` and `RoleBinding` for the `developer` on the managed cluster.
+
+If you are using {rhacm}, you can use the `ClusterPermission` API to create `Role` and `RoleBinding` objects from the hub cluster.
+
+See the following example that binds the `get` and `list` permissions for pods to the user `developer`:
+
+[source,yaml]
+----
+apiVersion: rbac.open-cluster-management.io/v1alpha1
+kind: ClusterPermission
+metadata:
+  name: <name>
+  namespace: <cluster-namespace>
+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 
+----
+
+[#access-managed-cluster-services]
+== Accessing managed cluster services
+
+To access managed cluster services, the managed cluster must be an {ocp} cluster and the service must use the `services-serving-certificate` service to generate server certificates.
+
+Complete the following steps:
+
+. Get the Prometheus service token from the managed cluster. Run the following command:
+
++
+[source,bash]
+----
+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)
+----
+
+. Get the Prometheus managed cluster metrics from the hub cluster. Run the following commands:
+
++
+[source,bash]
+----
+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" 
+----

clusters/main.adoc

@@ -60,7 +60,8 @@ include::cluster_lifecycle/scale_node_ctrl_plane.adoc[leveloffset=+4]
 include::cluster_lifecycle/hibernate_created_cluster.adoc[leveloffset=+3]
 include::cluster_lifecycle/upgrade_cluster.adoc[leveloffset=+3]
 include::cluster_lifecycle/upgrade_cluster_disconnected.adoc[leveloffset=+4]
-include::cluster_lifecycle/cluster_proxy_addon.adoc[leveloffset=+3]
+include::cluster_lifecycle/cluster_proxy_addon_config.adoc[leveloffset=+3]
+include::cluster_lifecycle/cluster_proxy_addon_use.adoc[leveloffset=+3]
 include::cluster_lifecycle/ansible_config_cluster.adoc[leveloffset=+3]
 include::cluster_lifecycle/ansible_config_hosted_cluster.adoc[leveloffset=+3]
 include::cluster_lifecycle/clusterclaims.adoc[leveloffset=+3]

clusters/release_notes/mce_known_issues.adoc

@@ -186,7 +186,7 @@ The search details page for a certain resource on a certain managed cluster migh
 
 The `ManagedServiceAccount` and cluster proxy add-ons are enabled by default in {acm-short} version 2.10 and newer. If the add-ons are disabled after upgrading, you must enable the `ManagedServiceAccount` and cluster proxy add-ons manually to use the pod log feature on non-{ocp-short} managed clusters.
 
-See link:../../clusters/install_upgrade/adv_config_install.adoc#serviceaccount-addon-intro[ManagedServiceAccount add-on] to learn how to enable `ManagedServiceAccount` and see link:../../clusters/cluster_lifecycle/cluster_proxy_addon.adoc#cluster-proxy-addon[Using cluster proxy add-ons] to learn how to enable a cluster proxy add-on.
+See link:../../clusters/install_upgrade/adv_config_install.adoc#serviceaccount-addon-intro[ManagedServiceAccount add-on] to learn how to enable `ManagedServiceAccount` and see link:../../clusters/cluster_lifecycle/cluster_proxy_addon_config.adoc#config-cluster-proxy-addon[Configuring cluster proxy add-ons] to learn how to enable a cluster proxy add-on.
 
 [#hypershift-proxy-install-not-supported-ocp-410z]
 === {ocp-short} 4.10.z does not support hosted control plane clusters with proxy configuration

clusters/release_notes/mce_whats_new.adoc

@@ -40,6 +40,7 @@ Learn about new features and enhancements that come with the {mce-short} install
 Learn about new features and enhancements for Cluster lifecycle with {mce-short}.
 
 - You can now define a unique mirror registry for each cluster. To learn more, see xref:../assisted_installer#config-mirror-reg-cluster[Configuring mirror registries for each cluster]
+- You can now access the `kube-apiserver` of a managed cluster by using a hub cluster user token. To learn more, see xref:../cluster_proxy_addon_use#access-kube-apiserver-hub-token[Accessing the `kube-apiserver` of a managed cluster by using a hub cluster user token].
 
 [#mce-acm-integration]
 === {mce-short} with {acm-short} integration