diff --git a/docs/plugins/README.md b/docs/plugins/README.md index 92cc17373..42fbd3ffc 100644 --- a/docs/plugins/README.md +++ b/docs/plugins/README.md @@ -102,3 +102,32 @@ project, so please double-check where the code lives before filing InfraKit issu | [docker/infrakit.aws](https://github.com/docker/infrakit.aws) | instance | creates Amazon EC2 instances | Have a Plugin you'd like to share? Submit a Pull Request to add yourself to the list! + +### APIs +_InfraKit_ plugins are exposed via HTTP, using [JSON-RPC 2.0](http://www.jsonrpc.org/specification). + +API requests can be made manually with `curl`. For example, the following command will list all groups: +```console +$ curl -X POST --unix-socket ~/.infrakit/plugins/group http:/rpc \ + -H 'Content-Type: application/json' + -d '{"jsonrpc":"2.0","method":"Group.InspectGroups","params":{},"id":5577006791947779410}' +{"jsonrpc":"2.0","result":{"Groups":null},"id":1} +``` + +API errors are surfaced with the `error` response field: +```console +$ curl -X POST --unix-socket ~/.infrakit/plugins/group http:/rpc \ + -H 'Content-Type: application/json' + -d '{"jsonrpc":"2.0","method":"Group.CommitGroup","params":{},"id":1}' +{"jsonrpc":"2.0","error":{"code":-32000,"message":"Group ID must not be blank","data":null},"id":1} +``` + +Per the JSON-RPC format, each API call has a `method` and `params`. The following pages define the available methods +for each plugin type: +- [Flavor](flavor.md) +- [Group](group.md) +- [Instance](instance.md) + +See also: documentation on common API [types](types.md). + +Additionally, all plugins will log each API HTTP request and response when run with the `--log 5` command line argument. diff --git a/docs/plugins/flavor.md b/docs/plugins/flavor.md new file mode 100644 index 000000000..8d89d5cba --- /dev/null +++ b/docs/plugins/flavor.md @@ -0,0 +1,144 @@ +# Flavor plugin API + + + +## API + +### Method `Flavor.Validate` +Checks whether a Flavor configuration is valid. + +#### Request +```json +{ + "Properties": {}, + "Allocation": { + "Size": 1, + "LogicalIDs": ["logical_id_1"] + } +} +``` + +Parameters: +- `Properties`: A JSON object representing the Flavor. The schema is defined by the Flavor plugin in use. +- `Allocation`: An [Allocation](types.md#allocation) + + +#### Response +```json +{ + "OK": true +} +``` + +`OK`: Whether the operation succeeded. + +### Method `Flavor.Prepare` +Instructs the Flavor Plugin to prepare an Instance with any additional configuration it wishes to include. The Flavor +may add, remove, or modify any fields in the Instance `Spec` by returning the desired Instance configuration. + +#### Request +```json +{ + "Properties": {}, + "Spec": { + "Properties": {}, + "Tags": { + "tag_key": "tag_value" + }, + "Init": "init script", + "LogicalID": "logical_id", + "Attachments": ["attachment_id"] + }, + "Allocation": { + "Size": 1, + "LogicalIDs": ["logical_id_1"] + } +} +``` + +Parameters: +- `Properties`: A JSON object representing the Flavor. The schema is defined by the Flavor plugin in use. +- `Spec`: The [Spec](types.md#instance-spec) of the Instance being prepared. +- `Allocation`: An [Allocation](types.md#allocation) + +#### Response +```json +{ + "Spec": { + "Properties": {}, + "Tags": { + "tag_key": "tag_value" + }, + "Init": "init script", + "LogicalID": "logical_id", + "Attachments": ["attachment_id"] + } +} +``` + +Fields: +- `Spec`: The [Spec](types.md#instance-spec) of the Instance, with the Flavor's adjustments made. + +### Method `Flavor.Healthy` +Checks whether the Flavor plugin considers an Instance to be healthy. + +#### Request +```json +{ + "Properties": {}, + "Instance": { + "ID": "instance_id", + "LogicalID": "logical_id", + "Tags": { + "tag_key": "tag_value" + } + } +} +``` + +Parameters: +- `Properties`: A JSON object representing the Flavor. The schema is defined by the Flavor plugin in use. +- `Instance`: The [Instance Description](types.md#instance-description) + +#### Response +```json +{ + "Health": 1 +} +``` + +Fields: +- `Health`: An integer representing the health the instance. `0` for 'unknown', `1` for 'healthy', or `2' for + 'unhealthy' + +### Method `Flavor.Drain` +Informs the Flavor plugin that an Instance will soon be terminated, and allows the plugin to perform any necessary +cleanup work prior to removing the instance. + +#### Request +```json +{ + "Properties": {}, + "Instance": { + "ID": "instance_id", + "LogicalID": "logical_id", + "Tags": { + "tag_key": "tag_value" + } + } +} +``` + +Parameters: +- `Properties`: A JSON object representing the Flavor. The schema is defined by the Flavor plugin in use. +- `Instance`: The [Instance Description](types.md#instance-description) + +#### Response +```json +{ + "OK": true +} +``` + +Fields: +- `OK`: Whether the operation succeeded. diff --git a/docs/plugins/group.md b/docs/plugins/group.md new file mode 100644 index 000000000..5eddde3ae --- /dev/null +++ b/docs/plugins/group.md @@ -0,0 +1,140 @@ +# Group plugin API + + + +## API + +### Method `Group.CommitGroup` +Submits the configuration for a group. The Group plugin is responsible for making any changes necessary to effect the +configuration. + +#### Request +```json +{ + "Spec": { + "ID": "group_id", + "Properties": {} + }, + "Pretend": true +} +``` + +Parameters: +- `Spec`: A [Group Spec](types.md#group-spec) +- `Pretend`: Whether to actually perform the change. If `false`, the request will have no side-effects. + +#### Response +```json +{ + "Details": "human readable text" +} +``` + +Fields: +- `Details`: A human-readable description of the commit action, or proposed action if `Pretend` was `true`. + + +### Method `Group.FreeGroup` +Removes a Group from active management. This operation is non-destructive - it will not destroy or modify any resources +associated with the Group. However, the Plugin will no longer attempt to maintain the state of the Group. + +#### Request +```json +{ + "ID": "group_id" +} +``` + +Parameters: +- `ID`: [Group ID](types.md#group-id) + +#### Response +```json +{ + "OK": true +} +``` + +Fields: +- `OK`: Whether the operation succeeded. + +### Method `Group.DescribeGroup` +Fetches details about the current status of a Group. + +#### Request +```json +{ + "ID": "group_Id" +} +``` + +Parameters: +- `ID`: [Group ID](types.md#group-id) + +#### Response +```json +{ + "Description": { + "Instances": [ + { + "ID": "instance_id", + "LogicalID": "logical_id", + "Tags": { + "tag_key": "tag_value" + } + } + ], + "Converged": true + } +} +``` + +Fields: +- `Description`: A [Group Description](types.md#group-description) + +### Method `Group.DestroyGroup` + +#### Request +```json +{ + "ID": "group_Id" +} +``` + +Parameters: +- `ID`: [Group ID](types.md#group-id) + +#### Response +```json +{ + "OK": true +} +``` + +Fields: +- `OK`: Whether the operation succeeded. + +### Method `Group.InspectGroups` +Fetches details about the state associated with a Group. + +#### Request +```json +{} +``` + +Parameters: None + +#### Response +```json +{ + "Groups": [ + { + "ID": "group_id", + "Properties": {} + } + ] +} +``` + +Fields: +- `Groups`: An array of [Group Specs](types.md#group-spec) diff --git a/docs/plugins/instance.md b/docs/plugins/instance.md index 63c99a736..18332b454 100644 --- a/docs/plugins/instance.md +++ b/docs/plugins/instance.md @@ -1,5 +1,110 @@ -# Instance plugin +# Instance plugin API ## API + +### Method `Instance.Validate` +Checks whether an instance configuration is valid. Must be free of side-effects. + +#### Request +```json +{ + "Properties": {} +} +``` + +Parameters: +- `Properties`: A JSON object representing the Instance. The schema is defined by the Instance plugin in use. + + +#### Response +```json +{ + "OK": true +} +``` + +Fields: +- `OK`: Whether the operation succeeded. + +### Method `Instance.Provision` +Provisions a new instance. + +#### Request +```json +{ + "Spec": { + "Properties": {}, + "Tags": {"tag_key": "tag_value"}, + "Init": "", + "LogicalID": "logical_id", + "Attachments": ["attachment_id"] + } +} +``` + +Parameters: +- `Spec`: an [Instance Spec](types.md#instance-spec). + +#### Response +```json +{ + "ID": "instance_id" +} +``` + +Fields: +- `ID`: An [instance ID](types.md#instance-id). + +### Method `Instance.Destroy` +Permanently destroys an instance. + +#### Request +```json +{ + "Instance": "instance_id" +} +``` + +Parameters: +- `Instance`: An [instance ID](types.md#instance-id). + +#### Response +```json +{ + "OK": true +} +``` + +Fields: +- `OK`: Whether the operation succeeded. + +### Method `Instance.DescribeInstances` +Fetches details about Instances. + +#### Request +```json +{ + "Tags": {"tag_key": "tag_value"} +} +``` + +Parameters: +- `Tags`: Instance tags to match. If multiple tags are specified, only Instances matching all tags are returned. + +#### Response +```json +{ + "Descriptions": [ + { + "ID": "instance_id", + "LogicalID": "logical_id", + "Tags": {"tag_key": "tag_value"} + } + ] +} +``` + +Fields: +- `Descriptions`: An array of matching [Instance Descriptions](types.md#instance-description) diff --git a/docs/plugins/types.md b/docs/plugins/types.md new file mode 100644 index 000000000..ca2cf0c80 --- /dev/null +++ b/docs/plugins/types.md @@ -0,0 +1,70 @@ +# API types and common fields + +# Allocation +The method and details for allocating a group. Groups are homogeneous (cattle) when the `Size` field is set, or +nearly-homogeneous (pets) when the `LogicalIDs` field is set. + +Groups using `LogicalIDs` will converge towards maintaining a number of Instances matching the number of `LogicalIDs`, +where each Instance is uniquely assigned a logical ID. The ID will be present in the `LogicalID` field of the Instance +[Description](#instance-description) and [Spec](#instance-spec). Logical IDs are useful for behavior such as managing +a pool of `Attachments` for state attached to instances. + +Fields: +- `Size`: An integer, the number of instances to maintain in the Group. +- `LogicalIDs`: An array of strings, the logical identifeirs to maintain in the group. + +# Group ID +A globally-unique string identifier for an Group. + + +# Group Description + +Fields: +- `Instances`: An array of [Instance Descriptions](#instance-description) +- `Converged`: `true` if the state of the Group matches the most recently + [Committed](group.md#method-group-commit-group) state, `false` otherwise. + + +# Group Spec +The declared specification of a Group. + +Fields: +- `ID`: [Group ID](types.md#group-id) +- `Properties`: A JSON object representing the Group. The schema is defined by the Group plugin in use. + +### Instance Attachment +An identifier for an external entity associated with an Instance. The meaning of Attachments and handling of Attachment +IDs is defined by the Instance plugin. + + +### Instance Description +The description of an existing Instance. + +Fields: +- `ID`: An [Instance ID](types.md#instance-id) +- `LogicalID`: [Logical ID](#logical-id) +- `Tags`: [Instance Tags](#instance-tags) + +### Instance ID +A globally-unique string identifier for an Instance. + + +### Instance Spec +The declared specification of an Instance. + +Fields: +- `Properties`: A JSON object representing the Instance to create. The schema is defined by the Instance plugin in use. +- `Tags`: [Instance Tags](#instance-tags) +- `Init`: a shell script to run when the instance boots. +- `LogicalID`: [Logical ID](#logical-id) +- `Attachments`: an array [Attachments](#instance-attachment) + + +### Instance Tags +A key (string) to value (string) mapping of attributes to include on an instance. Tags are useful for user-defined +Instance grouping and metadata. + + +### Logical ID +A possibly-reused logical identifier for an Instance. + diff --git a/pkg/rpc/group/types.go b/pkg/rpc/group/types.go index 3ab33ed65..7003df201 100644 --- a/pkg/rpc/group/types.go +++ b/pkg/rpc/group/types.go @@ -45,12 +45,11 @@ type DestroyGroupResponse struct { OK bool } -// InspectGroupsRequest is the rpc wrapper for the input to destroy a group +// InspectGroupsRequest is the rpc wrapper for the input to inspect groups type InspectGroupsRequest struct { - ID group.ID } -// InspectGroupsResponse is the rpc wrapper for the output from destroying a group +// InspectGroupsResponse is the rpc wrapper for the output from inspecting groups type InspectGroupsResponse struct { Groups []group.Spec } diff --git a/scripts/doc-source-check b/scripts/doc-source-check index 378e6718d..170fa1196 100755 --- a/scripts/doc-source-check +++ b/scripts/doc-source-check @@ -51,9 +51,18 @@ do then echo "PASS" else - echo "FAIL" - echo "Expected: $checksum" - echo "Actual: $hash" + echo "FAIL +Expected: $checksum +Actual: $hash + +The document at $f contains a SOURCE-CHECKSUM tag indicating +that it describes $file_pattern. The checksum has changed, which indicates +that $file_pattern has changed, but the checksum at $f has not. + +Please double-check that the documentation is up-to-date and certify the +documentation by updating the SOURCE-CHECKSUM SHA with the above 'Actual' +value. +" exit 1 fi done