Skip to content

docs: improve clarity of creating-sample-user.md documentation #10369

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: improve clarity of creating-sample-user.md documentation #10369

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 56 additions & 20 deletions docs/user/access-control/creating-sample-user.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,7 @@ metadata:

## Creating a ClusterRoleBinding

In most cases after provisioning the cluster using `kops`, `kubeadm` or any other popular tool, the `ClusterRole` `cluster-admin` already exists in the cluster. We can use it and create only a `ClusterRoleBinding` for our `ServiceAccount`.
If it does not exist then you need to create this role first and grant required privileges manually.
In most cases after provisioning the cluster using `kops`, `kubeadm` or any other popular tool, the `ClusterRole` `cluster-admin` already exists in the cluster. We can use it and create only a `ClusterRoleBinding` for our `ServiceAccount`. If it does not exist then you need to create this role first and grant required privileges manually.

```yaml
apiVersion: rbac.authorization.k8s.io/v1
Expand All @@ -40,7 +39,7 @@ subjects:

Now we need to find the token we can use to log in. Execute the following command:

```shell
```bash
kubectl -n kubernetes-dashboard create token admin-user
```

Expand All @@ -50,11 +49,26 @@ It should print something like:
eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9.eyJpc3MiOiJrdWJlcm5ldGVzL3NlcnZpY2VhY2NvdW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9uYW1lc3BhY2UiOiJrdWJlcm5ldGVzLWRhc2hib2FyZCIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VjcmV0Lm5hbWUiOiJhZG1pbi11c2VyLXRva2VuLXY1N253Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9zZXJ2aWNlLWFjY291bnQubmFtZSI6ImFkbWluLXVzZXIiLCJrdWJlcm5ldGVzLmlvL3NlcnZpY2VhY2NvdW50L3NlcnZpY2UtYWNjb3VudC51aWQiOiIwMzAzMjQzYy00MDQwLTRhNTgtOGE0Ny04NDllZTliYTc5YzEiLCJzdWIiOiJzeXN0ZW06c2VydmljZWFjY291bnQ6a3ViZXJuZXRlcy1kYXNoYm9hcmQ6YWRtaW4tdXNlciJ9.Z2JrQlitASVwWbc-s6deLRFVk5DWD3P_vjUFXsqVSY10pbjFLG4njoZwh8p3tLxnX_VBsr7_6bwxhWSYChp9hwxznemD5x5HLtjb16kI9Z7yFWLtohzkTwuFbqmQaMoget_nYcQBUC5fDmBHRfFvNKePh_vSSb2h_aYXa8GV5AcfPQpY7r461itme1EXHQJqv-SN-zUnguDguCTjD80pFZ_CmnSE1z9QdMHPB8hoB4V68gtswR1VLa6mSYdgPwCHauuOobojALSaMc3RH7MmFUumAgguhqAkX3Omqd3rJbYOMRuMjhANqd08piDC3aIabINX6gP5-Tuuw2svnV6NYQ
```

Check [Kubernetes docs](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#manually-create-an-api-token-for-a-serviceaccount) for more information about API tokens for a ServiceAccount.
Check [Kubernetes docs](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#service-account-token-volume-projection) for more information about API tokens for a ServiceAccount.

## Getting a long-lived Bearer Token for ServiceAccount
## Getting a Long-lived Bearer Token for ServiceAccount

We can also create a token with the secret which bound the service account and the token will be saved in the Secret:
The token generated by the previous `kubectl create token` command has a limited lifetime (typically 1 hour by default). If you need a token that doesn't expire automatically, you can create a long-lived token by binding it to a Secret.

**When to use long-lived tokens:**
- For automation scripts that need persistent access
- For CI/CD pipelines that access the dashboard
- When you need a token that persists across cluster restarts
- For service integrations that require stable authentication

**Security considerations:**
- Long-lived tokens pose a greater security risk as they don't expire automatically
- Store these tokens securely and rotate them regularly
- Consider using short-lived tokens when possible

### Step 1: Create a Secret for the Service Account Token

First, create a Secret that will store the long-lived token for your service account:

```yaml
apiVersion: v1
Expand All @@ -63,40 +77,62 @@ metadata:
name: admin-user
namespace: kubernetes-dashboard
annotations:
kubernetes.io/service-account.name: "admin-user"
type: kubernetes.io/service-account-token
kubernetes.io/service-account.name: "admin-user"
type: kubernetes.io/service-account-token
```

Apply this manifest using:

```bash
kubectl apply -f <filename>.yaml
```

After Secret is created, we can execute the following command to get the token which is saved in the Secret:
### Step 2: Retrieve the Long-lived Token

```shell
After the Secret is created, Kubernetes will automatically populate it with a token. You can retrieve this token using the following command:

```bash
kubectl get secret admin-user -n kubernetes-dashboard -o jsonpath="{.data.token}" | base64 -d
```

Check [Kubernetes docs](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#manually-create-a-long-lived-api-token-for-a-serviceaccount) for more information about long-lived API tokens for a ServiceAccount.
This command will output the decoded token that you can use for authentication.

**Note:** The token retrieved this way will remain valid until:
- The Secret is deleted
- The associated ServiceAccount is deleted
- The token is manually revoked

Check [Kubernetes docs](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#manually-create-a-service-account-api-token) for more information about long-lived API tokens for a ServiceAccount.

## Accessing Dashboard

Now copy the token and paste it into the `Enter token` field on the login screen.
Now copy the token and paste it into the Enter token field on the login screen.

![Sing in](../../images/signin.png)
![Sing in](../../../images/signin.png)

Click the `Sign in` button and that's it. You are now logged in as an admin.
Click the Sign in button and that's it. You are now logged in as an admin.

**Note** Token login is ONLY allowed when the browser is accessing the UI over https. If your networking path to the UI is via http, the login will fail with an invalid token error.
**Important:** Token login is ONLY allowed when the browser is accessing the UI over HTTPS. If your networking path to the UI is via HTTP, the login will fail with an "invalid token" error.

![Overview](../../images/overview.png)
![Overview](../../../images/overview.png)

## Clean up and next steps

Remove the admin `ServiceAccount` and `ClusterRoleBinding`.
Remove the admin ServiceAccount and ClusterRoleBinding.

```shell
```bash
kubectl -n kubernetes-dashboard delete serviceaccount admin-user
kubectl -n kubernetes-dashboard delete clusterrolebinding admin-user
```

If you created a Secret for long-lived token, also remove it:

```bash
kubectl -n kubernetes-dashboard delete secret admin-user
```

In order to find out more about how to grant/deny permissions in Kubernetes read the official [authentication](https://kubernetes.io/docs/reference/access-authn-authz/authentication/) & [authorization](https://kubernetes.io/docs/reference/access-authn-authz/authorization/) documentation.

----
_Copyright 2020 [The Kubernetes Dashboard Authors](https://github.com/kubernetes/dashboard/graphs/contributors)_
---

*Copyright 2020 [The Kubernetes Dashboard Authors](https://github.com/kubernetes/dashboard/graphs/contributors)*