Skip to content
This repository was archived by the owner on Jan 21, 2020. It is now read-only.

Commit 8ff3bf5

Browse files
wfarnerDavid Chung
wfarner
authored and
David Chung
committed
Add documentation for plugin HTTP APIs (#311)
Signed-off-by: Bill Farner <[email protected]>
1 parent a6d51a5 commit 8ff3bf5

File tree

7 files changed

+503
-7
lines changed

7 files changed

+503
-7
lines changed

‎docs/plugins/README.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,3 +102,32 @@ project, so please double-check where the code lives before filing InfraKit issu
102102
| [docker/infrakit.aws](https://github.com/docker/infrakit.aws) | instance | creates Amazon EC2 instances |
103103

104104
Have a Plugin you'd like to share? Submit a Pull Request to add yourself to the list!
105+
106+
### APIs
107+
_InfraKit_ plugins are exposed via HTTP, using [JSON-RPC 2.0](http://www.jsonrpc.org/specification).
108+
109+
API requests can be made manually with `curl`. For example, the following command will list all groups:
110+
```console
111+
$ curl -X POST --unix-socket ~/.infrakit/plugins/group http:/rpc \
112+
-H 'Content-Type: application/json'
113+
-d '{"jsonrpc":"2.0","method":"Group.InspectGroups","params":{},"id":5577006791947779410}'
114+
{"jsonrpc":"2.0","result":{"Groups":null},"id":1}
115+
```
116+
117+
API errors are surfaced with the `error` response field:
118+
```console
119+
$ curl -X POST --unix-socket ~/.infrakit/plugins/group http:/rpc \
120+
-H 'Content-Type: application/json'
121+
-d '{"jsonrpc":"2.0","method":"Group.CommitGroup","params":{},"id":1}'
122+
{"jsonrpc":"2.0","error":{"code":-32000,"message":"Group ID must not be blank","data":null},"id":1}
123+
```
124+
125+
Per the JSON-RPC format, each API call has a `method` and `params`. The following pages define the available methods
126+
for each plugin type:
127+
- [Flavor](flavor.md)
128+
- [Group](group.md)
129+
- [Instance](instance.md)
130+
131+
See also: documentation on common API [types](types.md).
132+
133+
Additionally, all plugins will log each API HTTP request and response when run with the `--log 5` command line argument.

‎docs/plugins/flavor.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# Flavor plugin API
2+
3+
<!-- SOURCE-CHECKSUM pkg/spi/flavor/* 81a2c81f42a56ce0baa54511ee621f885fc7080e -->
4+
5+
## API
6+
7+
### Method `Flavor.Validate`
8+
Checks whether a Flavor configuration is valid.
9+
10+
#### Request
11+
```json
12+
{
13+
"Properties": {},
14+
"Allocation": {
15+
"Size": 1,
16+
"LogicalIDs": ["logical_id_1"]
17+
}
18+
}
19+
```
20+
21+
Parameters:
22+
- `Properties`: A JSON object representing the Flavor. The schema is defined by the Flavor plugin in use.
23+
- `Allocation`: An [Allocation](types.md#allocation)
24+
25+
26+
#### Response
27+
```json
28+
{
29+
"OK": true
30+
}
31+
```
32+
33+
`OK`: Whether the operation succeeded.
34+
35+
### Method `Flavor.Prepare`
36+
Instructs the Flavor Plugin to prepare an Instance with any additional configuration it wishes to include. The Flavor
37+
may add, remove, or modify any fields in the Instance `Spec` by returning the desired Instance configuration.
38+
39+
#### Request
40+
```json
41+
{
42+
"Properties": {},
43+
"Spec": {
44+
"Properties": {},
45+
"Tags": {
46+
"tag_key": "tag_value"
47+
},
48+
"Init": "init script",
49+
"LogicalID": "logical_id",
50+
"Attachments": ["attachment_id"]
51+
},
52+
"Allocation": {
53+
"Size": 1,
54+
"LogicalIDs": ["logical_id_1"]
55+
}
56+
}
57+
```
58+
59+
Parameters:
60+
- `Properties`: A JSON object representing the Flavor. The schema is defined by the Flavor plugin in use.
61+
- `Spec`: The [Spec](types.md#instance-spec) of the Instance being prepared.
62+
- `Allocation`: An [Allocation](types.md#allocation)
63+
64+
#### Response
65+
```json
66+
{
67+
"Spec": {
68+
"Properties": {},
69+
"Tags": {
70+
"tag_key": "tag_value"
71+
},
72+
"Init": "init script",
73+
"LogicalID": "logical_id",
74+
"Attachments": ["attachment_id"]
75+
}
76+
}
77+
```
78+
79+
Fields:
80+
- `Spec`: The [Spec](types.md#instance-spec) of the Instance, with the Flavor's adjustments made.
81+
82+
### Method `Flavor.Healthy`
83+
Checks whether the Flavor plugin considers an Instance to be healthy.
84+
85+
#### Request
86+
```json
87+
{
88+
"Properties": {},
89+
"Instance": {
90+
"ID": "instance_id",
91+
"LogicalID": "logical_id",
92+
"Tags": {
93+
"tag_key": "tag_value"
94+
}
95+
}
96+
}
97+
```
98+
99+
Parameters:
100+
- `Properties`: A JSON object representing the Flavor. The schema is defined by the Flavor plugin in use.
101+
- `Instance`: The [Instance Description](types.md#instance-description)
102+
103+
#### Response
104+
```json
105+
{
106+
"Health": 1
107+
}
108+
```
109+
110+
Fields:
111+
- `Health`: An integer representing the health the instance. `0` for 'unknown', `1` for 'healthy', or `2' for
112+
'unhealthy'
113+
114+
### Method `Flavor.Drain`
115+
Informs the Flavor plugin that an Instance will soon be terminated, and allows the plugin to perform any necessary
116+
cleanup work prior to removing the instance.
117+
118+
#### Request
119+
```json
120+
{
121+
"Properties": {},
122+
"Instance": {
123+
"ID": "instance_id",
124+
"LogicalID": "logical_id",
125+
"Tags": {
126+
"tag_key": "tag_value"
127+
}
128+
}
129+
}
130+
```
131+
132+
Parameters:
133+
- `Properties`: A JSON object representing the Flavor. The schema is defined by the Flavor plugin in use.
134+
- `Instance`: The [Instance Description](types.md#instance-description)
135+
136+
#### Response
137+
```json
138+
{
139+
"OK": true
140+
}
141+
```
142+
143+
Fields:
144+
- `OK`: Whether the operation succeeded.

‎docs/plugins/group.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# Group plugin API
2+
3+
<!-- SOURCE-CHECKSUM pkg/spi/group/* 0eec99ab5b4dc627b4025e29fb97dba4ced8c16f -->
4+
5+
## API
6+
7+
### Method `Group.CommitGroup`
8+
Submits the configuration for a group. The Group plugin is responsible for making any changes necessary to effect the
9+
configuration.
10+
11+
#### Request
12+
```json
13+
{
14+
"Spec": {
15+
"ID": "group_id",
16+
"Properties": {}
17+
},
18+
"Pretend": true
19+
}
20+
```
21+
22+
Parameters:
23+
- `Spec`: A [Group Spec](types.md#group-spec)
24+
- `Pretend`: Whether to actually perform the change. If `false`, the request will have no side-effects.
25+
26+
#### Response
27+
```json
28+
{
29+
"Details": "human readable text"
30+
}
31+
```
32+
33+
Fields:
34+
- `Details`: A human-readable description of the commit action, or proposed action if `Pretend` was `true`.
35+
36+
37+
### Method `Group.FreeGroup`
38+
Removes a Group from active management. This operation is non-destructive - it will not destroy or modify any resources
39+
associated with the Group. However, the Plugin will no longer attempt to maintain the state of the Group.
40+
41+
#### Request
42+
```json
43+
{
44+
"ID": "group_id"
45+
}
46+
```
47+
48+
Parameters:
49+
- `ID`: [Group ID](types.md#group-id)
50+
51+
#### Response
52+
```json
53+
{
54+
"OK": true
55+
}
56+
```
57+
58+
Fields:
59+
- `OK`: Whether the operation succeeded.
60+
61+
### Method `Group.DescribeGroup`
62+
Fetches details about the current status of a Group.
63+
64+
#### Request
65+
```json
66+
{
67+
"ID": "group_Id"
68+
}
69+
```
70+
71+
Parameters:
72+
- `ID`: [Group ID](types.md#group-id)
73+
74+
#### Response
75+
```json
76+
{
77+
"Description": {
78+
"Instances": [
79+
{
80+
"ID": "instance_id",
81+
"LogicalID": "logical_id",
82+
"Tags": {
83+
"tag_key": "tag_value"
84+
}
85+
}
86+
],
87+
"Converged": true
88+
}
89+
}
90+
```
91+
92+
Fields:
93+
- `Description`: A [Group Description](types.md#group-description)
94+
95+
### Method `Group.DestroyGroup`
96+
97+
#### Request
98+
```json
99+
{
100+
"ID": "group_Id"
101+
}
102+
```
103+
104+
Parameters:
105+
- `ID`: [Group ID](types.md#group-id)
106+
107+
#### Response
108+
```json
109+
{
110+
"OK": true
111+
}
112+
```
113+
114+
Fields:
115+
- `OK`: Whether the operation succeeded.
116+
117+
### Method `Group.InspectGroups`
118+
Fetches details about the state associated with a Group.
119+
120+
#### Request
121+
```json
122+
{}
123+
```
124+
125+
Parameters: None
126+
127+
#### Response
128+
```json
129+
{
130+
"Groups": [
131+
{
132+
"ID": "group_id",
133+
"Properties": {}
134+
}
135+
]
136+
}
137+
```
138+
139+
Fields:
140+
- `Groups`: An array of [Group Specs](types.md#group-spec)

0 commit comments

Comments
 (0)