Skip to content

Commit

Permalink
doc(Gorgone): Fix documentation of action module
Browse files Browse the repository at this point in the history 
Refs:MON-139728
  • Loading branch information
@Evan-Adam
Evan-Adam committed Aug 14, 2024
1 parent aa3b2ba commit 4d06a8d
Show file tree
Hide file tree
Showing 2 changed files with 46 additions and 36 deletions.
64 changes: 33 additions & 31 deletions gorgone/docs/api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,14 @@ Centreon Gorgone provides a RestAPI through its HTTP server module.

### Get Nodes Connection Status

| Endpoint | Method |
| :- | :- |
| /internal/constatus | `GET` |
| Endpoint | Method |
|:--------------------|:-------|
| /internal/constatus | `GET` |

#### Headers

| Header | Value |
| :- | :- |
| Header | Value |
|:-------|:-----------------|
| Accept | application/json |

#### Example
Expand Down Expand Up @@ -42,14 +42,14 @@ curl --request GET "https://hostname:8443/api/internal/constatus" \

### Get Public Key Thumbprint

| Endpoint | Method |
| :- | :- |
| /internal/thumbprint | `GET` |
| Endpoint | Method |
|:---------------------|:-------|
| /internal/thumbprint | `GET` |

#### Headers

| Header | Value |
| :- | :- |
| Header | Value |
|:-------|:-----------------|
| Accept | application/json |

#### Example
Expand All @@ -73,14 +73,14 @@ curl --request GET "https://hostname:8443/api/internal/thumbprint" \

### Get Runtime Informations And Statistics

| Endpoint | Method |
| :- | :- |
| /internal/information | `GET` |
| Endpoint | Method |
|:----------------------|:-------|
| /internal/information | `GET` |

#### Headers

| Header | Value |
| :- | :- |
| Header | Value |
|:-------|:-----------------|
| Accept | application/json |

#### Example
Expand Down Expand Up @@ -158,6 +158,7 @@ The available endpoints depend on which modules are loaded.
Endpoints are basically built from:

* API root,
* optional target node, local if not present ( `/nodes/:nodeid/` )
* Module's namespace,
* Module's name,
* Action
Expand All @@ -175,7 +176,7 @@ curl --request POST "https://hostname:8443/api/core/action/command" \
]"
```

Find more informations directly from modules documentations [here](../docs/modules.md).
Find more informations directly from modules documentations [here](./modules.md).

As Centreon Gorgone is asynchronous, those endpoints will return a token corresponding to the action.

Expand All @@ -187,7 +188,7 @@ As Centreon Gorgone is asynchronous, those endpoints will return a token corresp
}
```

That being said, its possible to make Gorgone work synchronously by providing two parameters.
That being said, it is possible to make Gorgone work synchronously by providing two parameters.

First one is `log_wait` with a numeric value in microseconds: this value defines the amount of time the API will wait before trying to retrieve log results.

Expand All @@ -202,7 +203,7 @@ Note: the `sync_wait` parameter is induced if you ask for a log directly specify
Using the `/core/action/command` endpoint with `log_wait` parameter set to 100000:

```bash
curl --request POST "https://hostname:8443/api/core/action/command&log_wait=100000" \
curl --request POST "https://hostname:8443/api/core/action/command?log_wait=100000" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data "[
Expand All @@ -219,12 +220,12 @@ This call will ask for the API to execute an action and will give a result after

Note: there is no need for logs synchronisation when dealing with local actions.

##### Launch a command remotly and wait for the result
##### Launch a command remotely and wait for the result

Using the `/nodes/:id/core/action/command` endpoint with `log_wait` parameter set to 100000:

```bash
curl --request POST "https://hostname:8443/api/nodes/2/core/action/command&log_wait=100000&sync_wait=200000" \
curl --request POST "https://hostname:8443/api/nodes/2/core/action/command?log_wait=100000&sync_wait=200000" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data "[
Expand All @@ -241,23 +242,24 @@ This call will ask for the API to execute an action on the node with ID 2, will

## Log endpoint

To retrieve the logs, a specific endpoint can be called as follow.
To retrieve the logs, a specific endpoint can be called as follows.

| Endpoint | Method |
| :- | :- |
| /log/:token | `GET` |
| Endpoint | Method |
|:------------------------------|:-------|
| /api/nodes/:nodeid/log/:token | `GET` |

#### Headers

| Header | Value |
| :- | :- |
| Accept | application/json |
| Header | Value |
|:-------|:------------------|
| Accept | application/json |

#### Path variables

| Variable | Description |
| :- | :- |
| token | Token of the action |
| Variable | Description |
|:---------|:---------------------------|
| token | Token of the action |
| nodeid | node id to search log into |

#### Examples

Expand All @@ -271,7 +273,7 @@ curl --request GET "https://hostname:8443/api/nodes/2/log/3f25bc3a797fe989d1fb05
--header "Accept: application/json"
```

This second example will force logs synchonisation before looking for results to retrieve. Default temporisation is 10ms and can be changed by providing `sync_wait` parameter.
This second example will force logs synchronisation before looking for results to retrieve. Default wait time is 10ms and can be changed by providing `sync_wait` parameter.

#### Response example

Expand Down
18 changes: 13 additions & 5 deletions gorgone/docs/modules/core/action.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ This module aims to execute actions on the server running the Gorgone daemon or
## Configuration

| Directive | Description | Default value |
| :--------------- | :------------------------------------------------------------- | :------------ |
|:-----------------|:---------------------------------------------------------------|:--------------|
| command_timeout | Time in seconds before a command is considered timed out | `30` |
| whitelist_cmds | Boolean to enable commands whitelist | `false` |
| allowed_cmds | Regexp list of allowed commands | |
Expand Down Expand Up @@ -38,7 +38,7 @@ allowed_cmds:
## Events
| Event | Description |
| :---------- | :-------------------------------------------------------------------------------------- |
|:------------|:----------------------------------------------------------------------------------------|
| ACTIONREADY | Internal event to notify the core |
| PROCESSCOPY | Process file or archive received from another daemon |
| COMMAND | Execute a shell command on the server running the daemon or on another server using SSH |
Expand All @@ -48,20 +48,20 @@ allowed_cmds:
### Execute a command line
| Endpoint | Method |
| :------------------- | :----- |
|:---------------------|:-------|
| /core/action/command | `POST` |

#### Headers

| Header | Value |
| :----------- | :--------------- |
|:-------------|:-----------------|
| Accept | application/json |
| Content-Type | application/json |

#### Body

| Key | Value |
| :---------------- | :------------------------------------------------------- |
|:------------------|:---------------------------------------------------------|
| command | Command to execute |
| timeout | Time in seconds before a command is considered timed out |
| continue_on_error | Behaviour in case of execution issue |
Expand All @@ -76,8 +76,11 @@ allowed_cmds:
]
```


#### Example

See a complete exemple of this endpoint in the [api documentation](../../api.md)

```bash
curl --request POST "https://hostname:8443/api/core/action/command" \
--header "Accept: application/json" \
Expand All @@ -88,3 +91,8 @@ curl --request POST "https://hostname:8443/api/core/action/command" \
}
]"
```
Output :
```bash
{"token":"b3f825f87d64764316d872c59e4bae69299b0003f6e5d27bbc7de4e27c50eb65fc17440baf218578343eff7f4d67f7e98ab6da40b050a2635bb735c7cec276bd"}
```

0 comments on commit 4d06a8d

Please sign in to comment.