mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-25 04:28:15 +00:00
Denise
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: API
|
||||
weight: 7500
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
## 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.
|
||||
@@ -10,19 +10,19 @@ aliases:
|
||||
|
||||
- [Operating System](#operating-system)
|
||||
|
||||
- [RedHat Enterprise Linux (RHEL) / Oracle Enterprise Linux (OEL) / CentOS](#redhat-enterprise-linux-rhel--oracle-enterprise-linux-oel--centos)
|
||||
|
||||
- [Red Hat Enterprise Linux (RHEL) / Oracle Enterprise Linux (OEL) / CentOS](#red-hat-enterprise-linux-rhel-oracle-enterprise-linux-oel-centos)
|
||||
|
||||
- [Using upstream Docker](#using-upstream-docker)
|
||||
- [Using RHEL/CentOS packaged Docker](#using-rhelcentos-packaged-docker)
|
||||
- [Using RHEL/CentOS packaged Docker](#using-rhel-centos-packaged-docker)
|
||||
- [Notes about Atomic Nodes](#red-hat-atomic)
|
||||
|
||||
- [OpenSSH version](#openssh-version)
|
||||
- [Creating a Docker Group](#creating-a-docker-group)
|
||||
- [Software](#software)
|
||||
- [Ports](#ports)
|
||||
- [Opening port TCP/6443 using `iptables``](#opening-port-tcp6443-using-iptables)
|
||||
- [Opening port TCP/6443 using `firewalld`](#opening-port-tcp6443-using-firewalld)
|
||||
- [Notes about Atomic Nodes](#notes-about-atomic-nodes)
|
||||
|
||||
- [Container Volumes](#container-volumes)
|
||||
- [OpenSSH version](#openssh-version)
|
||||
- [Creating a Docker Group](#creating-a-docker-group)
|
||||
- [Opening port TCP/6443 using `iptables`](#opening-port-tcp-6443-using-iptables)
|
||||
- [Opening port TCP/6443 using `firewalld`](#opening-port-tcp-6443-using-firewalld)
|
||||
|
||||
<!-- /TOC -->
|
||||
|
||||
@@ -82,9 +82,9 @@ xt_tcpudp |
|
||||
net.bridge.bridge-nf-call-iptables=1
|
||||
```
|
||||
|
||||
### RedHat Enterprise Linux (RHEL) / Oracle Enterprise Linux (OEL) / CentOS
|
||||
### Red Hat Enterprise Linux (RHEL) / Oracle Enterprise Linux (OEL) / CentOS
|
||||
|
||||
If using RedHat Enterprise Linux, Oracle Enterprise Linux or CentOS, you cannot use the `root` user as [SSH user]({{< baseurl >}}/rke/v0.1.x/en/config-options/nodes/#ssh-user) due to [Bugzilla 1527565](https://bugzilla.redhat.com/show_bug.cgi?id=1527565). Please follow the instructions below how to setup Docker correctly, based on the way you installed Docker on the node.
|
||||
If using Red Hat Enterprise Linux, Oracle Enterprise Linux or CentOS, you cannot use the `root` user as [SSH user]({{< baseurl >}}/rke/v0.1.x/en/config-options/nodes/#ssh-user) due to [Bugzilla 1527565](https://bugzilla.redhat.com/show_bug.cgi?id=1527565). Please follow the instructions below how to setup Docker correctly, based on the way you installed Docker on the node.
|
||||
|
||||
#### Using upstream Docker
|
||||
If you are using upstream Docker, the package name is `docker-ce` or `docker-ee`. You can check the installed package by executing:
|
||||
@@ -96,13 +96,13 @@ rpm -q docker-ce
|
||||
When using the upstream Docker packages, please follow [Manage Docker as a non-root user](https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user).
|
||||
|
||||
#### Using RHEL/CentOS packaged Docker
|
||||
If you are using the Docker Docker package supplied by RedHat / CentOS, the package name is `docker`. You can check the installed package by executing:
|
||||
If you are using the Docker Docker package supplied by Red Hat / CentOS, the package name is `docker`. You can check the installed package by executing:
|
||||
|
||||
```
|
||||
rpm -q docker
|
||||
```
|
||||
|
||||
If you are using the Docker package supplied by RedHat / CentOS, the `dockerroot` group is automatically added to the system. You will need to edit (or create) `/etc/docker/daemon.json` to include the following:
|
||||
If you are using the Docker package supplied by Red Hat / CentOS, the `dockerroot` group is automatically added to the system. You will need to edit (or create) `/etc/docker/daemon.json` to include the following:
|
||||
|
||||
```
|
||||
{
|
||||
@@ -130,15 +130,31 @@ $ docker ps
|
||||
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
|
||||
```
|
||||
|
||||
### Red Hat Atomic
|
||||
|
||||
Before trying to use RKE with Red Hat Atomic nodes, there are a couple of updates to the OS that need to occur in order to get RKE working.
|
||||
|
||||
#### OpenSSH version
|
||||
|
||||
By default, Atomic hosts ship with OpenSSH 6.4, which doesn't support SSH tunneling, which is a core RKE requirement. If you upgrade to the latest version of OpenSSH supported by Atomic, it will correct the SSH issue.
|
||||
|
||||
#### Creating a Docker Group
|
||||
|
||||
By default, Atomic hosts do not come with a Docker group. You can update the ownership of the Docker socket by enabling the specific user in order to launch RKE.
|
||||
|
||||
```
|
||||
# chown <user> /var/run/docker.sock
|
||||
```
|
||||
|
||||
## Software
|
||||
|
||||
- Docker - Each Kubernetes version supports different Docker versions.
|
||||
|
||||
Kubernetes Version | Docker 1.12.6 | Docker 1.13.1 | Docker 17.03.2 |
|
||||
----|----|----|----|
|
||||
v1.11.x | X | X | X |
|
||||
v1.10.x | X | X | X |
|
||||
v1.9.x | X | X | X |
|
||||
v1.8.x | X | X | X |
|
||||
|
||||
You can either follow the [Docker installation](https://docs.docker.com/install/) instructions or use one of Rancher's [install scripts](https://github.com/rancher/install-docker) to install Docker.
|
||||
|
||||
@@ -174,12 +190,13 @@ Server:
|
||||
|
||||
## Ports
|
||||
|
||||
{{< ports-rke-nodes >}}
|
||||
{{< requirements_ports_rke >}}
|
||||
|
||||
If you are using an external firewall, make sure you have this port opened between the machine you are using to run `rke` and the nodes that you are going to use in the cluster.
|
||||
|
||||
|
||||
### Opening port TCP/6443 using `iptables``
|
||||
### Opening port TCP/6443 using `iptables`
|
||||
|
||||
```
|
||||
# Open TCP/6443 for all
|
||||
@@ -203,31 +220,3 @@ firewall-cmd --permanent --zone=public --add-rich-rule='
|
||||
port protocol="tcp" port="6443" accept'
|
||||
firewall-cmd --reload
|
||||
```
|
||||
|
||||
## Notes about Atomic Nodes
|
||||
|
||||
Before trying to use RKE with Atomic nodes, there are a couple of updates to the OS that need to occur in order to get RKE working.
|
||||
|
||||
### Container Volumes
|
||||
|
||||
In RKE, most of the volumes are mounted with option `z`, but there are some container volumes that may have some issues in Atomic due to SELinux.
|
||||
|
||||
Before running RKE, users will need to run the following commands to make some additional directories:
|
||||
|
||||
```
|
||||
# mkdir /opt/cni /etc/cni
|
||||
# chcon -Rt svirt_sandbox_file_t /etc/cni
|
||||
# chcon -Rt svirt_sandbox_file_t /opt/cni
|
||||
```
|
||||
|
||||
### OpenSSH version
|
||||
|
||||
By default, Atomic hosts ship with OpenSSH 6.4, which doesn't support SSH tunneling, which is a core RKE requirement. If you upgrade to the latest version of OpenSSH supported by Atomic, it will correct the SSH issue.
|
||||
|
||||
### Creating a Docker Group
|
||||
|
||||
By default, Atomic hosts do not come with a Docker group. You can update the ownership of the Docker socket by enabling the specific user in order to launch RKE.
|
||||
|
||||
```
|
||||
# chown <user> /var/run/docker.sock
|
||||
```
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
<div>
|
||||
<p><strong>RKE node:</strong><br/>Node that runs the <code>rke</code> commands</p>
|
||||
<h3>RKE node - Outbound rules</h3>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Protocol</th>
|
||||
<th>Port</th>
|
||||
<th>Source</th>
|
||||
<th>Destination</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>TCP</td>
|
||||
<td>22</td>
|
||||
<td>RKE node</td>
|
||||
<td><ul><li>Any node configured in Cluster Configuration File</li></ul></td>
|
||||
<td>SSH provisioning of node by RKE</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>TCP</td>
|
||||
<td>6443</td>
|
||||
<td>RKE node</td>
|
||||
<td><ul><li>controlplane nodes</li></ul></td>
|
||||
<td>Kubernetes apiserver</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
Reference in New Issue
Block a user