15308555518/ website
1
0
Fork 0
mirror of https://github.com/kubesphere/website.git synced 2025-12-26 00:12:48 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #944 from Sherlock113/apii 

fix wording in API doc
This commit is contained in:
Sherlock113 2021-01-15 15:40:57 +08:00 committed by GitHub
parent 153d400b7a 450021e949
commit a392e04828
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 42 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
content/en/docs/api-reference/api-docs.md
View File

@ -2,31 +2,28 @@
title: "KubeSphere API"
keywords: 'Kubernetes, KubeSphere, API'
description: 'KubeSphere API documentation'
linkTitle: "KubeSphere API"
weight: 17100
---
## Architecture
The KubeSphere API server validates and configures data for the API objects.
The API Server services REST operations and provide the frontend to the
cluster's shared state through which all other components interact.
The KubeSphere API server validates and configures data for API objects. The API Server services REST operations and provides the frontend to the cluster's shared state through which all other components interact.
![ks-apiserver](/images/docs/api-reference/ks-apiserver.png)
![ks-apiserver](/images/docs/api-reference/kubesphere-api/ks-apiserver.png)
## How to use KubeSphere API
## Use the KubeSphere API
In KubeSphere v3.0, we move the functionalities of _ks-apigateway_, _ks-account_ into _ks-apiserver_ to make the architecture more compact and straight forward. In order to use KubeSphere API, you need to expose _ks-apiserver_ to your client.
KubeSphere v3.0 moves the functionalities of **ks-apigateway** and **ks-account** into **ks-apiserver** to make the architecture more compact and clear. In order to use the KubeSphere API, you need to expose **ks-apiserver** to your client.
### Step 1: Expose KubeSphere API service
### Step 1: Expose the KubeSphere API service
If you are going to access KubeSphere inside the cluster, you can skip the following section and just use the KubeSphere API server endpoint **`http://ks-apiserver.kubesphere-system.svc`**.
On the other hand, you need to expose the KubeSphere API server endpoint to the outside of the cluster first.
On the other hand, you need to expose the KubeSphere API server endpoint outside the cluster first.
There are many ways to expose a Kubernetes service. For simplicity, we use _NodePort_ in our case. Change service `ks-apiserver` type to NodePort by using the following command.
There are many ways to expose a Kubernetes service. For demonstration purposes, this example uses `NodePort`. Change the service type of `ks-apiserver` to `NodePort` by using the following command.
```bash
$ kubectl -n kubesphere-system patch service ks-apiserver -p '{"spec":{"type":"NodePort"}}'
@ -37,11 +34,11 @@ ks-apiserver NodePort 10.233.15.31 <none> 80:31407/TCP
ks-console NodePort 10.233.3.45 <none> 80:30880/TCP 49d
```
Now, you can access `ks-apiserver` outside the cluster through URL like `http://[node ip]:31407`, where `[node ip]` means IP of any node in your cluster.
Now, you can access `ks-apiserver` outside the cluster through the URL like `http://[node ip]:31407`, where `[node ip]` means the IP address of any node in your cluster.
### Step 2: Generate a token
You need to identify yourself before making any call to the API server. Let's take a user `jeff` with password `P#$$w0rd` as an example. He needs to issue a request to generate a token like the following:
You need to identify yourself before making any call to the API server. The following example uses the password `P#$$w0rd`. The user needs to issue a request to generate a token as below:
```bash
curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
@ -53,11 +50,11 @@ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
{{< notice note >}}
Please substitue `[node ip]` with the real ip address.
Replace `[node ip]` with your actual IP address.
{{</ notice >}}
If the identity is correct, the server will response something like the following. `access_token` is the token to access the KubeSphere API Server.
If the identity is correct, the server will respond as shown in the following output. `access_token` is the token to access the KubeSphere API Server.
```json
{
@ -70,7 +67,7 @@ If the identity is correct, the server will response something like the followin
### Step 3: Make the call
Now you got everything you need to access KubeSphere API server. Make the call using the access token acquired above as the following to get node list:
If you have everything you need to access the KubeSphere API server, make the call using the access token acquired above as shown in the following example to get the node list:
```bash
$ curl -X GET -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImFkbWluIiwidWlkIjoiYTlhNjJmOTEtYWQ2Yi00MjRlLWIxNWEtZTFkOTcyNmUzNDFhIiwidG9rZW5fdHlwZSI6ImFjY2Vzc190b2tlbiIsImV4cCI6MTYwMDg1MjM5OCwiaWF0IjoxNjAwODQ1MTk4LCJpc3MiOiJrdWJlc3BoZXJlIiwibmJmIjoxNjAwODQ1MTk4fQ.Hcyf-CPMeq8XyQQLz5PO-oE1Rp1QVkOeV_5J2oX1hvU" \
@ -109,13 +106,13 @@ $ curl -X GET -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ
{{< notice note >}}
Please substitue `[node ip]` with the real ip address.
Replace `[node ip]` with your actual IP address.
{{</ notice >}}
## API Reference
KubeSpehre API swagger json can be found in repo https://github.com/kubesphere/kubesphere/tree/release-3.0/api
The KubeSphere API swagger JSON file can be found in the repository https://github.com/kubesphere/kubesphere/tree/release-3.0/api.
- KubeSphere specified API [swagger json](https://github.com/kubesphere/kubesphere/blob/release-3.0/api/ks-openapi-spec/swagger.json). It contains all the APIs that are only applied to KubeSphere.
- KubeSphere specified CRD [swagger json](https://github.com/kubesphere/kubesphere/blob/release-3.0/api/openapi-spec/swagger.json). It contains all the generated CRDs API documentation. It is same with Kubernetes api objects.
- KubeSphere specified the API [swagger json](https://github.com/kubesphere/kubesphere/blob/release-3.0/api/ks-openapi-spec/swagger.json) file. It contains all the APIs that are only applied to KubeSphere.
- KubeSphere specified the CRD [swagger json](https://github.com/kubesphere/kubesphere/blob/release-3.0/api/openapi-spec/swagger.json) file. It contains all the generated CRDs API documentation. It is same as Kubernetes API objects.

42
content/zh/docs/api-reference/api-docs.md
View File

@ -2,20 +2,28 @@
title: "KubeSphere API"
keywords: 'Kubernetes, KubeSphere, API'
description: 'KubeSphere API documentation'
linkTitle: "KubeSphere API"
weight: 17100
---
In KubeSphere v3.0, we move the functionalities of _ks-apigateway_, _ks-account_ into _ks-apiserver_ to make the architecture more compact and straight forward. In order to use KubeSphere API, you need to expose _ks-apiserver_ to your client.
## Architecture
## Step 1: Expose KubeSphere API service
The KubeSphere API server validates and configures data for API objects. The API Server services REST operations and provides the frontend to the cluster's shared state through which all other components interact.
![ks-apiserver](/images/docs/api-reference/kubesphere-api/ks-apiserver.png)
## Use the KubeSphere API
KubeSphere v3.0 moves the functionalities of **ks-apigateway** and **ks-account** into **ks-apiserver** to make the architecture more compact and clear. In order to use the KubeSphere API, you need to expose **ks-apiserver** to your client.
### Step 1: Expose the KubeSphere API service
If you are going to access KubeSphere inside the cluster, you can skip the following section and just use the KubeSphere API server endpoint **`http://ks-apiserver.kubesphere-system.svc`**.
On the other hand, you need to expose the KubeSphere API server endpoint to the outside of the cluster first.
On the other hand, you need to expose the KubeSphere API server endpoint outside the cluster first.
There are many ways to expose a Kubernetes service. For simplicity, we use _NodePort_ in our case. Change service `ks-apiserver` type to NodePort by using the following command.
There are many ways to expose a Kubernetes service. For demonstration purposes, this example uses `NodePort`. Change the service type of `ks-apiserver` to `NodePort` by using the following command.
```bash
$ kubectl -n kubesphere-system patch service ks-apiserver -p '{"spec":{"type":"NodePort"}}'
@ -26,11 +34,11 @@ ks-apiserver NodePort 10.233.15.31 <none> 80:31407/TCP
ks-console NodePort 10.233.3.45 <none> 80:30880/TCP 49d
```
Now, you can access `ks-apiserver` outside the cluster through URL like `http://[node ip]:31407`, where `[node ip]` means IP of any node in your cluster.
Now, you can access `ks-apiserver` outside the cluster through the URL like `http://[node ip]:31407`, where `[node ip]` means the IP address of any node in your cluster.
## Step 2: Generate a token
### Step 2: Generate a token
You need to identify yourself before making any call to the API server. Let's take a user `jeff` with password `P#$$w0rd` as an example. He needs to issue a request to generate a token like the following:
You need to identify yourself before making any call to the API server. The following example uses the password `P#$$w0rd`. The user needs to issue a request to generate a token as below:
```bash
curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
@ -42,11 +50,11 @@ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
{{< notice note >}}
Please substitue `[node ip]` with the real ip address.
Replace `[node ip]` with your actual IP address.
{{</ notice >}}
If the identity is correct, the server will response something like the following. `access_token` is the token to access the KubeSphere API Server.
If the identity is correct, the server will respond as shown in the following output. `access_token` is the token to access the KubeSphere API Server.
```json
{
@ -57,9 +65,9 @@ If the identity is correct, the server will response something like the followin
}
```
## Step 3: Make the call
### Step 3: Make the call
Now you got everything you need to access KubeSphere API server. Make the call using the access token acquired above as the following to get node list:
If you have everything you need to access the KubeSphere API server, make the call using the access token acquired above as shown in the following example to get the node list:
```bash
$ curl -X GET -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImFkbWluIiwidWlkIjoiYTlhNjJmOTEtYWQ2Yi00MjRlLWIxNWEtZTFkOTcyNmUzNDFhIiwidG9rZW5fdHlwZSI6ImFjY2Vzc190b2tlbiIsImV4cCI6MTYwMDg1MjM5OCwiaWF0IjoxNjAwODQ1MTk4LCJpc3MiOiJrdWJlc3BoZXJlIiwibmJmIjoxNjAwODQ1MTk4fQ.Hcyf-CPMeq8XyQQLz5PO-oE1Rp1QVkOeV_5J2oX1hvU" \
@ -98,13 +106,13 @@ $ curl -X GET -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ
{{< notice note >}}
Please substitue `[node ip]` with the real ip address.
Replace `[node ip]` with your actual IP address.
{{</ notice >}}
## API Reference
KubeSpehre API swagger json can be found in repo https://github.com/kubesphere/kubesphere/tree/release-3.0/api
The KubeSphere API swagger JSON file can be found in the repository https://github.com/kubesphere/kubesphere/tree/release-3.0/api.
- KubeSphere specified API [swagger json](https://github.com/kubesphere/kubesphere/blob/release-3.0/api/ks-openapi-spec/swagger.json). It contains all the APIs that are only applied to KubeSphere.
- KubeSphere specified CRD [swagger json](https://github.com/kubesphere/kubesphere/blob/release-3.0/api/openapi-spec/swagger.json). It contains all the generated CRDs API documentation. It is same with Kubernetes api objects.
- KubeSphere specified the API [swagger json](https://github.com/kubesphere/kubesphere/blob/release-3.0/api/ks-openapi-spec/swagger.json) file. It contains all the APIs that are only applied to KubeSphere.
- KubeSphere specified the CRD [swagger json](https://github.com/kubesphere/kubesphere/blob/release-3.0/api/openapi-spec/swagger.json) file. It contains all the generated CRDs API documentation. It is same as Kubernetes API objects.

BIN
static/images/docs/api-reference/kubesphere-api/ks-apiserver.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 263 KiB