mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-28 22:18:52 +00:00
Reorganize docs for Rancher v2.5
This commit is contained in:
Catherine Luse
@@ -1,52 +0,0 @@
|
||||
---
|
||||
title: API
|
||||
weight: 19
|
||||
---
|
||||
|
||||
## 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, click on your user avatar in the upper right corner. Under **API & Keys**, you can find the URL endpoint as well as create [API keys]({{<baseurl>}}/rancher/v2.x/en/user-settings/api-keys/).
|
||||
|
||||
## Authentication
|
||||
|
||||
API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys]({{<baseurl>}}/rancher/v2.x/en/user-settings/api-keys/). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/) 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]({{<baseurl>}}/rancher/v2.x/en/api/api-tokens).
|
||||
|
||||
## 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.
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
title: API Keys
|
||||
weight: 3
|
||||
---
|
||||
|
||||
If you want to access your Rancher clusters, projects, or other objects using external applications, you can do so using the Rancher API. However, before your application can access the API, you must provide the app with a key used to authenticate with Rancher. You can obtain a key using the Rancher UI.
|
||||
|
||||
An API key is also required for using Rancher CLI.
|
||||
|
||||
API Keys are composed of four components:
|
||||
|
||||
- **Endpoint:** This is the IP address and path that other applications use to send requests to the Rancher API.
|
||||
- **Access Key:** The token's username.
|
||||
- **Secret Key:** The token's password. For applications that prompt you for two different strings for API authentication, you usually enter the two keys together.
|
||||
- **Bearer Token:** The token username and password concatenated together. Use this string for applications that prompt you for one authentication string.
|
||||
|
||||
## Creating an API Key
|
||||
|
||||
1. Select **User Avatar** > **API & Keys** from the **User Settings** menu in the upper-right.
|
||||
|
||||
2. Click **Add Key**.
|
||||
|
||||
3. **Optional:** Enter a description for the API key and select an expiration period or a scope. We recommend setting an expiration date.
|
||||
|
||||
The API key won't be valid after expiration. Shorter expiration periods are more secure.
|
||||
|
||||
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]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/#4-authorized-cluster-endpoint) for more information.
|
||||
|
||||
4. Click **Create**.
|
||||
|
||||
**Step Result:** Your API Key is created. Your API **Endpoint**, **Access Key**, **Secret Key**, and **Bearer Token** are displayed.
|
||||
|
||||
Use the **Bearer Token** to authenticate with Rancher CLI.
|
||||
|
||||
5. Copy the information displayed to a secure location. This information is only displayed once, so if you lose your key, you'll have to make a new one.
|
||||
|
||||
## What's Next?
|
||||
|
||||
- Enter your API key information into the application that will send 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]({{<baseurl>}}/rancher/v2.x/en/cli).
|
||||
|
||||
## Deleting API Keys
|
||||
|
||||
If you need to revoke an API key, delete it. You should delete API keys:
|
||||
|
||||
- That may have been compromised.
|
||||
- That have expired.
|
||||
|
||||
To delete an API, select the stale key and click **Delete**.
|
||||
@@ -1,29 +0,0 @@
|
||||
---
|
||||
title: API Tokens
|
||||
weight: 1
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
To delete a token,
|
||||
|
||||
1. Go to the list of all tokens in the Rancher API view at `https://<Rancher-Server-IP>/v3/tokens`.
|
||||
|
||||
1. Access the token you want to delete by its ID. For example, `https://<Rancher-Server-IP>/v3/tokens/kubectl-shell-user-vqkqt`
|
||||
|
||||
1. Click **Delete.**
|
||||
|
||||
Here is the complete list of tokens that are generated with `ttl=0`:
|
||||
|
||||
| Token | Description |
|
||||
|-------|-------------|
|
||||
| `kubeconfig-*` | Kubeconfig token |
|
||||
| `kubectl-shell-*` | Access to `kubectl` shell in the browser |
|
||||
| `agent-*` | Token for agent deployment |
|
||||
| `compose-token-*` | Token for compose |
|
||||
| `helm-token-*` | Token for Helm chart deployment |
|
||||
| `*-pipeline*` | Pipeline token for project |
|
||||
| `telemetry-*` | Telemetry token |
|
||||
| `drain-node-*` | Token for drain (we use `kubectl` for drain because there is no native Kubernetes API) |
|
||||
Reference in New Issue
Block a user