tyler.durden
/
icinga2
mirror of https://github.com/Icinga/icinga2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

API Documentation: Explain DELETE for config stages/packages 

fixes #10591
This commit is contained in:
Michael Friedrich 2015-11-10 16:55:26 +01:00
parent 503826acf5
commit 7c361853ad
1 changed files with 89 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
doc/9-icinga2-api.md
View File

@ -1135,7 +1135,8 @@ can be fetched in a separated request.
Send a `POST` request to a new config package called `example-cmdb` in this example. This Send a `POST` request to a new config package called `example-cmdb` in this example. This
will create a new empty configuration package. will create a new empty configuration package.
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST https://localhost:5665/v1/config/packages/example-cmdb | python -m json.tool $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST \
'https://localhost:5665/v1/config/packages/example-cmdb' | python -m json.tool
{ {
"results": [ "results": [
{ {
@ -1146,25 +1147,25 @@ will create a new empty configuration package.
] ]
} }
Package names starting with an underscore are exclusive to the Icinga 2 daemon
and must not be used.
### <a id="icinga2-api-config-management-create-config-stage"></a> Uploading configuration for a Config Package ### <a id="icinga2-api-config-management-create-config-stage"></a> Uploading configuration for a Config Package
Configuration files in packages are managed in stages. Stages provide a way to maintain multiple configuration versions for a package. Configuration files in packages are managed in stages. Stages provide a way to maintain multiple configuration versions for a package.
Send a `POST` request to the URL endpoint `/v1/config/stages` including an existing Send a `POST` request to the URL endpoint `/v1/config/stages` and add the name of an existing
configuration package, e.g. `example-cmdb`. configuration package to the URL path (e.g. `example-cmdb`).
The request body must contain the `files` attribute with the value being The request body must contain the `files` attribute with the value being
a dictionary of file targets and their content. a dictionary of file targets and their content.
The example below will create a new file called `test.conf` in the `conf.d` The example below will create a new file called `test.conf` in the `conf.d`
directory. directory. Note: This example contains an error (`chec_command`). This is
intentional.
The Icinga 2 API returns the `package` name this stage was created for, and also $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST \
generates a unique name for the `stage` attribute you'll need for later requests. -d '{ "files": { "conf.d/test.conf": "object Host \"cmdb-host\" { chec_command = \"dummy\" }" } }' \
'https://localhost:5665/v1/config/stages/example-cmdb' | python -m json.tool
Note: This example contains an error (`chec_command`). This is intentional.
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST -d '{ "files": { "conf.d/test.conf": "object Host \"cfg-mgmt\" { chec_command = \"dummy\" }" } }' https://localhost:5665/v1/config/stages/example-cmdb | python -m json.tool
{ {
"results": [ "results": [
{ {
@ -1176,20 +1177,27 @@ Note: This example contains an error (`chec_command`). This is intentional.
] ]
} }
Icinga 2 automatically restarts to activate the new config stage. If validation for the new config stage fails the old stage will remain active. The Icinga 2 API returns the `package` name this stage was created for, and also
generates a unique name for the `stage` attribute you'll need for later requests.
Old stages are not automatically removed. You can remove stages that are no longer use. Icinga 2 automatically restarts the daemon in order to activate the new config stage.
If the validation for the new config stage failed the old stage and its configuration objects
will remain active.
Icinga 2 automatically creates the following files in the main configuration package > **Note**
stage: >
> Old stages are not purged automatically. You can [remove stages](9-icinga2-api.md#) that are no longer in use.
Icinga 2 will create the following files in the configuration package
stage after configuration validation:
File | Description File | Description
------------|-------------- ------------|--------------
status | Contains the [configuration validation](8-cli-commands.md#config-validation) exit code (everything else than 0 indicates an error). status | Contains the [configuration validation](8-cli-commands.md#config-validation) exit code (everything else than 0 indicates an error).
startup.log | Contains the [configuration validation](8-cli-commands.md#config-validation) output. startup.log | Contains the [configuration validation](8-cli-commands.md#config-validation) output.
You can [fetch these files](9-icinga2-api.md#icinga2-api-config-management-fetch-config-package-stage-files) via API call You can [fetch these files](9-icinga2-api.md#icinga2-api-config-management-fetch-config-package-stage-files)
after creating a new stage. in order to verify that the new configuration was deployed successfully.
### <a id="icinga2-api-config-management-list-config-packages"></a> List Configuration Packages and their Stages ### <a id="icinga2-api-config-management-list-config-packages"></a> List Configuration Packages and their Stages
@ -1199,7 +1207,7 @@ A list of packages and their stages can be retrieved by sending a `GET` request
The following example contains one configuration package `example-cmdb`. The package does not currently The following example contains one configuration package `example-cmdb`. The package does not currently
have an active stage. have an active stage.
$ curl -k -s -u root:icinga https://localhost:5665/v1/config/packages | python -m json.tool $ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/packages' | python -m json.tool
{ {
"results": [ "results": [
{ {
@ -1215,10 +1223,11 @@ have an active stage.
### <a id="icinga2-api-config-management-list-config-package-stage-files"></a> List Configuration Packages and their Stages ### <a id="icinga2-api-config-management-list-config-package-stage-files"></a> List Configuration Packages and their Stages
In order to retrieve a list of files for a stage you can send a `GET` request to the URL endpoint `/v1/config/stages`. You need to include In order to retrieve a list of files for a stage you can send a `GET` request to
the URL endpoint `/v1/config/stages`. You need to include
the package name (`example-cmdb`) and stage name (`example.localdomain-1441625839-0`) in the URL: the package name (`example-cmdb`) and stage name (`example.localdomain-1441625839-0`) in the URL:
$ curl -k -s -u root:icinga https://localhost:5665/v1/config/stages/example-cmdb/example.localdomain-1441625839-0 | python -m json.tool $ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/stages/example-cmdb/example.localdomain-1441625839-0' | python -m json.tool
{ {
"results": [ "results": [
... ...
@ -1247,39 +1256,90 @@ the package name (`example-cmdb`) and stage name (`example.localdomain-144162583
### <a id="icinga2-api-config-management-fetch-config-package-stage-files"></a> Fetch Configuration Package Stage Files ### <a id="icinga2-api-config-management-fetch-config-package-stage-files"></a> Fetch Configuration Package Stage Files
Send a `GET` request to the URL endpoint `/v1/config/files` including Send a `GET` request to the URL endpoint `/v1/config/files` and add
the package name, the stage name and the relative path to the file. the package name, the stage name and the relative path to the file to the URL path.
You can fetch a [list of existing files](9-icinga2-api.md#icinga2-api-config-management-list-config-package-stage-files)
in a configuration stage and then specifically request their content.
> **Note** > **Note**
>
> The returned files are plain-text instead of JSON-encoded. > The returned files are plain-text instead of JSON-encoded.
The following example fetches the configuration file `conf.d/test.conf`: The following example fetches the configuration file `conf.d/test.conf`:
$ curl -k -s -u root:icinga https://localhost:5665/v1/config/files/example-cmdb/example.localdomain-1441625839-0/conf.d/test.conf $ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/files/example-cmdb/example.localdomain-1441625839-0/conf.d/test.conf'
object Host "cfg-mgmt" { chec_command = "dummy" }
object Host "cmdb-host" { chec_command = "dummy" }
You can fetch a [list of existing files](9-icinga2-api.md#icinga2-api-config-management-list-config-package-stage-files)
in a configuration stage and then specifically request their content.
### <a id="icinga2-api-config-management-config-package-stage-errors"></a> Configuration Package Stage Errors ### <a id="icinga2-api-config-management-config-package-stage-errors"></a> Configuration Package Stage Errors
Now that we don't have an active stage for `example-cmdb` yet seen [here](9-icinga2-api.md#icinga2-api-config-management-list-config-packages), Now that we don't have an active stage for `example-cmdb` yet seen [here](9-icinga2-api.md#icinga2-api-config-management-list-config-packages),
there must have been an error. there must have been an error.
Fetch the `startup.log` file and check the config validation errors: In order to check for validation errors you can fetch the `startup.log` file
by sending a `GET` request to the URL endpoint `/v1/config/files`. You must include
the package name, stage name and the `startup.log` in the URL path.
$ curl -k -s -u root:icinga https://localhost:5665/v1/config/files/example-cmdb/example.localdomain-1441133065-1/startup.log $ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/files/example-cmdb/example.localdomain-1441133065-1/startup.log'
... ...
critical/config: Error: Attribute 'chec_command' does not exist. critical/config: Error: Attribute 'chec_command' does not exist.
Location: Location:
/var/lib/icinga2/api/packages/example-cmdb/example.localdomain-1441133065-1/conf.d/test.conf(1): object Host "cfg-mgmt" { chec_command = "dummy" } /var/lib/icinga2/api/packages/example-cmdb/example.localdomain-1441133065-1/conf.d/test.conf(1): object Host "cmdb-host" { chec_command = "dummy" }
^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^
critical/config: 1 error critical/config: 1 error
The output is similar to the manual [configuration validation](8-cli-commands.md#config-validation). The output is similar to the manual [configuration validation](8-cli-commands.md#config-validation).
> **Note**
>
> The returned output is plain-text instead of JSON-encoded.
### <a id="icinga2-api-config-management-delete-config-stage"></a> Deleting Configuration Package Stage
You can send a `DELETE` request to the URL endpoint `/v1/config/stages`
in order to purge a configuration stage. You must include the package and
stage name inside the URL path.
The following example removes the failed configuration stage `example.localdomain-1441133065-1`
in the `example-cmdb` configuration package:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X DELETE \
'https://localhost:5665/v1/config/stages/example-cmdb/example.localdomain-1441133065-1' | python -m json.tool
{
"results": [
{
"code": 200.0,
"status": "Stage deleted."
}
]
}
### <a id="icinga2-api-config-management-delete-config-package"></a> Deleting Configuration Package
In order to completely purge a configuration package and its stages
you can send a `DELETE` request to the URL endpoint `/v1/config/packages`
with the package name in the URL path.
This example entirely deletes the configuration package `example-cmdb`:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X DELETE \
'https://localhost:5665/v1/config/packages/example-cmdb' | python -m json.tool
{
"results": [
{
"code": 200.0,
"package": "example-cmdb",
"status": "Deleted package."
}
]
}
## <a id="icinga2-api-types"></a> Types ## <a id="icinga2-api-types"></a> Types
You can retrieve the configuration object types by sending a `GET` request to URL You can retrieve the configuration object types by sending a `GET` request to URL