From 42a3a93c6f665c6518e9d92f7784644837a49a9d Mon Sep 17 00:00:00 2001 From: ruquanzhao <903264308@qq.com> Date: Thu, 9 Jan 2025 22:07:13 +0800 Subject: [PATCH] docs: update guide of enableRbac in production environment (#582) --- .../1-getting-started/2-installation.md | 2 +- .../karpor/1-getting-started/3-quick-start.md | 28 ++----------------- .../3-user-guide/1-how-to-create-token.md | 15 ++++++++++ .../1-getting-started/3-quick-start.md | 28 ++----------------- .../3-user-guide/1-how-to-create-token.md | 16 +++++++++++ 5 files changed, 38 insertions(+), 51 deletions(-) diff --git a/docs/karpor/1-getting-started/2-installation.md b/docs/karpor/1-getting-started/2-installation.md index 9793f7d3..d037f1e8 100644 --- a/docs/karpor/1-getting-started/2-installation.md +++ b/docs/karpor/1-getting-started/2-installation.md @@ -49,7 +49,7 @@ helm repo update helm search repo kusionstack/karpor --versions ``` -### Upgrade specified version +### Upgrade specified version You can specify the version to be upgraded through the `--version`. diff --git a/docs/karpor/1-getting-started/3-quick-start.md b/docs/karpor/1-getting-started/3-quick-start.md index d0179bb2..47ea1bcf 100644 --- a/docs/karpor/1-getting-started/3-quick-start.md +++ b/docs/karpor/1-getting-started/3-quick-start.md @@ -57,33 +57,11 @@ This will open the Karpor Web interface. 👇 Congratulations! 🎉 You have successfully installed Karpor. Now you can start using Karpor to explore and gain insights into resources across multiple clusters. -## Create Access Token +## Enable RBAC when installing karpor (optional) -Before registering clusters, you need to create an access token to log in to the Karpor Web interface. Here are the brief steps to create a token: +To facilitate users in quickly getting started with Karpor, the RBAC (Role-Based Access Control) authentication feature of `karpor-server` is disabled by default. This means that `karpor-server` will accept all requests. However, this approach can introduce significant risks in a production environment. We strongly recommend using RBAC authentication to protect data security when deploying Karpor in a production setting. -1. Export the KubeConfig of the Hub Cluster: - -```shell -kubectl get configmap karpor-kubeconfig -n karpor -o go-template='{{.data.config}}' > $HOME/.kube/karpor-hub-cluster.kubeconfig -``` - -2. Create ServiceAccount and ClusterRoleBinding: - -```shell -export KUBECONFIG=$HOME/.kube/karpor-hub-cluster.kubeconfig -kubectl create serviceaccount karpor-admin -kubectl create clusterrolebinding karpor-admin --clusterrole=karpor-admin --serviceaccount=default:karpor-admin -``` - -3. Create token: - -```shell -kubectl create token karpor-admin --duration=1000h -``` - -Copy the generated token, which will be used later to log in to the Karpor Web interface. - -For detailed instructions on creating tokens, please refer to the [How to Create Token](../3-user-guide/1-how-to-create-token.md) documentation. +For detailed instructions on RBAC authorization and tokens, please refer to the [How to Create Token](../3-user-guide/1-how-to-create-token.md) documentation. ## Register Cluster diff --git a/docs/karpor/3-user-guide/1-how-to-create-token.md b/docs/karpor/3-user-guide/1-how-to-create-token.md index 3e2ef484..304ec445 100644 --- a/docs/karpor/3-user-guide/1-how-to-create-token.md +++ b/docs/karpor/3-user-guide/1-how-to-create-token.md @@ -5,9 +5,20 @@ In this document, you will learn how to use a token to access the Karpor dashboa [Hub Cluster](../2-concepts/3-glossary.md#hub-cluster) adopts the same Role-Based Access Control (RBAC) mechanism as Kubernetes. This means that in order to access the Hub Cluster, users need to create a ClusterRole, ServiceAccount, and the corresponding ClusterRoleBinding in the Hub Cluster to bind the two. To enhance user experience, we have preset two ClusterRoles: karpor-admin and karpor-guest. The karpor-admin role has permissions to perform all actions on the dashboard, including but not limited to adding or deleting clusters, creating resource groups, etc., while the karpor-guest role is limited to view-only actions on the dashboard. As users gain a deeper understanding of Karpor, they can create additional ClusterRoles based on their needs to achieve more granular permission management. +## Enable RBAC when installing karpor + +To facilitate users in quickly getting started with Karpor, the RBAC (Role-Based Access Control) authentication feature of `karpor-server` is disabled by default. This means that `karpor-server` will accept all requests. However, this approach can introduce significant risks in a production environment. We strongly recommend using RBAC authentication to protect data security when deploying Karpor in a production setting. Follow the instructions below to enable the RBAC feature during Karpor installation. + +```shell +helm repo add kusionstack https://kusionstack.github.io/charts +helm repo update +helm install karpor kusionstack/karpor --set server.enableRbac=true +``` + ## Exporting the KubeConfig for the Hub Cluster Since the Hub Cluster requires a KubeConfig for authentication, you can export the KubeConfig to access the Hub Cluster using the following command. + ```shell # The following operation is performed in the Kubernetes cluster where Karpor is installed kubectl get configmap karpor-kubeconfig -n karpor -o go-template='{{.data.config}}' > $HOME/.kube/karpor-hub-cluster.kubeconfig @@ -18,11 +29,13 @@ kubectl get configmap karpor-kubeconfig -n karpor -o go-template='{{.data.config You can use the following sed command to change the access address in the Hub Cluster certificate to the local address: For MacOS/BSD systems (need an extra `''` after `-i`): + ```shell sed -i '' 's/karpor-server.karpor.svc/127.0.0.1/g' $HOME/.kube/karpor-hub-cluster.kubeconfig ``` For Linux/GNU systems (only `-i`): + ```shell sed -i 's/karpor-server.karpor.svc/127.0.0.1/g' $HOME/.kube/karpor-hub-cluster.kubeconfig ``` @@ -46,6 +59,7 @@ kubectl -n karpor port-forward svc/karpor-server 7443:7443 This section will guide you on how to create karpor-admin and karpor-guest users in the Hub Cluster and assign the corresponding ClusterRoleBinding to them. Here are the specific steps: First, specify the target cluster for kubectl to connect to as the Hub Cluster: + ```shell export KUBECONFIG=$HOME/.kube/karpor-hub-cluster.kubeconfig ``` @@ -62,6 +76,7 @@ kubectl create clusterrolebinding karpor-guest --clusterrole=karpor-guest --serv ## Create Tokens for Your Users The following operations need to be performed in the Hub Cluster. Please ensure that kubectl is correctly set to connect to the Hub Cluster: + ```shell export KUBECONFIG=$HOME/.kube/karpor-hub-cluster.kubeconfig ``` diff --git a/i18n/zh/docusaurus-plugin-content-docs-karpor/current/1-getting-started/3-quick-start.md b/i18n/zh/docusaurus-plugin-content-docs-karpor/current/1-getting-started/3-quick-start.md index 6d1d3afe..a669e4b7 100644 --- a/i18n/zh/docusaurus-plugin-content-docs-karpor/current/1-getting-started/3-quick-start.md +++ b/i18n/zh/docusaurus-plugin-content-docs-karpor/current/1-getting-started/3-quick-start.md @@ -57,33 +57,11 @@ helm install karpor kusionstack/karpor 祝贺你！🎉 你已成功安装 Karpor。现在你可以开始使用 Karpor 探索和洞察多集群中的资源。 -## 创建访问令牌 +## 在安装 Karpor 时启用 RBAC 功能（可选） -在注册集群之前，你需要创建一个访问令牌来登录 Karpor Web 界面。以下是创建令牌的简要步骤： +为了方便用户快速上手 Karpor，`karpor-server` 的 RBAC（基于角色的访问控制）认证功能默认是关闭的。这意味着 `karpor-server` 会接受所有请求。然而，这种做法在生产环境中可能会带来显著的风险。我们强烈建议在生产环境中部署 Karpor 时启用 RBAC 认证功能，以保护数据安全。 -1. 导出 Hub Cluster 的 KubeConfig: - -```shell -kubectl get configmap karpor-kubeconfig -n karpor -o go-template='{{.data.config}}' > $HOME/.kube/karpor-hub-cluster.kubeconfig -``` - -2. 创建 ServiceAccount 和 ClusterRoleBinding: - -```shell -export KUBECONFIG=$HOME/.kube/karpor-hub-cluster.kubeconfig -kubectl create serviceaccount karpor-admin -kubectl create clusterrolebinding karpor-admin --clusterrole=karpor-admin --serviceaccount=default:karpor-admin -``` - -3. 创建令牌: - -```shell -kubectl create token karpor-admin --duration=1000h -``` - -复制生成的令牌,稍后将用于登录 Karpor Web 界面。 - -有关创建令牌的详细说明,请参阅 [如何创建 Token](../3-user-guide/1-how-to-create-token.md) 文档。 +有关 RBAC 鉴权和创建令牌的详细说明,请参阅 [如何创建 Token](../3-user-guide/1-how-to-create-token.md) 文档。 ## 注册集群 diff --git a/i18n/zh/docusaurus-plugin-content-docs-karpor/current/3-user-guide/1-how-to-create-token.md b/i18n/zh/docusaurus-plugin-content-docs-karpor/current/3-user-guide/1-how-to-create-token.md index bd72e5c5..6e8f293e 100644 --- a/i18n/zh/docusaurus-plugin-content-docs-karpor/current/3-user-guide/1-how-to-create-token.md +++ b/i18n/zh/docusaurus-plugin-content-docs-karpor/current/3-user-guide/1-how-to-create-token.md @@ -5,9 +5,20 @@ title: 如何创建 Token [Hub Cluster](../2-concepts/3-glossary.md#hub-cluster) 采用了与 Kubernetes 相同的基于角色的访问控制（RBAC）机制。这意味着，要访问 Hub Cluster，用户需要在 Hub Cluster 上创建 ClusterRole、ServiceAccount，以及相应的 ClusterRoleBinding 来将两者绑定。为了提升用户体验，我们预设了两种 ClusterRole：karpor-admin 和 karpor-guest。karpor-admin 角色拥有在面板上执行所有操作的权限，包括但不限于添加或删除集群、创建资源组等；而 karpor-guest 角色则仅限于在面板上进行查看操作。随着对 Karpor 的深入了解，用户可以根据自身需求，创建额外的 ClusterRole，实现更细致的权限管理。 +## 在安装 Karpor 时启用 RBAC 功能 + +为了方便用户快速上手 Karpor，`karpor-server` 的 RBAC（基于角色的访问控制）认证功能默认是关闭的。这意味着 `karpor-server` 会接受所有请求。然而，这种做法在生产环境中可能会带来显著的风险。我们强烈建议在生产环境中部署 Karpor 时启用 RBAC 认证功能，以保护数据安全。请按照以下说明在安装 Karpor 时启用 RBAC 功能。 + +```shell +helm repo add kusionstack https://kusionstack.github.io/charts +helm repo update +helm install karpor kusionstack/karpor --set server.enableRbac=true +``` + ## 导出 Hub Cluster 的 KubeConfig 由于 Hub Cluster 需要 KubeConfig 进行验证，可以通过以下命令一键导出用于访问 Hub Cluster 的 KubeConfig。 + ```shell # 以下操作在安装 Karpor 的 Kubernetes 集群中运行 kubectl get configmap karpor-kubeconfig -n karpor -o go-template='{{.data.config}}' > $HOME/.kube/karpor-hub-cluster.kubeconfig @@ -18,11 +29,13 @@ kubectl get configmap karpor-kubeconfig -n karpor -o go-template='{{.data.config 你可以使用以下 sed 命令将 Hub 集群证书中的访问地址更改为本地地址： 对于 MacOS/BSD 系统（需要在 `-i` 后添加 `''`）： + ```shell sed -i '' 's/karpor-server.karpor.svc/127.0.0.1/g' $HOME/.kube/karpor-hub-cluster.kubeconfig ``` 对于 Linux/GNU 系统（仅需要 `-i`）： + ```shell sed -i 's/karpor-server.karpor.svc/127.0.0.1/g' $HOME/.kube/karpor-hub-cluster.kubeconfig ``` @@ -46,6 +59,7 @@ kubectl -n karpor port-forward svc/karpor-server 7443:7443 本节将指导你如何在 Hub Cluster 中创建 karpor-admin 和 karpor-guest 用户，并为它们分配相应的 ClusterRoleBinding。以下是具体的操作步骤： 首先，指定 kubectl 连接的目标集群为 Hub Cluster： + ```shell export KUBECONFIG=$HOME/.kube/karpor-hub-cluster.kubeconfig ``` @@ -62,11 +76,13 @@ kubectl create clusterrolebinding karpor-guest --clusterrole=karpor-guest --serv ## 为你的用户创建 Token 以下操作需在 Hub Cluster 中执行，请确保已正确设置 kubectl 连接到 Hub Cluster： + ```shell export KUBECONFIG=$HOME/.kube/karpor-hub-cluster.kubeconfig ``` 默认情况下，token 的有效期为 1 小时。如果你需要长期使用的 token，可以在生成时指定更长的过期时间。例如： + ```shell kubectl create token karpor-admin --duration=1000h ```