docs: add serviceaccount-api-access and update faq #421
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,91 @@ | ||
| --- | ||
| title: "ServiceAccount Tokens for API Access" | ||
| linkTitle: "ServiceAccount API Access" | ||
| description: "How to retrieve and use ServiceAccount tokens in Cozystack." | ||
| weight: 20 | ||
| aliases: | ||
| - /docs/v0/operations/api-access | ||
| - /docs/operations/api-access | ||
| --- | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| Before you begin, make sure that: | ||
| - A tenant already exists in Cozystack. | ||
| See [Create a User Tenant]({{% ref "/docs/v0/getting-started/create-tenant" %}}) if you haven't created one yet. | ||
| - You have access to the tenant namespace — either via OIDC credentials or an administrative kubeconfig. | ||
| - `kubectl` is installed and configured. | ||
| - (Optional) `jq` is installed. | ||
|
|
||
|
|
||
| ## Retrieving the ServiceAccount Token | ||
|
|
||
| Each tenant in Cozystack has a Secret that contains a ServiceAccount token. | ||
| The Secret has the same name as the tenant and is located in the tenant's namespace. | ||
coderabbitai[bot] marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| {{< tabs name="get_token" >}} | ||
| {{% tab name="Dashboard" %}} | ||
|
|
||
| 1. Log in to the Dashboard as a user with access to the tenant. | ||
| 1. Switch context to the target tenant if needed. | ||
| 1. On the left sidebar, navigate to the **Administration** → **Info** page and open the **Secrets** tab. | ||
| 1. Find the secret named `tenant-<name>` (e.g. `tenant-team1`), where the **Key** is **token**. | ||
| 1. Click the eye icon to reveal the **Value** field, then click the revealed data. The text will be copied to the clipboard automatically. | ||
|
|
||
| {{% /tab %}} | ||
|
|
||
| {{% tab name="kubectl" %}} | ||
|
|
||
| Retrieve the token for a tenant named `<name>`: | ||
|
|
||
| ```bash | ||
| kubectl -n tenant-<name> get tenantsecret tenant-<name> -o json | jq -r '.data.token | @base64d' | ||
| ``` | ||
|
|
||
| To store the token in a variable for subsequent commands: | ||
|
|
||
| ```bash | ||
| export TOKEN=$(kubectl -n tenant-<name> get tenantsecret tenant-<name> -o json | jq -r '.data.token | @base64d') | ||
| ``` | ||
|
|
||
| {{% /tab %}} | ||
| {{< /tabs >}} | ||
|
|
||
| ## Using the Token for API Access | ||
|
|
||
| Once you have the token, you can [generate a kubeconfig]({{% ref "/docs/v0/operations/faq/generate-kubeconfig" %}}) for kubectl access, or use it directly with `curl` as shown below. | ||
|
|
||
| {{% alert color="warning" %}} | ||
| **Token Security** | ||
|
|
||
| ServiceAccount tokens in Cozystack **do not expire** by default. Handle them with the same care as passwords. | ||
| {{% /alert %}} | ||
|
|
||
| ### Test the Connection | ||
|
|
||
| First, verify your kubectl context points to the correct Cozystack cluster: | ||
|
|
||
| ```bash | ||
| kubectl config current-context | ||
| kubectl cluster-info | ||
| ``` | ||
|
|
||
| Next, get the API server address: | ||
|
|
||
| ```bash | ||
| export API_SERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}') | ||
|
Collaborator
There was a problem hiding this comment. In prerequisites we need either kubectl config or OIDC credentials. I think we should be able to get everything either from the dashboard or using kubectl. User might not have configured kubectl for this cluster |
||
| ``` | ||
|
|
||
| Then, extract the CA certificate from the tenant secret: | ||
|
|
||
| ```bash | ||
| kubectl -n tenant-<name> get secret tenant-<name> -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt | ||
| ``` | ||
|
|
||
| Now, test the connection: | ||
|
|
||
| ```bash | ||
| curl --cacert ca.crt -H "Authorization: Bearer ${TOKEN}" ${API_SERVER}/api | ||
| ``` | ||
|
|
||
| > You can remove `ca.crt` after testing. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.