Skip to content

Commit

Permalink
docs: adjust description and style in create token (#557)
Browse files Browse the repository at this point in the history 
* docs: adjust export kubeconfig description in create token

* docs: adjust style
  • Loading branch information
@elliotxx
elliotxx authored Sep 29, 2024
1 parent 4f08599 commit abaeb27
Show file tree
Hide file tree
Showing 2 changed files with 40 additions and 36 deletions.
40 changes: 21 additions & 19 deletions docs/karpor/3-user-guide/1-how-to-create-token.md
View file
Original file line number Diff line number Diff line change
@@ -1,52 +1,53 @@
---
title: How to create token
title: How to Create Token
---
In this document, you will learn how to use a token to access the Karpor dashboard.

[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.
[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.

## 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 method.

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 operations are performed in the Kubernetes cluster where Karpor is installed.
kubectl get configmap karpor-kubeconfig -n karpor -o yaml
# 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}}'
```

Then export the kubeconfig from the data field of this config map to your local environment.
**Note**: Please ensure that the server address in the Hub Cluster's kubeconfig is accessible from your local machine. If you deployed Karpor in a local cluster, you need to forward the karpor-server service to local port 7443 and change the server address to `https://127.0.0.1:7443`.

## Forward the Services of the Hub Cluster to the Local Machine

## Forward the services of the hub cluster to the local machine
In this section, we assume that you have deployed Karpor in a local cluster.

Next, you need to forward the service of karpor-server to your local machine. If you have used other methods for forwarding, you can skip this step. Here, we will use a simple port-forwarding method. Open another terminal and run:
As mentioned in the previous section, to access the Hub Cluster locally, you need to forward the karpor-server service to your local machine. If you have used other methods for forwarding, you can skip this step. Here, we will use a simple port-forwarding method. Open another terminal and run:

```shell
# The following operations are performed in the Kubernetes cluster where Karpor is installed.
# The following operation is performed in the Kubernetes cluster where Karpor is installed
kubectl -n karpor port-forward svc/karpor-server 7443:7443
```

## Create ServiceAccount and ClusterRoleBinding for your users
## Create ServiceAccount and ClusterRoleBinding for Your Users

You can use the following commands to create karpor-admin and karpor-guest along with the corresponding clusterrolebinding in the hub cluster:
You can use the following commands to create karpor-admin and karpor-guest along with the corresponding ClusterRoleBinding in the Hub Cluster:

```shell
# The following commands run in the hub cluster.
# createa ServiceAccount karpor-admin and bind to clusterrole
export KUBECONFIG=<Hub cluster KUBECONFIG>
# The following commands run in the Hub Cluster
# Create ServiceAccount karpor-admin and bind to ClusterRole
export KUBECONFIG=<Hub Cluster KUBECONFIG>
kubectl create serviceaccount karpor-admin
kubectl create clusterrolebinding karpor-admin --clusterrole=karpor-admin --serviceaccount=default:karpor-admin
# createa ServiceAccount karpor-guest and bind to clusterrole
# Create ServiceAccount karpor-guest and bind to ClusterRole
kubectl create serviceaccount karpor-guest
kubectl create clusterrolebinding karpor-guest --clusterrole=karpor-guest --serviceaccount=default:karpor-guest
```

## Create tokens for your users
## Create Tokens for Your Users

By default, the validity period of a token is 1 hour. If you need a long-term token, you can specify the expiration time when generating the token. For example:

```shell
# The following commands run in the hub cluster.
export KUBECONFIG=<Hub cluster KUBECONFIG>
# The following commands run in the Hub Cluster
export KUBECONFIG=<Hub Cluster KUBECONFIG>
kubectl create token karpor-admin --duration=1000h
```

Expand All @@ -57,3 +58,4 @@ By default, the maximum validity period of the token is 8760 hours (1 year). If
Copy the token you just generated and paste it into the token input box on the Karpor dashboard, then click login.

Start your Karpor journey in a secure environment!

36 changes: 19 additions & 17 deletions ...saurus-plugin-content-docs-karpor/current/3-user-guide/1-how-to-create-token.md
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,25 @@
---
title: 如何创建 token
title: 如何创建 Token
---
在这篇文档中，你将了解如何使用 token 访问 Karpor dashboard。

[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，实现更细致的权限管理。
[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，实现更细致的权限管理。

## 导出 Hub Cluster 的 kubeconfig

由于 hub cluster 需要 kubeconfig 进行验证，可以通过以下方法导出将用于访问 hub cluster 的 kubeconfig。
## 导出 Hub Cluster 的 Kubeconfig

由于 Hub Cluster 需要 kubeconfig 进行验证，可以通过以下命令一键导出用于访问 Hub Cluster 的 kubeconfig。
```shell
# 以下操作在安装 Karpor 的 Kubernetes 集群中运行
kubectl get configmap karpor-kubeconfig -n karpor -o yaml
kubectl get configmap karpor-kubeconfig -n karpor -o go-template='{{.data.config}}'
```

然后把这个 configmap 的 data 字段中的 kubeconfig 导出到你的本地环境。
**注意**：请确保本地机器可访问 Hub Cluster 的 kubeconfig 中的 server 地址。如在本地集群部署 Karpor，需将 karpor-server 服务转发至本地端口 7443，并将 server 地址改为 `https://127.0.0.1:7443`。

## 将 Hub Cluster 的服务转发到本地

## 将 hub cluster 的服务转发到本地
在本节中，我们假设你将 Karpor 部署在了本地集群。

接下来，你需要将 karpor-server 的服务转发到本地。如果你使用了其他方法进行了转发，可以跳过这一步。这里使用简单的 port-forward 进行转发，打开另一个终端，运行：
如上节所说，为了在本地访问 Hub Cluster，你需要将 karpor-server 的服务转发到本地。如果你使用了其他方法进行了转发，可以跳过这一步。这里使用简单的 port-forward 进行转发，打开另一个终端，运行：

```shell
# 以下操作在安装 Karpor 的 Kubernetes 集群中运行
Expand All @@ -27,26 +28,26 @@ kubectl -n karpor port-forward svc/karpor-server 7443:7443

## 为你的用户创建 ServiceAccount 和 ClusterRoleBinding

你可以用如下命令在 hub cluster 中创建 karpor-admin 和 karpor-guest 以及对应 clusterrolebinding:
你可以用如下命令在 Hub Cluster 中创建 karpor-admin 和 karpor-guest 以及对应 ClusterRoleBinding:

```shell
# 以下操作在 hub cluster 中运行
# 创建 karpor-admin 并绑定到 clusterrole
export KUBECONFIG=<Hub cluster KUBECONFIG>
# 以下操作在 Hub Cluster 中运行
# 创建 ServiceAccount karpor-admin 并绑定到 ClusterRole
export KUBECONFIG=<Hub Cluster KUBECONFIG>
kubectl create serviceaccount karpor-admin
kubectl create clusterrolebinding karpor-admin --clusterrole=karpor-admin --serviceaccount=default:karpor-admin
# 创建 karpor-guest 并绑定到 clusterrole
# 创建 ServiceAccount karpor-guest 并绑定到 ClusterRole
kubectl create serviceaccount karpor-guest
kubectl create clusterrolebinding karpor-guest --clusterrole=karpor-guest --serviceaccount=default:karpor-guest
```

## 为你的用户创建 token
## 为你的用户创建 Token

默认情况下，token 的有效期是 1 个小时。如果你需要长期 token，可以指定在生成 token 时指定过期时间。比如：

```shell
# 以下操作在 hub 集群中运行
export KUBECONFIG=<Hub cluster KUBECONFIG>
# 以下操作在 Hub Cluster 中运行
export KUBECONFIG=<Hub Cluster KUBECONFIG>
kubectl create token karpor-admin --duration=1000h
```

Expand All @@ -57,3 +58,4 @@ kubectl create token karpor-admin --duration=1000h
复制刚刚生成的 token，粘贴到 Karpor dashboard 的 token 输入框中， 点击登录。

在安全环境下开启你的 Karpor 之旅吧！

0 comments on commit abaeb27

Please sign in to comment.