mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-25 04:28:15 +00:00
Merge pull request #1147 from sunilarjun/update-api-sidebar
Move Previous API Docs to the RKA Section
This commit is contained in:
Sunil Singh
@@ -1,11 +1,13 @@
|
||||
---
|
||||
title: API Tokens
|
||||
title: Using API Tokens
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/reference-guides/about-the-api/api-tokens"/>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/api/api-tokens"/>
|
||||
</head>
|
||||
|
||||
Rancher v2.8.0 introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl`. This page covers information on API tokens used with the [Rancher CLI](../reference-guides/cli-with-rancher), [kubeconfig files](../how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md#about-the-kubeconfig-file), Terraform and the [v3 API browser](./v3-rancher-api-guide.md#enable-view-in-api).
|
||||
|
||||
By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password.
|
||||
|
||||
You can deactivate API tokens by deleting them or by deactivating the user account.
|
||||
@@ -43,13 +45,11 @@ This setting is used by all kubeconfig tokens except those created by the CLI to
|
||||
|
||||
## Disable Tokens in Generated Kubeconfigs
|
||||
|
||||
Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. When this setting is deactivated, a generated kubeconfig references the [Rancher CLI](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request.
|
||||
Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. When this setting is deactivated, a generated kubeconfig references the [Rancher CLI](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request.
|
||||
|
||||
## Token Hashing
|
||||
|
||||
Users can enable token hashing, where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first.
|
||||
|
||||
To enable token hashing, refer to [this section](../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md).
|
||||
You can [enable token hashing](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md), where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. You should first evaluate this setting in a test environment, and/or take backups before enabling.
|
||||
|
||||
This feature affects all tokens which include, but are not limited to, the following:
|
||||
|
||||
@@ -82,4 +82,4 @@ Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempt
|
||||
|
||||
### kubeconfig-generate-token
|
||||
|
||||
When true, kubeconfigs requested through the UI contain a valid token. When false, kubeconfigs contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then retrieves and caches a token for the user](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl).
|
||||
When true, kubeconfigs requested through the UI contain a valid token. When false, kubeconfigs contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then retrieves and caches a token for the user](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl).
|
||||
@@ -1,12 +1,12 @@
|
||||
---
|
||||
title: API Quick Start Guide
|
||||
title: RK-API Quick Start Guide
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/api/quickstart"/>
|
||||
</head>
|
||||
|
||||
You can access Rancher's resources through the Kubernetes API. This guide will help you get started on using this API as a Rancher user.
|
||||
You can access Rancher's resources through the Kubernetes API. This guide helps you get started on using this API as a Rancher user.
|
||||
|
||||
1. In the upper left corner, click **☰ > Global Settings**.
|
||||
2. Find and copy the address in the `server-url` field.
|
||||
@@ -129,7 +129,7 @@ To ensure that your tools can recognize Rancher's CA certificates, most setups r
|
||||
If your Rancher instance is proxied by another service, you must extract the certificate that the service is using, and add it to the kubeconfig file, as demonstrated in step 5.
|
||||
:::
|
||||
|
||||
4. The following commands will convert `rancher.crt` to base64 output, trim all new-lines, and update the cluster in the kubeconfig with the certificate, then finishing by removing the `rancher.crt` file:
|
||||
4. The following commands convert `rancher.crt` to base64 output, trim all new-lines, and update the cluster in the kubeconfig with the certificate, then finish by removing the `rancher.crt` file:
|
||||
|
||||
```bash
|
||||
export KUBECONFIG=$PATH_TO_RANCHER_KUBECONFIG
|
||||
|
||||
@@ -0,0 +1,94 @@
|
||||
---
|
||||
title: Previous v3 Rancher API Guide
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/api/v3-rancher-api-guide"/>
|
||||
</head>
|
||||
|
||||
Rancher v2.8.0 introduced the Rancher Kubernetes API (RK-API). The previous v3 Rancher API is still available. This page describes the v3 API. For more information on RK-API, see the [RK-API quickstart](./quickstart.md) and [reference guide](./api-reference.mdx).
|
||||
|
||||
## How to Use the API
|
||||
|
||||
The previous v3 API has its own user interface accessible from a [web browser](./v3-rancher-api-guide.md#enable-view-in-api). This is an easy way to see resources, perform actions, and see the equivalent `curl` or HTTP request & response. To access it:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Rancher v2.6.4+">
|
||||
|
||||
1. Click your user avatar in the upper right corner.
|
||||
1. Click **Account & API Keys**.
|
||||
1. Under the **API Keys** section, find the **API Endpoint** field and click the link. The link looks something like `https://<RANCHER_FQDN>/v3`, where `<RANCHER_FQDN>` is the fully qualified domain name of your Rancher deployment.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Rancher before v2.6.4">
|
||||
|
||||
Go to the URL endpoint at `https://<RANCHER_FQDN>/v3`, where `<RANCHER_FQDN>` is the fully qualified domain name of your Rancher deployment.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Authentication
|
||||
|
||||
API requests must include authentication information. Authentication is done with HTTP basic authentication using [API keys](../reference-guides/user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take.
|
||||
|
||||
By default, certain cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md).
|
||||
|
||||
## Making Requests
|
||||
|
||||
The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, [see further documentation](https://github.com/rancher/api-spec/blob/master/specification.md).
|
||||
|
||||
- Every type has a Schema which describes:
|
||||
- The URL to get to the collection of this type of resource.
|
||||
- Every field the resource can have, along with their type, basic validation rules, whether they are required or optional, etc.
|
||||
- Every action that is possible on this type of resource, with their inputs and outputs (also as schemas).
|
||||
- Every field that allows filtering.
|
||||
- What HTTP verb methods are available for the collection itself, or for individual resources in the collection.
|
||||
|
||||
The design allows you to load just the list of schemas and access everything about the API. The UI for the API contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and follow other `links` inside of the returned resources to get any other information.
|
||||
|
||||
In practice, you may just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/<type>`) or get a specific resource (`/v3/<type>/<id>`). Anything deeper than that is subject to change in future releases.
|
||||
|
||||
Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL where you can retrieve that information. Again, you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself.
|
||||
|
||||
Most resources have actions, which do something or change the state of the resource. To use them, send a HTTP `POST` to the URL in the `actions` map of the action you want. Certain actions require input or produce output. See the individual documentation for each type or the schemas for specific information.
|
||||
|
||||
To edit a resource, send a HTTP `PUT` to the `links.update` link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored.
|
||||
|
||||
To delete a resource, send a HTTP `DELETE` to the `links.remove` link on the resource. If the link is missing then you don't have permission to update the resource.
|
||||
|
||||
To create a new resource, HTTP `POST` to the collection URL in the schema (which is `/v3/<type>`).
|
||||
|
||||
## Filtering
|
||||
|
||||
Most collections can be filtered on the server-side by common fields using HTTP query parameters. The `filters` map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just `field=value`. Modifiers can be added to the field name, for example, `field_gt=42` for "field is greater than 42." See the [API spec](https://github.com/rancher/api-spec/blob/master/specification.md#filtering) for full details.
|
||||
|
||||
## Sorting
|
||||
|
||||
Most collections can be sorted on the server-side by common fields using HTTP query parameters. The `sortLinks` map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified.
|
||||
|
||||
## Pagination
|
||||
|
||||
API responses are paginated with a limit of 100 resources per page by default. This can be changed with the `limit` query parameter, up to a maximum of 1000, for example, `/v3/pods?limit=1000`. The `pagination` map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not.
|
||||
|
||||
## Capturing v3 API Calls
|
||||
|
||||
You can use browser developer tools to capture how the v3 API is called. For example, you could follow these steps to use the Chrome developer tools to get the API call for provisioning an RKE cluster:
|
||||
|
||||
1. In the Rancher UI, go to **Cluster Management** and click **Create.**
|
||||
1. Click one of the cluster types. This example uses Digital Ocean.
|
||||
1. Fill out the form with a cluster name and node template, but don't click **Create**.
|
||||
1. You need to open the developer tools before the cluster creation to see the API call being recorded. To open the tools, right-click the Rancher UI and click **Inspect.**
|
||||
1. In the developer tools, click the **Network** tab.
|
||||
1. On the **Network** tab, make sure **Fetch/XHR** is selected.
|
||||
1. In the Rancher UI, click **Create**. In the developer tools, you should see a new network request with the name `cluster?_replace=true`.
|
||||
1. Right-click `cluster?_replace=true` and click **Copy > Copy as cURL.**
|
||||
1. Paste the result into any text editor. You can see the POST request, including the URL it was sent to, all headers, and the full body of the request. This command can be used to create a cluster from the command line. Note: the request should be stored in a safe place because it contains credentials.
|
||||
|
||||
### Enable View in API
|
||||
|
||||
You can also view captured v3 API calls for your respective clusters and resources. This feature is not enabled by default. To enable it:
|
||||
|
||||
1. Click your **User Tile** in the top right corner of the UI and select **Preferences** from the drop-down menu.
|
||||
2. Under the **Advanced Features** section, click **Enable "View in API"**
|
||||
|
||||
Once checked, the **View in API** link is displayed under the **⋮** sub-menu on resource pages in the UI.
|
||||
+1
-1
@@ -26,7 +26,7 @@ The following is a list of feature flags available in Rancher. If you've upgrade
|
||||
- `multi-cluster-management`: Allows multi-cluster provisioning and management of Kubernetes clusters. This flag can only be set at install time. It can't be enabled or disabled later.
|
||||
- `rke1-custom-node-cleanup`: Enables cleanup of deleted RKE1 custom nodes. We recommend that you keep this flag enabled, to prevent removed nodes from attempting to rejoin the cluster.
|
||||
- `rke2`: Enables provisioning RKE2 clusters. This flag is enabled by default.
|
||||
- `token-hashing`: Enables token hashing. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../reference-guides/about-the-api/api-tokens.md#token-hashing) for more information.
|
||||
- `token-hashing`: Enables token hashing. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/api-tokens.md#token-hashing) for more information.
|
||||
- `unsupported-storage-drivers`: Enables types for storage providers and provisioners that aren't enabled by default. See [Allow Unsupported Storage Drivers](../../../how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md) for more information.
|
||||
|
||||
The following table shows the availability and default values for some feature flags in Rancher. Features marked "GA" are generally available:
|
||||
|
||||
+4
-4
@@ -19,11 +19,11 @@ The kubeconfig file and its contents are specific to each cluster. It can be dow
|
||||
1. Find the cluster whose kubeconfig you want to download, and select **⁝** at the end of the row.
|
||||
1. Select **Download KubeConfig** from the submenu.
|
||||
|
||||
You will need a separate kubeconfig file for each cluster that you have access to in Rancher.
|
||||
You need a separate kubeconfig file for each cluster that you have access to in Rancher.
|
||||
|
||||
After you download the kubeconfig file, you will be able to use the kubeconfig file and its Kubernetes [contexts](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration) to access your downstream cluster.
|
||||
After you download the kubeconfig file, you are able to use the kubeconfig file and its Kubernetes [contexts](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration) to access your downstream cluster.
|
||||
|
||||
If admins have [kubeconfig token generation turned off](../../../../reference-guides/about-the-api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires [rancher cli](./authorized-cluster-endpoint.md) to be present in your PATH.
|
||||
If admins have [kubeconfig token generation turned off](../../../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires that the [Rancher CLI](./authorized-cluster-endpoint.md) to be present in your PATH.
|
||||
|
||||
### Two Authentication Methods for RKE Clusters
|
||||
|
||||
@@ -36,7 +36,7 @@ For RKE clusters, the kubeconfig file allows you to be authenticated in two ways
|
||||
|
||||
This second method, the capability to connect directly to the cluster's Kubernetes API server, is important because it lets you access your downstream cluster if you can't connect to Rancher.
|
||||
|
||||
To use the authorized cluster endpoint, you will need to configure kubectl to use the extra kubectl context in the kubeconfig file that Rancher generates for you when the RKE cluster is created. This file can be downloaded from the cluster view in the Rancher UI, and the instructions for configuring kubectl are on [this page.](use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster)
|
||||
To use the authorized cluster endpoint, you need to configure kubectl to use the extra kubectl context in the kubeconfig file that Rancher generates for you when the RKE cluster is created. This file can be downloaded from the cluster view in the Rancher UI, and the instructions for configuring kubectl are on [this page.](use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster)
|
||||
|
||||
These methods of communicating with downstream Kubernetes clusters are also explained in the [architecture page](../../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md) in the larger context of explaining how Rancher works and how Rancher communicates with downstream clusters.
|
||||
|
||||
|
||||
@@ -76,7 +76,7 @@ To manage individual nodes, browse to the cluster that you want to manage and th
|
||||
|
||||
## Viewing a Node in the Rancher API
|
||||
|
||||
Select this option to view the node's [API endpoints](../../../reference-guides/about-the-api/about-the-api.md).
|
||||
Select this option to view the node's [API endpoints](../../../api/quickstart.md).
|
||||
|
||||
## Deleting a Node
|
||||
|
||||
@@ -100,7 +100,7 @@ For [nodes hosted by an infrastructure provider](../launch-kubernetes-with-ranch
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to SSH into a node and click the name of the cluster.
|
||||
1. On the **Machine Pools** tab, find the node that you want to remote into and click **⋮ > Download SSH Key**. A ZIP file containing files used for SSH will be downloaded.
|
||||
1. On the **Machine Pools** tab, find the node that you want to remote into and click **⋮ > Download SSH Key**. A ZIP file containing files used for SSH is then downloaded.
|
||||
1. Extract the ZIP file to any location.
|
||||
1. Open Terminal. Change your location to the extracted ZIP file.
|
||||
1. Enter the following command:
|
||||
@@ -111,13 +111,13 @@ For [nodes hosted by an infrastructure provider](../launch-kubernetes-with-ranch
|
||||
|
||||
## Cordoning a Node
|
||||
|
||||
_Cordoning_ a node marks it as unschedulable. This feature is useful for performing short tasks on the node during small maintenance windows, like reboots, upgrades, or decommissions. When you're done, power back on and make the node schedulable again by uncordoning it.
|
||||
_Cordoning_ a node marks it as unschedulable. This feature is useful for performing short tasks on the node during small maintenance windows, like reboots, upgrades or decommissions. When you're done, power back on and make the node schedulable again by uncordoning it.
|
||||
|
||||
## Draining a Node
|
||||
|
||||
_Draining_ is the process of first cordoning the node, and then evicting all its pods. This feature is useful for performing node maintenance (like kernel upgrades or hardware maintenance). It prevents new pods from deploying to the node while redistributing existing pods so that users don't experience service interruption.
|
||||
|
||||
- For pods with a replica set, the pod is replaced by a new pod that will be scheduled to a new node. Additionally, if the pod is part of a service, then clients will automatically be redirected to the new pod.
|
||||
- For pods with a replica set, the pod is replaced by a new pod that is scheduled to a new node. Additionally, if the pod is part of a service, then clients are automatically redirected to the new pod.
|
||||
|
||||
- For pods with no replica set, you need to bring up a new copy of the pod, and assuming it is not part of a service, redirect clients to it.
|
||||
|
||||
@@ -127,20 +127,21 @@ However, you can override the conditions draining when you initiate the drain. Y
|
||||
|
||||
### Aggressive and Safe Draining Options
|
||||
|
||||
When you configure the upgrade strategy for the cluster, you will be able to enable node draining. If node draining is enabled, you will be able to configure how pods are deleted and rescheduled.
|
||||
When you configure the upgrade strategy for the cluster, you can enable node draining. If node draining is enabled, you are able to configure how pods are deleted and rescheduled.
|
||||
|
||||
- **Aggressive Mode**
|
||||
|
||||
In this mode, pods won't get rescheduled to a new node, even if they do not have a controller. Kubernetes expects you to have your own logic that handles the deletion of these pods.
|
||||
|
||||
Kubernetes also expects the implementation to decide what to do with pods using emptyDir. If a pod uses emptyDir to store local data, you might not be able to safely delete it, since the data in the emptyDir will be deleted once the pod is removed from the node. Choosing aggressive mode will delete these pods.
|
||||
Kubernetes also expects the implementation to decide what to do with pods using emptyDir. If a pod uses emptyDir to store local data, you might not be able to safely delete it, since the data in the emptyDir is deleted once the pod is removed from the node. Choosing aggressive mode deletes these pods.
|
||||
|
||||
- **Safe Mode**
|
||||
|
||||
If a node has standalone pods or ephemeral data it will be cordoned but not drained.
|
||||
If a node has stand-alone pods or ephemeral data it is cordoned but not drained.
|
||||
|
||||
### Grace Period
|
||||
|
||||
The timeout given to each pod for cleaning things up, so they will have chance to exit gracefully. For example, when pods might need to finish any outstanding requests, roll back transactions or save state to some external storage. If negative, the default value specified in the pod will be used.
|
||||
The timeout given to each pod for cleaning things up so they have a chance to exit gracefully. For example, when pods might need to finish any outstanding requests, roll back transactions or save state to an external storage. If negative, the default value specified in the pod is used.
|
||||
|
||||
### Timeout
|
||||
|
||||
@@ -156,17 +157,17 @@ The [timeout setting](https://github.com/kubernetes/kubernetes/pull/64378) was n
|
||||
|
||||
If there's any error related to user input, the node enters a `cordoned` state because the drain failed. You can either correct the input and attempt to drain the node again, or you can abort by uncordoning the node.
|
||||
|
||||
If the drain continues without error, the node enters a `draining` state. You'll have the option to stop the drain when the node is in this state, which will stop the drain process and change the node's state to `cordoned`.
|
||||
If the drain continues without error, the node enters a `draining` state. You'll have the option to stop the drain when the node is in this state, which then stops the drain process and changes the node's state to `cordoned`.
|
||||
|
||||
Once drain successfully completes, the node will be in a state of `drained`. You can then power off or delete the node.
|
||||
Once drain successfully completes, the node is in a state of `drained`. You can then power off or delete the node.
|
||||
|
||||
**Want to know more about cordon and drain?** See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/safely-drain-node/).
|
||||
|
||||
## Labeling a Node to be Ignored by Rancher
|
||||
|
||||
Some solutions, such as F5's BIG-IP integration, may require creating a node that is never registered to a cluster.
|
||||
Certain solutions, such as F5's BIG-IP integration, may require creating a node that is never registered to a cluster.
|
||||
|
||||
Since the node will never finish registering, it will always be shown as unhealthy in the Rancher UI.
|
||||
Since the node never finishes registering, it is always shown as unhealthy in the Rancher UI.
|
||||
|
||||
In that case, you may want to label the node to be ignored by Rancher so that Rancher only shows nodes as unhealthy when they are actually failing.
|
||||
|
||||
@@ -181,16 +182,16 @@ There is an [open issue](https://github.com/rancher/rancher/issues/24172) in whi
|
||||
|
||||
### Labeling Nodes to be Ignored with kubectl
|
||||
|
||||
To add a node that will be ignored by Rancher, use `kubectl` to create a node that has the following label:
|
||||
To add a node that is ignored by Rancher, use `kubectl` to create a node that has the following label:
|
||||
|
||||
```
|
||||
cattle.rancher.io/node-status: ignore
|
||||
```
|
||||
|
||||
**Result:** If you add the node to a cluster, Rancher will not attempt to sync with this node. The node can still be part of the cluster and can be listed with `kubectl`.
|
||||
**Result**: If you add the node to a cluster, Rancher skips syncing with this node. The node can still be part of the cluster and can be listed with `kubectl`.
|
||||
|
||||
If the label is added before the node is added to the cluster, the node will not be shown in the Rancher UI.
|
||||
If the label is added before the node is added to the cluster, the node is not shown in the Rancher UI.
|
||||
|
||||
If the label is added after the node is added to a Rancher cluster, the node will not be removed from the UI.
|
||||
If the label is added after the node is added to a Rancher cluster, the node is not removed from the UI.
|
||||
|
||||
If you delete the node from the Rancher server using the Rancher UI or API, the node will not be removed from the cluster if the `nodeName` is listed in the Rancher settings in the Rancher API under `v3/settings/ignore-node-name`.
|
||||
If you delete the node from the Rancher server using the Rancher UI or API, the node is not removed from the cluster if the `nodeName` is listed in the Rancher settings in the Rancher API under `v3/settings/ignore-node-name`.
|
||||
|
||||
@@ -1,93 +0,0 @@
|
||||
---
|
||||
title: API
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/reference-guides/about-the-api"/>
|
||||
</head>
|
||||
|
||||
## How to use the API
|
||||
|
||||
The API has its own user interface accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Rancher v2.6.4+">
|
||||
|
||||
1. Click on your user avatar in the upper right corner.
|
||||
1. Click **Account & API Keys**.
|
||||
1. Under the **API Keys** section, find the **API Endpoint** field and click the link. The link will look something like `https://<RANCHER_FQDN>/v3`, where `<RANCHER_FQDN>` is the fully qualified domain name of your Rancher deployment.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Rancher before v2.6.4">
|
||||
|
||||
Go to the URL endpoint at `https://<RANCHER_FQDN>/v3`, where `<RANCHER_FQDN>` is the fully qualified domain name of your Rancher deployment.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Authentication
|
||||
|
||||
API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys](../user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take.
|
||||
|
||||
By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md).
|
||||
|
||||
## Making requests
|
||||
|
||||
The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, [see here](https://github.com/rancher/api-spec/blob/master/specification.md).
|
||||
|
||||
- Every type has a Schema which describes:
|
||||
- The URL to get to the collection of this type of resources
|
||||
- Every field the resource can have, along with their type, basic validation rules, whether they are required or optional, etc.
|
||||
- Every action that is possible on this type of resource, with their inputs and outputs (also as schemas).
|
||||
- Every field that filtering is allowed on
|
||||
- What HTTP verb methods are available for the collection itself, or for individual resources in the collection.
|
||||
|
||||
|
||||
- So the theory is that you can load just the list of schemas and know everything about the API. This is in fact how the UI for the API works, it contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and other `links` inside of the returned resources to get any other information.
|
||||
|
||||
- In practice, you will probably just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/<type>`) or get a specific resource (`/v3/<type>/<id>`). Anything deeper than that is subject to change in future releases.
|
||||
|
||||
- Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL to retrieve that information. Again you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself.
|
||||
|
||||
- Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP `POST` to the URL in the `actions` map for the action you want. Some actions require input or produce output, see the individual documentation for each type or the schemas for specific information.
|
||||
|
||||
- To edit a resource, send a HTTP `PUT` to the `links.update` link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored.
|
||||
|
||||
- To delete a resource, send a HTTP `DELETE` to the `links.remove` link on the resource. If the link is missing then you don't have permission to update the resource.
|
||||
|
||||
- To create a new resource, HTTP `POST` to the collection URL in the schema (which is `/v3/<type>`).
|
||||
|
||||
## Filtering
|
||||
|
||||
Most collections can be filtered on the server-side by common fields using HTTP query parameters. The `filters` map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just `field=value`. Modifiers can be added to the field name, e.g. `field_gt=42` for "field is greater than 42". See the [API spec](https://github.com/rancher/api-spec/blob/master/specification.md#filtering) for full details.
|
||||
|
||||
## Sorting
|
||||
|
||||
Most collections can be sorted on the server-side by common fields using HTTP query parameters. The `sortLinks` map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified.
|
||||
|
||||
## Pagination
|
||||
|
||||
API responses are paginated with a limit of 100 resources per page by default. This can be changed with the `limit` query parameter, up to a maximum of 1000, e.g. `/v3/pods?limit=1000`. The `pagination` map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not.
|
||||
|
||||
## Capturing Rancher API Calls
|
||||
|
||||
You can use browser developer tools to capture how the Rancher API is called. For example, you could follow these steps to use the Chrome developer tools to get the API call for provisioning an RKE cluster:
|
||||
|
||||
1. In the Rancher UI, go to **Cluster Management** and click **Create.**
|
||||
1. Click one of the cluster types. This example uses Digital Ocean.
|
||||
1. Fill out the form with a cluster name and node template, but don't click **Create**.
|
||||
1. You will need to open the developer tools before the cluster creation to see the API call being recorded. To open the tools, right-click on the Rancher UI and click **Inspect.**
|
||||
1. In the developer tools, click the **Network** tab.
|
||||
1. On the **Network** tab, make sure **Fetch/XHR** is selected.
|
||||
1. In the Rancher UI, click **Create**. In the developer tools, you should see a new network request with the name `cluster?_replace=true`.
|
||||
1. Right-click `cluster?_replace=true` and click **Copy > Copy as cURL.**
|
||||
1. Paste the result into any text editor. You will be able to see the POST request, including the URL it was sent to, all of the headers, and the full body of the request. This command can be used to create a cluster from the command line. Note: The request should be stored in a safe place because it contains credentials.
|
||||
|
||||
### Enable View in API
|
||||
|
||||
You can also view captured Rancher API calls for your respective clusters and resources. This feature is not enabled by default. To enable it:
|
||||
|
||||
1. Click on your **User Tile** in the top right corner of the UI and select **Preferences** from the dropdown menu.
|
||||
2. Under the **Advanced Features** section, click **Enable "View in API"**
|
||||
|
||||
Once checked, the **View in API** link will now appear under the **⋮** sub-menu on resource pages in the UI.
|
||||
@@ -22,7 +22,7 @@ Run `kubectl cluster-info` or `kubectl get pods` successfully.
|
||||
|
||||
_Requirements_
|
||||
|
||||
If admins have [kubeconfig token generation turned off](../about-the-api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires the [Rancher CLI](./rancher-cli.md) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see an error like:
|
||||
If admins have [kubeconfig token generation turned off](../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires the [Rancher CLI](./rancher-cli.md) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see an error like:
|
||||
`Unable to connect to the server: getting credentials: exec: exec: "rancher": executable file not found in $PATH`.
|
||||
|
||||
This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported:
|
||||
@@ -33,4 +33,4 @@ This feature enables kubectl to authenticate with the Rancher server and get a n
|
||||
4. OpenLDAP
|
||||
5. SAML providers: Ping, Okta, ADFS, Keycloak, Shibboleth
|
||||
|
||||
When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../about-the-api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), or [gets deleted from the Rancher server](../about-the-api/api-tokens.md#deleting-tokens). Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again.
|
||||
When you first run kubectl, for example, `kubectl get pods`, you are prompted to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), or [gets deleted from the Rancher server](../../api/api-tokens.md#deleting-tokens). Upon expiration, you must log in with the Rancher server again to run the `kubectl get pods` command.
|
||||
|
||||
@@ -21,7 +21,7 @@ API Keys are composed of four components:
|
||||
|
||||
:::note
|
||||
|
||||
Users may opt to enable [token hashing](../about-the-api/api-tokens.md).
|
||||
Users may opt to enable [token hashing](../../api/api-tokens.md).
|
||||
|
||||
:::
|
||||
|
||||
@@ -35,9 +35,9 @@ Users may opt to enable [token hashing](../about-the-api/api-tokens.md).
|
||||
|
||||
The API key won't be valid after expiration. Shorter expiration periods are more secure.
|
||||
|
||||
Expiration period will be bound by `v3/settings/auth-token-max-ttl-minutes`. If it exceeds the max-ttl, API key will be created with max-ttl as the expiration period.
|
||||
Expiration period is bound by `v3/settings/auth-token-max-ttl-minutes`. If it exceeds the max-ttl, the API key is created with max-ttl as the expiration period.
|
||||
|
||||
A scope will limit the API key so that it will only work against the Kubernetes API of the specified cluster. If the cluster is configured with an Authorized Cluster Endpoint, you will be able to use a scoped token directly against the cluster's API without proxying through the Rancher server. See [Authorized Cluster Endpoints](../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-authorized-cluster-endpoint) for more information.
|
||||
A scope limits the API key so that it only works against the Kubernetes API of the specified cluster. If the cluster is configured with an Authorized Cluster Endpoint, you are able to use a scoped token directly against the cluster's API without proxying through the Rancher server. See [Authorized Cluster Endpoints](../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-authorized-cluster-endpoint) for more information.
|
||||
|
||||
4. Click **Create**.
|
||||
|
||||
@@ -49,7 +49,7 @@ Users may opt to enable [token hashing](../about-the-api/api-tokens.md).
|
||||
|
||||
## What's Next?
|
||||
|
||||
- Enter your API key information into the application that will send requests to the Rancher API.
|
||||
- Enter your API key information into the application that sends requests to the Rancher API.
|
||||
- Learn more about the Rancher endpoints and parameters by selecting **View in API** for an object in the Rancher UI.
|
||||
- API keys are used for API calls and [Rancher CLI](../cli-with-rancher/cli-with-rancher.md).
|
||||
|
||||
|
||||
+18
-8
@@ -1717,10 +1717,6 @@ module.exports = {
|
||||
to: '/v2.8/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates',
|
||||
from: '/v2.8/pages-for-subheaders/about-rke1-templates'
|
||||
},
|
||||
{
|
||||
to: '/v2.8/reference-guides/about-the-api',
|
||||
from: '/v2.8/pages-for-subheaders/about-the-api'
|
||||
},
|
||||
{
|
||||
to: '/v2.8/how-to-guides/new-user-guides/manage-clusters/access-clusters',
|
||||
from: '/v2.8/pages-for-subheaders/access-clusters'
|
||||
@@ -2061,10 +2057,6 @@ module.exports = {
|
||||
to: '/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates',
|
||||
from: '/pages-for-subheaders/about-rke1-templates'
|
||||
},
|
||||
{
|
||||
to: '/reference-guides/about-the-api',
|
||||
from: '/pages-for-subheaders/about-the-api'
|
||||
},
|
||||
{
|
||||
to: '/how-to-guides/new-user-guides/manage-clusters/access-clusters',
|
||||
from: '/pages-for-subheaders/access-clusters'
|
||||
@@ -3452,7 +3444,25 @@ module.exports = {
|
||||
{
|
||||
to: '/v2.7/reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale',
|
||||
from: '/v2.7/reference-guides/best-practices/rancher-server/tips-for-scaling-rancher'
|
||||
},
|
||||
// Redirects for restructure from PR #1147 (start)
|
||||
{
|
||||
to: '/v2.8/api/v3-rancher-api-guide',
|
||||
from: ['/v2.8/reference-guides/about-the-api', '/v2.8/pages-for-subheaders/about-the-api']
|
||||
},
|
||||
{
|
||||
to: '/v2.8/api/api-tokens',
|
||||
from: '/v2.8/reference-guides/about-the-api/api-tokens'
|
||||
},
|
||||
{
|
||||
to: '/api/v3-rancher-api-guide',
|
||||
from: ['/reference-guides/about-the-api', '/pages-for-subheaders/about-the-api']
|
||||
},
|
||||
{
|
||||
to: '/api/api-tokens',
|
||||
from: '/reference-guides/about-the-api/api-tokens'
|
||||
}
|
||||
// Redirects for restructure from PR #1147 (end)
|
||||
],
|
||||
},
|
||||
],
|
||||
|
||||
+3
-12
@@ -1022,17 +1022,6 @@ const sidebars = {
|
||||
"reference-guides/cli-with-rancher/kubectl-utility",
|
||||
]
|
||||
},
|
||||
{
|
||||
type: 'category',
|
||||
label: 'About the API',
|
||||
link: {
|
||||
type: 'doc',
|
||||
id: "reference-guides/about-the-api/about-the-api",
|
||||
},
|
||||
items: [
|
||||
"reference-guides/about-the-api/api-tokens",
|
||||
]
|
||||
},
|
||||
"reference-guides/rancher-cluster-tools",
|
||||
|
||||
"reference-guides/rancher-project-tools",
|
||||
@@ -1362,7 +1351,9 @@ const sidebars = {
|
||||
"api/workflows/projects"
|
||||
]
|
||||
},
|
||||
"api/api-reference"
|
||||
"api/api-reference",
|
||||
"api/api-tokens",
|
||||
"api/v3-rancher-api-guide",
|
||||
]
|
||||
},
|
||||
"contribute-to-rancher",
|
||||
|
||||
+7
-7
@@ -1,11 +1,13 @@
|
||||
---
|
||||
title: API Tokens
|
||||
title: Using API Tokens
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/reference-guides/about-the-api/api-tokens"/>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/api/api-tokens"/>
|
||||
</head>
|
||||
|
||||
Rancher v2.8.0 introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl`. This page covers information on API tokens used with the [Rancher CLI](../reference-guides/cli-with-rancher), [kubeconfig files](../how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md#about-the-kubeconfig-file), Terraform and the [v3 API browser](./v3-rancher-api-guide.md#enable-view-in-api).
|
||||
|
||||
By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password.
|
||||
|
||||
You can deactivate API tokens by deleting them or by deactivating the user account.
|
||||
@@ -43,13 +45,11 @@ This setting is used by all kubeconfig tokens except those created by the CLI to
|
||||
|
||||
## Disable Tokens in Generated Kubeconfigs
|
||||
|
||||
Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. When this setting is deactivated, a generated kubeconfig references the [Rancher CLI](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request.
|
||||
Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. When this setting is deactivated, a generated kubeconfig references the [Rancher CLI](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request.
|
||||
|
||||
## Token Hashing
|
||||
|
||||
Users can enable token hashing, where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first.
|
||||
|
||||
To enable token hashing, refer to [this section](../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md).
|
||||
You can [enable token hashing](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md), where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. You should first evaluate this setting in a test environment, and/or take backups before enabling.
|
||||
|
||||
This feature affects all tokens which include, but are not limited to, the following:
|
||||
|
||||
@@ -82,4 +82,4 @@ Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempt
|
||||
|
||||
### kubeconfig-generate-token
|
||||
|
||||
When true, kubeconfigs requested through the UI contain a valid token. When false, kubeconfigs contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then retrieves and caches a token for the user](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl).
|
||||
When true, kubeconfigs requested through the UI contain a valid token. When false, kubeconfigs contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then retrieves and caches a token for the user](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl).
|
||||
@@ -1,12 +1,12 @@
|
||||
---
|
||||
title: API Quick Start Guide
|
||||
title: RK-API Quick Start Guide
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/api/quickstart"/>
|
||||
</head>
|
||||
|
||||
You can access Rancher's resources through the Kubernetes API. This guide will help you get started on using this API as a Rancher user.
|
||||
You can access Rancher's resources through the Kubernetes API. This guide helps you get started on using this API as a Rancher user.
|
||||
|
||||
1. In the upper left corner, click **☰ > Global Settings**.
|
||||
2. Find and copy the address in the `server-url` field.
|
||||
@@ -129,7 +129,7 @@ To ensure that your tools can recognize Rancher's CA certificates, most setups r
|
||||
If your Rancher instance is proxied by another service, you must extract the certificate that the service is using, and add it to the kubeconfig file, as demonstrated in step 5.
|
||||
:::
|
||||
|
||||
4. The following commands will convert `rancher.crt` to base64 output, trim all new-lines, and update the cluster in the kubeconfig with the certificate, then finishing by removing the `rancher.crt` file:
|
||||
4. The following commands convert `rancher.crt` to base64 output, trim all new-lines, and update the cluster in the kubeconfig with the certificate, then finish by removing the `rancher.crt` file:
|
||||
|
||||
```bash
|
||||
export KUBECONFIG=$PATH_TO_RANCHER_KUBECONFIG
|
||||
|
||||
@@ -0,0 +1,94 @@
|
||||
---
|
||||
title: Previous v3 Rancher API Guide
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/api/v3-rancher-api-guide"/>
|
||||
</head>
|
||||
|
||||
Rancher v2.8.0 introduced the Rancher Kubernetes API (RK-API). The previous v3 Rancher API is still available. This page describes the v3 API. For more information on RK-API, see the [RK-API quickstart](./quickstart.md) and [reference guide](./api-reference.mdx).
|
||||
|
||||
## How to Use the API
|
||||
|
||||
The previous v3 API has its own user interface accessible from a [web browser](./v3-rancher-api-guide.md#enable-view-in-api). This is an easy way to see resources, perform actions, and see the equivalent `curl` or HTTP request & response. To access it:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Rancher v2.6.4+">
|
||||
|
||||
1. Click your user avatar in the upper right corner.
|
||||
1. Click **Account & API Keys**.
|
||||
1. Under the **API Keys** section, find the **API Endpoint** field and click the link. The link looks something like `https://<RANCHER_FQDN>/v3`, where `<RANCHER_FQDN>` is the fully qualified domain name of your Rancher deployment.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Rancher before v2.6.4">
|
||||
|
||||
Go to the URL endpoint at `https://<RANCHER_FQDN>/v3`, where `<RANCHER_FQDN>` is the fully qualified domain name of your Rancher deployment.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Authentication
|
||||
|
||||
API requests must include authentication information. Authentication is done with HTTP basic authentication using [API keys](../reference-guides/user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take.
|
||||
|
||||
By default, certain cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md).
|
||||
|
||||
## Making Requests
|
||||
|
||||
The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, [see further documentation](https://github.com/rancher/api-spec/blob/master/specification.md).
|
||||
|
||||
- Every type has a Schema which describes:
|
||||
- The URL to get to the collection of this type of resource.
|
||||
- Every field the resource can have, along with their type, basic validation rules, whether they are required or optional, etc.
|
||||
- Every action that is possible on this type of resource, with their inputs and outputs (also as schemas).
|
||||
- Every field that allows filtering.
|
||||
- What HTTP verb methods are available for the collection itself, or for individual resources in the collection.
|
||||
|
||||
The design allows you to load just the list of schemas and access everything about the API. The UI for the API contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and follow other `links` inside of the returned resources to get any other information.
|
||||
|
||||
In practice, you may just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/<type>`) or get a specific resource (`/v3/<type>/<id>`). Anything deeper than that is subject to change in future releases.
|
||||
|
||||
Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL where you can retrieve that information. Again, you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself.
|
||||
|
||||
Most resources have actions, which do something or change the state of the resource. To use them, send a HTTP `POST` to the URL in the `actions` map of the action you want. Certain actions require input or produce output. See the individual documentation for each type or the schemas for specific information.
|
||||
|
||||
To edit a resource, send a HTTP `PUT` to the `links.update` link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored.
|
||||
|
||||
To delete a resource, send a HTTP `DELETE` to the `links.remove` link on the resource. If the link is missing then you don't have permission to update the resource.
|
||||
|
||||
To create a new resource, HTTP `POST` to the collection URL in the schema (which is `/v3/<type>`).
|
||||
|
||||
## Filtering
|
||||
|
||||
Most collections can be filtered on the server-side by common fields using HTTP query parameters. The `filters` map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just `field=value`. Modifiers can be added to the field name, for example, `field_gt=42` for "field is greater than 42." See the [API spec](https://github.com/rancher/api-spec/blob/master/specification.md#filtering) for full details.
|
||||
|
||||
## Sorting
|
||||
|
||||
Most collections can be sorted on the server-side by common fields using HTTP query parameters. The `sortLinks` map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified.
|
||||
|
||||
## Pagination
|
||||
|
||||
API responses are paginated with a limit of 100 resources per page by default. This can be changed with the `limit` query parameter, up to a maximum of 1000, for example, `/v3/pods?limit=1000`. The `pagination` map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not.
|
||||
|
||||
## Capturing v3 API Calls
|
||||
|
||||
You can use browser developer tools to capture how the v3 API is called. For example, you could follow these steps to use the Chrome developer tools to get the API call for provisioning an RKE cluster:
|
||||
|
||||
1. In the Rancher UI, go to **Cluster Management** and click **Create.**
|
||||
1. Click one of the cluster types. This example uses Digital Ocean.
|
||||
1. Fill out the form with a cluster name and node template, but don't click **Create**.
|
||||
1. You need to open the developer tools before the cluster creation to see the API call being recorded. To open the tools, right-click the Rancher UI and click **Inspect.**
|
||||
1. In the developer tools, click the **Network** tab.
|
||||
1. On the **Network** tab, make sure **Fetch/XHR** is selected.
|
||||
1. In the Rancher UI, click **Create**. In the developer tools, you should see a new network request with the name `cluster?_replace=true`.
|
||||
1. Right-click `cluster?_replace=true` and click **Copy > Copy as cURL.**
|
||||
1. Paste the result into any text editor. You can see the POST request, including the URL it was sent to, all headers, and the full body of the request. This command can be used to create a cluster from the command line. Note: the request should be stored in a safe place because it contains credentials.
|
||||
|
||||
### Enable View in API
|
||||
|
||||
You can also view captured v3 API calls for your respective clusters and resources. This feature is not enabled by default. To enable it:
|
||||
|
||||
1. Click your **User Tile** in the top right corner of the UI and select **Preferences** from the drop-down menu.
|
||||
2. Under the **Advanced Features** section, click **Enable "View in API"**
|
||||
|
||||
Once checked, the **View in API** link is displayed under the **⋮** sub-menu on resource pages in the UI.
|
||||
+1
-1
@@ -26,7 +26,7 @@ The following is a list of feature flags available in Rancher. If you've upgrade
|
||||
- `multi-cluster-management`: Allows multi-cluster provisioning and management of Kubernetes clusters. This flag can only be set at install time. It can't be enabled or disabled later.
|
||||
- `rke1-custom-node-cleanup`: Enables cleanup of deleted RKE1 custom nodes. We recommend that you keep this flag enabled, to prevent removed nodes from attempting to rejoin the cluster.
|
||||
- `rke2`: Enables provisioning RKE2 clusters. This flag is enabled by default.
|
||||
- `token-hashing`: Enables token hashing. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../reference-guides/about-the-api/api-tokens.md#token-hashing) for more information.
|
||||
- `token-hashing`: Enables token hashing. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/api-tokens.md#token-hashing) for more information.
|
||||
- `unsupported-storage-drivers`: Enables types for storage providers and provisioners that aren't enabled by default. See [Allow Unsupported Storage Drivers](../../../how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md) for more information.
|
||||
|
||||
The following table shows the availability and default values for some feature flags in Rancher. Features marked "GA" are generally available:
|
||||
|
||||
+4
-4
@@ -19,11 +19,11 @@ The kubeconfig file and its contents are specific to each cluster. It can be dow
|
||||
1. Find the cluster whose kubeconfig you want to download, and select **⁝** at the end of the row.
|
||||
1. Select **Download KubeConfig** from the submenu.
|
||||
|
||||
You will need a separate kubeconfig file for each cluster that you have access to in Rancher.
|
||||
You need a separate kubeconfig file for each cluster that you have access to in Rancher.
|
||||
|
||||
After you download the kubeconfig file, you will be able to use the kubeconfig file and its Kubernetes [contexts](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration) to access your downstream cluster.
|
||||
After you download the kubeconfig file, you are then able to use the kubeconfig file and its Kubernetes [contexts](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration) to access your downstream cluster.
|
||||
|
||||
If admins have [kubeconfig token generation turned off](../../../../reference-guides/about-the-api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires [rancher cli](./authorized-cluster-endpoint.md) to be present in your PATH.
|
||||
If admins have [kubeconfig token generation turned off](../../../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires that the [Rancher CLI](./authorized-cluster-endpoint.md) to be present in your PATH.
|
||||
|
||||
### Two Authentication Methods for RKE Clusters
|
||||
|
||||
@@ -36,7 +36,7 @@ For RKE clusters, the kubeconfig file allows you to be authenticated in two ways
|
||||
|
||||
This second method, the capability to connect directly to the cluster's Kubernetes API server, is important because it lets you access your downstream cluster if you can't connect to Rancher.
|
||||
|
||||
To use the authorized cluster endpoint, you will need to configure kubectl to use the extra kubectl context in the kubeconfig file that Rancher generates for you when the RKE cluster is created. This file can be downloaded from the cluster view in the Rancher UI, and the instructions for configuring kubectl are on [this page.](use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster)
|
||||
To use the authorized cluster endpoint, you need to configure kubectl to use the extra kubectl context in the kubeconfig file that Rancher generates for you when the RKE cluster is created. This file can be downloaded from the cluster view in the Rancher UI, and the instructions for configuring kubectl are on [this page.](use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster)
|
||||
|
||||
These methods of communicating with downstream Kubernetes clusters are also explained in the [architecture page](../../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md) in the larger context of explaining how Rancher works and how Rancher communicates with downstream clusters.
|
||||
|
||||
|
||||
+18
-17
@@ -76,7 +76,7 @@ To manage individual nodes, browse to the cluster that you want to manage and th
|
||||
|
||||
## Viewing a Node in the Rancher API
|
||||
|
||||
Select this option to view the node's [API endpoints](../../../reference-guides/about-the-api/about-the-api.md).
|
||||
Select this option to view the node's [API endpoints](../../../api/quickstart.md).
|
||||
|
||||
## Deleting a Node
|
||||
|
||||
@@ -100,7 +100,7 @@ For [nodes hosted by an infrastructure provider](../launch-kubernetes-with-ranch
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to SSH into a node and click the name of the cluster.
|
||||
1. On the **Machine Pools** tab, find the node that you want to remote into and click **⋮ > Download SSH Key**. A ZIP file containing files used for SSH will be downloaded.
|
||||
1. On the **Machine Pools** tab, find the node that you want to remote into and click **⋮ > Download SSH Key**. A ZIP file containing files used for SSH is then downloaded.
|
||||
1. Extract the ZIP file to any location.
|
||||
1. Open Terminal. Change your location to the extracted ZIP file.
|
||||
1. Enter the following command:
|
||||
@@ -111,13 +111,13 @@ For [nodes hosted by an infrastructure provider](../launch-kubernetes-with-ranch
|
||||
|
||||
## Cordoning a Node
|
||||
|
||||
_Cordoning_ a node marks it as unschedulable. This feature is useful for performing short tasks on the node during small maintenance windows, like reboots, upgrades, or decommissions. When you're done, power back on and make the node schedulable again by uncordoning it.
|
||||
_Cordoning_ a node marks it as unschedulable. This feature is useful for performing short tasks on the node during small maintenance windows, like reboots, upgrades or decommissions. When you're done, power back on and make the node schedulable again by uncordoning it.
|
||||
|
||||
## Draining a Node
|
||||
|
||||
_Draining_ is the process of first cordoning the node, and then evicting all its pods. This feature is useful for performing node maintenance (like kernel upgrades or hardware maintenance). It prevents new pods from deploying to the node while redistributing existing pods so that users don't experience service interruption.
|
||||
|
||||
- For pods with a replica set, the pod is replaced by a new pod that will be scheduled to a new node. Additionally, if the pod is part of a service, then clients will automatically be redirected to the new pod.
|
||||
- For pods with a replica set, the pod is replaced by a new pod that is scheduled to a new node. Additionally, if the pod is part of a service, then clients are automatically redirected to the new pod.
|
||||
|
||||
- For pods with no replica set, you need to bring up a new copy of the pod, and assuming it is not part of a service, redirect clients to it.
|
||||
|
||||
@@ -127,20 +127,21 @@ However, you can override the conditions draining when you initiate the drain. Y
|
||||
|
||||
### Aggressive and Safe Draining Options
|
||||
|
||||
When you configure the upgrade strategy for the cluster, you will be able to enable node draining. If node draining is enabled, you will be able to configure how pods are deleted and rescheduled.
|
||||
When you configure the upgrade strategy for the cluster, you are able to enable node draining. If node draining is enabled, you are able to configure how pods are deleted and rescheduled.
|
||||
|
||||
- **Aggressive Mode**
|
||||
|
||||
In this mode, pods won't get rescheduled to a new node, even if they do not have a controller. Kubernetes expects you to have your own logic that handles the deletion of these pods.
|
||||
|
||||
Kubernetes also expects the implementation to decide what to do with pods using emptyDir. If a pod uses emptyDir to store local data, you might not be able to safely delete it, since the data in the emptyDir will be deleted once the pod is removed from the node. Choosing aggressive mode will delete these pods.
|
||||
Kubernetes also expects the implementation to decide what to do with pods using emptyDir. If a pod uses emptyDir to store local data, you might not be able to safely delete it, since the data in the emptyDir is deleted once the pod is removed from the node. Choosing aggressive mode deletes these pods.
|
||||
|
||||
- **Safe Mode**
|
||||
|
||||
If a node has standalone pods or ephemeral data it will be cordoned but not drained.
|
||||
If a node has stand-alone pods or ephemeral data it is cordoned but not drained.
|
||||
|
||||
### Grace Period
|
||||
|
||||
The timeout given to each pod for cleaning things up, so they will have chance to exit gracefully. For example, when pods might need to finish any outstanding requests, roll back transactions or save state to some external storage. If negative, the default value specified in the pod will be used.
|
||||
The timeout given to each pod for cleaning things up so they have the chance to exit gracefully. For example, when pods might need to finish any outstanding requests, roll back transactions or save state to an external storage. If negative, the default value specified in the pod is used.
|
||||
|
||||
### Timeout
|
||||
|
||||
@@ -156,17 +157,17 @@ The [timeout setting](https://github.com/kubernetes/kubernetes/pull/64378) was n
|
||||
|
||||
If there's any error related to user input, the node enters a `cordoned` state because the drain failed. You can either correct the input and attempt to drain the node again, or you can abort by uncordoning the node.
|
||||
|
||||
If the drain continues without error, the node enters a `draining` state. You'll have the option to stop the drain when the node is in this state, which will stop the drain process and change the node's state to `cordoned`.
|
||||
If the drain continues without error, the node enters a `draining` state. You'll have the option to stop the drain when the node is in this state, which stops the drain process and changes the node's state to `cordoned`.
|
||||
|
||||
Once drain successfully completes, the node will be in a state of `drained`. You can then power off or delete the node.
|
||||
Once drain successfully completes, the node is in a state of `drained`. You can then power off or delete the node.
|
||||
|
||||
**Want to know more about cordon and drain?** See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/safely-drain-node/).
|
||||
|
||||
## Labeling a Node to be Ignored by Rancher
|
||||
|
||||
Some solutions, such as F5's BIG-IP integration, may require creating a node that is never registered to a cluster.
|
||||
Certain solutions, such as F5's BIG-IP integration, may require creating a node that is never registered to a cluster.
|
||||
|
||||
Since the node will never finish registering, it will always be shown as unhealthy in the Rancher UI.
|
||||
Since the node never finishes registering, it is always shown as unhealthy in the Rancher UI.
|
||||
|
||||
In that case, you may want to label the node to be ignored by Rancher so that Rancher only shows nodes as unhealthy when they are actually failing.
|
||||
|
||||
@@ -181,16 +182,16 @@ There is an [open issue](https://github.com/rancher/rancher/issues/24172) in whi
|
||||
|
||||
### Labeling Nodes to be Ignored with kubectl
|
||||
|
||||
To add a node that will be ignored by Rancher, use `kubectl` to create a node that has the following label:
|
||||
To add a node that is ignored by Rancher, use `kubectl` to create a node that has the following label:
|
||||
|
||||
```
|
||||
cattle.rancher.io/node-status: ignore
|
||||
```
|
||||
|
||||
**Result:** If you add the node to a cluster, Rancher will not attempt to sync with this node. The node can still be part of the cluster and can be listed with `kubectl`.
|
||||
**Result**: If you add the node to a cluster, Rancher skips syncing with this node. The node can still be part of the cluster and can be listed with `kubectl`.
|
||||
|
||||
If the label is added before the node is added to the cluster, the node will not be shown in the Rancher UI.
|
||||
If the label is added before the node is added to the cluster, the node is not shown in the Rancher UI.
|
||||
|
||||
If the label is added after the node is added to a Rancher cluster, the node will not be removed from the UI.
|
||||
If the label is added after the node is added to a Rancher cluster, the node is not removed from the UI.
|
||||
|
||||
If you delete the node from the Rancher server using the Rancher UI or API, the node will not be removed from the cluster if the `nodeName` is listed in the Rancher settings in the Rancher API under `v3/settings/ignore-node-name`.
|
||||
If you delete the node from the Rancher server using the Rancher UI or API, the node is not removed from the cluster if the `nodeName` is listed in the Rancher settings in the Rancher API under `v3/settings/ignore-node-name`.
|
||||
|
||||
@@ -1,92 +0,0 @@
|
||||
---
|
||||
title: API
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/reference-guides/about-the-api"/>
|
||||
</head>
|
||||
|
||||
## How to use the API
|
||||
|
||||
The API has its own user interface accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Rancher v2.6.4+">
|
||||
|
||||
1. Click on your user avatar in the upper right corner.
|
||||
1. Click **Account & API Keys**.
|
||||
1. Under the **API Keys** section, find the **API Endpoint** field and click the link. The link will look something like `https://<RANCHER_FQDN>/v3`, where `<RANCHER_FQDN>` is the fully qualified domain name of your Rancher deployment.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Rancher before v2.6.4">
|
||||
|
||||
Go to the URL endpoint at `https://<RANCHER_FQDN>/v3`, where `<RANCHER_FQDN>` is the fully qualified domain name of your Rancher deployment.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Authentication
|
||||
|
||||
API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys](../user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take.
|
||||
|
||||
By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md).
|
||||
|
||||
## Making requests
|
||||
|
||||
The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, [see here](https://github.com/rancher/api-spec/blob/master/specification.md).
|
||||
|
||||
- Every type has a Schema which describes:
|
||||
- The URL to get to the collection of this type of resources
|
||||
- Every field the resource can have, along with their type, basic validation rules, whether they are required or optional, etc.
|
||||
- Every action that is possible on this type of resource, with their inputs and outputs (also as schemas).
|
||||
- Every field that filtering is allowed on
|
||||
- What HTTP verb methods are available for the collection itself, or for individual resources in the collection.
|
||||
|
||||
|
||||
- So the theory is that you can load just the list of schemas and know everything about the API. This is in fact how the UI for the API works, it contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and other `links` inside of the returned resources to get any other information.
|
||||
|
||||
- In practice, you will probably just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/<type>`) or get a specific resource (`/v3/<type>/<id>`). Anything deeper than that is subject to change in future releases.
|
||||
|
||||
- Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL to retrieve that information. Again you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself.
|
||||
|
||||
- Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP `POST` to the URL in the `actions` map for the action you want. Some actions require input or produce output, see the individual documentation for each type or the schemas for specific information.
|
||||
|
||||
- To edit a resource, send a HTTP `PUT` to the `links.update` link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored.
|
||||
|
||||
- To delete a resource, send a HTTP `DELETE` to the `links.remove` link on the resource. If the link is missing then you don't have permission to update the resource.
|
||||
|
||||
- To create a new resource, HTTP `POST` to the collection URL in the schema (which is `/v3/<type>`).
|
||||
|
||||
## Filtering
|
||||
|
||||
Most collections can be filtered on the server-side by common fields using HTTP query parameters. The `filters` map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just `field=value`. Modifiers can be added to the field name, e.g. `field_gt=42` for "field is greater than 42". See the [API spec](https://github.com/rancher/api-spec/blob/master/specification.md#filtering) for full details.
|
||||
|
||||
## Sorting
|
||||
|
||||
Most collections can be sorted on the server-side by common fields using HTTP query parameters. The `sortLinks` map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified.
|
||||
|
||||
## Pagination
|
||||
|
||||
API responses are paginated with a limit of 100 resources per page by default. This can be changed with the `limit` query parameter, up to a maximum of 1000, e.g. `/v3/pods?limit=1000`. The `pagination` map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not.
|
||||
|
||||
## Capturing Rancher API Calls
|
||||
|
||||
You can use browser developer tools to capture how the Rancher API is called. For example, you could follow these steps to use the Chrome developer tools to get the API call for provisioning an RKE cluster:
|
||||
|
||||
1. In the Rancher UI, go to **Cluster Management** and click **Create.**
|
||||
1. Click one of the cluster types. This example uses Digital Ocean.
|
||||
1. Fill out the form with a cluster name and node template, but don't click **Create**.
|
||||
1. You will need to open the developer tools before the cluster creation to see the API call being recorded. To open the tools, right-click on the Rancher UI and click **Inspect.**
|
||||
1. In the developer tools, click the **Network** tab.
|
||||
1. On the **Network** tab, make sure **Fetch/XHR** is selected.
|
||||
1. In the Rancher UI, click **Create**. In the developer tools, you should see a new network request with the name `cluster?_replace=true`.
|
||||
1. Right-click `cluster?_replace=true` and click **Copy > Copy as cURL.**
|
||||
1. Paste the result into any text editor. You will be able to see the POST request, including the URL it was sent to, all of the headers, and the full body of the request. This command can be used to create a cluster from the command line. Note: The request should be stored in a safe place because it contains credentials.
|
||||
|
||||
### Enable View in API
|
||||
You can also view captured Rancher API calls for your respective clusters and resources. This feature is not enabled by default. To enable it:
|
||||
|
||||
1. Click on your **User Tile** in the top right corner of the UI and select **Preferences** from the dropdown menu.
|
||||
2. Under the **Advanced Features** section, click **Enable "View in API"**
|
||||
|
||||
Once checked, the **View in API** link will now appear under the **⋮** sub-menu on resource pages in the UI.
|
||||
@@ -22,7 +22,7 @@ Run `kubectl cluster-info` or `kubectl get pods` successfully.
|
||||
|
||||
_Requirements_
|
||||
|
||||
If admins have [kubeconfig token generation turned off](../about-the-api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires the [Rancher CLI](./rancher-cli.md) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see an error like:
|
||||
If admins have [kubeconfig token generation turned off](../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires the [Rancher CLI](./rancher-cli.md) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see an error like:
|
||||
`Unable to connect to the server: getting credentials: exec: exec: "rancher": executable file not found in $PATH`.
|
||||
|
||||
This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported:
|
||||
@@ -33,4 +33,4 @@ This feature enables kubectl to authenticate with the Rancher server and get a n
|
||||
4. OpenLDAP
|
||||
5. SAML providers: Ping, Okta, ADFS, Keycloak, Shibboleth
|
||||
|
||||
When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../about-the-api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), or [gets deleted from the Rancher server](../about-the-api/api-tokens.md#deleting-tokens). Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again.
|
||||
When you first run kubectl, for example, `kubectl get pods`, you are prompted to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), or [gets deleted from the Rancher server](../../api/api-tokens.md#deleting-tokens). Upon expiration, you must log in with the Rancher server again to run the `kubectl get pods` command.
|
||||
|
||||
@@ -21,7 +21,7 @@ API Keys are composed of four components:
|
||||
|
||||
:::note
|
||||
|
||||
Users may opt to enable [token hashing](../about-the-api/api-tokens.md).
|
||||
Users may opt to enable [token hashing](../../api/api-tokens.md).
|
||||
|
||||
:::
|
||||
|
||||
@@ -35,9 +35,9 @@ Users may opt to enable [token hashing](../about-the-api/api-tokens.md).
|
||||
|
||||
The API key won't be valid after expiration. Shorter expiration periods are more secure.
|
||||
|
||||
Expiration period will be bound by `v3/settings/auth-token-max-ttl-minutes`. If it exceeds the max-ttl, API key will be created with max-ttl as the expiration period.
|
||||
Expiration period is bound by `v3/settings/auth-token-max-ttl-minutes`. If it exceeds the max-ttl, API key is created with max-ttl as the expiration period.
|
||||
|
||||
A scope will limit the API key so that it will only work against the Kubernetes API of the specified cluster. If the cluster is configured with an Authorized Cluster Endpoint, you will be able to use a scoped token directly against the cluster's API without proxying through the Rancher server. See [Authorized Cluster Endpoints](../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-authorized-cluster-endpoint) for more information.
|
||||
A scope limits the API key so that it only works against the Kubernetes API of the specified cluster. If the cluster is configured with an Authorized Cluster Endpoint, you are able to use a scoped token directly against the cluster's API without proxying through the Rancher server. See [Authorized Cluster Endpoints](../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-authorized-cluster-endpoint) for more information.
|
||||
|
||||
4. Click **Create**.
|
||||
|
||||
@@ -49,7 +49,7 @@ Users may opt to enable [token hashing](../about-the-api/api-tokens.md).
|
||||
|
||||
## What's Next?
|
||||
|
||||
- Enter your API key information into the application that will send requests to the Rancher API.
|
||||
- Enter your API key information into the application that sends requests to the Rancher API.
|
||||
- Learn more about the Rancher endpoints and parameters by selecting **View in API** for an object in the Rancher UI.
|
||||
- API keys are used for API calls and [Rancher CLI](../cli-with-rancher/cli-with-rancher.md).
|
||||
|
||||
|
||||
@@ -985,17 +985,6 @@
|
||||
"reference-guides/cli-with-rancher/kubectl-utility"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "category",
|
||||
"label": "About the API",
|
||||
"link": {
|
||||
"type": "doc",
|
||||
"id": "reference-guides/about-the-api/about-the-api"
|
||||
},
|
||||
"items": [
|
||||
"reference-guides/about-the-api/api-tokens"
|
||||
]
|
||||
},
|
||||
"reference-guides/rancher-cluster-tools",
|
||||
"reference-guides/rancher-project-tools",
|
||||
"reference-guides/system-tools",
|
||||
@@ -1322,7 +1311,9 @@
|
||||
"api/workflows/projects"
|
||||
]
|
||||
},
|
||||
"api/api-reference"
|
||||
"api/api-reference",
|
||||
"api/api-tokens",
|
||||
"api/v3-rancher-api-guide"
|
||||
]
|
||||
},
|
||||
"contribute-to-rancher"
|
||||
|
||||
Reference in New Issue
Block a user