[DOCS] Added licensing APIs (elastic/x-pack-elasticsearch#4026)
Original commit: elastic/x-pack-elasticsearch@0e50cc0d64
This commit is contained in:
Lisa Cawley
GitHub
parent
2147d217df
commit
6e87d95f9b
|
|
@ -61,6 +61,9 @@ buildRestTests.expectedUnconvertedCandidates = [
|
|||
'en/watcher/trigger/schedule/weekly.asciidoc',
|
||||
'en/watcher/trigger/schedule/yearly.asciidoc',
|
||||
'en/watcher/troubleshooting.asciidoc',
|
||||
'en/rest-api/license/delete-license.asciidoc',
|
||||
'en/rest-api/license/start-trial.asciidoc',
|
||||
'en/rest-api/license/update-license.asciidoc',
|
||||
'en/ml/api-quickref.asciidoc',
|
||||
'en/rest-api/ml/delete-calendar-event.asciidoc',
|
||||
'en/rest-api/ml/delete-snapshot.asciidoc',
|
||||
|
|
@ -72,7 +75,7 @@ buildRestTests.expectedUnconvertedCandidates = [
|
|||
'en/rest-api/ml/get-record.asciidoc',
|
||||
'en/rest-api/ml/get-influencer.asciidoc',
|
||||
'en/rest-api/ml/get-snapshot.asciidoc',
|
||||
'en/rest-api/ml/post-data.asciidoc',
|
||||
'en/rest-api/ml/post-data.asciidoc',
|
||||
'en/rest-api/ml/preview-datafeed.asciidoc',
|
||||
'en/rest-api/ml/revert-snapshot.asciidoc',
|
||||
'en/rest-api/ml/update-snapshot.asciidoc',
|
||||
|
|
|
|||
|
|
@ -9,6 +9,7 @@ directly to configure and access {xpack} features.
|
|||
|
||||
* <<info-api, Info API>>
|
||||
* <<graph-explore-api, Graph Explore API>>
|
||||
* <<licensing-apis>>
|
||||
* <<ml-apis, Machine Learning APIs>>
|
||||
* <<security-api,Security APIs>>
|
||||
* <<watcher-api, Watcher APIs>>
|
||||
|
|
@ -19,9 +20,10 @@ directly to configure and access {xpack} features.
|
|||
|
||||
include::info.asciidoc[]
|
||||
include::graph/explore.asciidoc[]
|
||||
include::licensing.asciidoc[]
|
||||
include::migration.asciidoc[]
|
||||
include::ml-api.asciidoc[]
|
||||
include::rollup-api.asciidoc[]
|
||||
include::security.asciidoc[]
|
||||
include::watcher.asciidoc[]
|
||||
include::rollup-api.asciidoc[]
|
||||
include::migration.asciidoc[]
|
||||
include::defs.asciidoc[]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,43 @@
|
|||
[role="xpack"]
|
||||
[[delete-license]]
|
||||
=== Delete License API
|
||||
|
||||
This API enables you to delete licensing information.
|
||||
|
||||
[float]
|
||||
==== Request
|
||||
|
||||
`DELETE /_xpack/license`
|
||||
|
||||
[float]
|
||||
==== Description
|
||||
|
||||
When your license expires, {xpack} operates in a degraded mode. For more
|
||||
information, see {xpack-ref}/license-expiration.html[License Expiration].
|
||||
|
||||
[float]
|
||||
==== Authorization
|
||||
|
||||
You must have `manage` cluster privileges to use this API.
|
||||
For more information, see
|
||||
{xpack-ref}/security-privileges.html[Security Privileges].
|
||||
|
||||
[float]
|
||||
==== Examples
|
||||
|
||||
The following example queries the info API:
|
||||
|
||||
[source,js]
|
||||
------------------------------------------------------------
|
||||
DELETE _xpack/license
|
||||
------------------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[skip:license testing issues]
|
||||
|
||||
When the license is successfully deleted, the API returns the following response:
|
||||
[source,js]
|
||||
------------------------------------------------------------
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,75 @@
|
|||
[role="xpack"]
|
||||
[[get-license]]
|
||||
=== Get License API
|
||||
|
||||
This API enables you to retrieve licensing information.
|
||||
|
||||
[float]
|
||||
==== Request
|
||||
|
||||
`GET /_xpack/license`
|
||||
|
||||
[float]
|
||||
==== Description
|
||||
|
||||
This API returns information about the type of license, when it was issued, and
|
||||
when it expires, for example.
|
||||
|
||||
For more information about the different types of licenses, see
|
||||
https://www.elastic.co/subscriptions.
|
||||
|
||||
|
||||
[float]
|
||||
==== Query Parameters
|
||||
|
||||
`local`::
|
||||
(boolean) Specifies whether to retrieve local information. The default value
|
||||
is `false`, which means the information is retrieved from the master node.
|
||||
|
||||
|
||||
[float]
|
||||
==== Authorization
|
||||
|
||||
You must have `monitor` cluster privileges to use this API.
|
||||
For more information, see
|
||||
{xpack-ref}/security-privileges.html[Security Privileges].
|
||||
|
||||
|
||||
[float]
|
||||
==== Examples
|
||||
|
||||
The following example provides information about a basic license:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
GET _xpack/license
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"license" : {
|
||||
"status" : "active",
|
||||
"uid" : "cbff45e7-c553-41f7-ae4f-9205eabd80xx",
|
||||
"type" : "trial",
|
||||
"issue_date" : "2018-02-22T23:12:05.550Z",
|
||||
"issue_date_in_millis" : 1519341125550,
|
||||
"expiry_date" : "2018-03-24T23:12:05.550Z",
|
||||
"expiry_date_in_millis" : 1521933125550,
|
||||
"max_nodes" : 1000,
|
||||
"issued_to" : "test",
|
||||
"issuer" : "elasticsearch",
|
||||
"start_date_in_millis" : -1
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// TESTRESPONSE[s/"cbff45e7-c553-41f7-ae4f-9205eabd80xx"/$body.license.uid/]
|
||||
// TESTRESPONSE[s/"trial"/$body.license.type/]
|
||||
// TESTRESPONSE[s/"2018-02-22T23:12:05.550Z"/$body.license.issue_date/]
|
||||
// TESTRESPONSE[s/1519341125550/$body.license.issue_date_in_millis/]
|
||||
// TESTRESPONSE[s/"2018-03-24T23:12:05.550Z"/$body.license.expiry_date/]
|
||||
// TESTRESPONSE[s/1521933125550/$body.license.expiry_date_in_millis/]
|
||||
// TESTRESPONSE[s/1000/$body.license.max_nodes/]
|
||||
// TESTRESPONSE[s/"test"/$body.license.issued_to/]
|
||||
// TESTRESPONSE[s/"elasticsearch"/$body.license.issuer/]
|
||||
|
|
@ -0,0 +1,52 @@
|
|||
[role="xpack"]
|
||||
[[get-trial-status]]
|
||||
=== Get Trial Status API
|
||||
|
||||
This API enables you to check the status of your trial license.
|
||||
|
||||
[float]
|
||||
==== Request
|
||||
|
||||
`GET _xpack/license/trial_status`
|
||||
|
||||
[float]
|
||||
==== Description
|
||||
|
||||
If a license is not already registered for the cluster, one is generated when
|
||||
the nodes start. By default, this is a 30-day trial license that gives access
|
||||
to all {xpack} features.
|
||||
|
||||
NOTE: You are allowed to initiate a trial license only if your cluster has not
|
||||
already activated a trial license for the current major X-Pack version. For
|
||||
example, if you have already activated a trial for v6.0, you cannot start a new
|
||||
trial until v7.0. You can, however, contact `info@elastic.co` to request an
|
||||
extended trial license.
|
||||
|
||||
For more information about the different types of licenses, see
|
||||
https://www.elastic.co/subscriptions.
|
||||
|
||||
==== Authorization
|
||||
|
||||
You must have `monitor` cluster privileges to use this API.
|
||||
For more information, see
|
||||
{xpack-ref}/security-privileges.html[Security Privileges].
|
||||
|
||||
[float]
|
||||
==== Examples
|
||||
|
||||
The following example checks whether you are eligible to start a trial:
|
||||
|
||||
[source,js]
|
||||
------------------------------------------------------------
|
||||
GET _xpack/license/trial_status
|
||||
------------------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
Example response:
|
||||
[source,js]
|
||||
------------------------------------------------------------
|
||||
{
|
||||
"eligible_to_start_trial": true
|
||||
}
|
||||
------------------------------------------------------------
|
||||
// TESTRESPONSE[s/"eligible_to_start_trial": true/"eligible_to_start_trial": $body.eligible_to_start_trial/]
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
[role="xpack"]
|
||||
[[start-trial]]
|
||||
=== Start Trial API
|
||||
|
||||
This API starts a 30-day trial license.
|
||||
|
||||
[float]
|
||||
==== Request
|
||||
|
||||
`POST _xpack/license/start_trial`
|
||||
|
||||
[float]
|
||||
==== Description
|
||||
|
||||
The `start trial` API enables you to upgrade from a basic license to a 30-day
|
||||
trial license, which gives access to all {xpack} features.
|
||||
|
||||
NOTE: You are allowed to initiate a trial license only if your cluster has not
|
||||
already activated a trial license for the current major X-Pack version. For
|
||||
example, if you have already activated a trial for v6.0, you cannot start a new
|
||||
trial until v7.0. You can, however, contact `info@elastic.co` to request an
|
||||
extended trial license.
|
||||
|
||||
To check the status of your trial license, use the following API:
|
||||
<<get-trial-status>>.
|
||||
|
||||
For more information about the different types of licenses, see
|
||||
https://www.elastic.co/subscriptions.
|
||||
|
||||
==== Authorization
|
||||
|
||||
You must have `manage` cluster privileges to use this API.
|
||||
For more information, see
|
||||
{xpack-ref}/security-privileges.html[Security Privileges].
|
||||
|
||||
[float]
|
||||
==== Examples
|
||||
|
||||
The following example checks whether you are eligible to start a trial:
|
||||
|
||||
[source,js]
|
||||
------------------------------------------------------------
|
||||
POST _xpack/license/start_trial
|
||||
------------------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[skip:license testing issues]
|
||||
|
||||
Example response:
|
||||
[source,js]
|
||||
------------------------------------------------------------
|
||||
{
|
||||
"trial_was_started": true
|
||||
}
|
||||
------------------------------------------------------------
|
||||
|
|
@ -0,0 +1,160 @@
|
|||
[role="xpack"]
|
||||
[[update-license]]
|
||||
=== Update License API
|
||||
|
||||
This API enables you to update your license.
|
||||
|
||||
[float]
|
||||
==== Request
|
||||
|
||||
`PUT _xpack/license`
|
||||
|
||||
[float]
|
||||
==== Description
|
||||
|
||||
You can update your license at runtime without shutting down your nodes.
|
||||
License updates take effect immediately. If the license you are installing does
|
||||
not support all of the features that were available with your previous license,
|
||||
however, you are notified in the response. You must then re-submit the API
|
||||
request with the `acknowledge` parameter set to `true`.
|
||||
|
||||
For more information about the different types of licenses, see
|
||||
https://www.elastic.co/subscriptions.
|
||||
|
||||
[float]
|
||||
==== Query Parameters
|
||||
|
||||
`acknowledge`::
|
||||
(boolean) Specifies whether you acknowledge the license changes. The default
|
||||
value is `false`.
|
||||
|
||||
[float]
|
||||
==== Request Body
|
||||
|
||||
`licenses`::
|
||||
(array) A sequence of one or more JSON documents containing the license
|
||||
information.
|
||||
|
||||
|
||||
[float]
|
||||
==== Authorization
|
||||
|
||||
If {security} is enabled, you need `manage` cluster privileges to install the
|
||||
license.
|
||||
|
||||
If {security} is enabled and you are installing a gold or platinum license, you
|
||||
must enable TLS on the transport networking layer before you install the license.
|
||||
See <<configuring-tls>>.
|
||||
|
||||
[float]
|
||||
==== Examples
|
||||
|
||||
The following example updates to a basic license:
|
||||
|
||||
[source,js]
|
||||
------------------------------------------------------------
|
||||
POST _xpack/license
|
||||
{
|
||||
"licenses": [
|
||||
{
|
||||
"uid":"893361dc-9749-4997-93cb-802e3d7fa4xx",
|
||||
"type":"basic",
|
||||
"issue_date_in_millis":1411948800000,
|
||||
"expiry_date_in_millis":1914278399999,
|
||||
"max_nodes":1,
|
||||
"issued_to":"issuedTo",
|
||||
"issuer":"issuer",
|
||||
"signature":"xx"
|
||||
}
|
||||
]
|
||||
}
|
||||
------------------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[skip:license testing issues]
|
||||
|
||||
NOTE: These values are invalid; you must substitute the appropriate content
|
||||
from your license file.
|
||||
|
||||
You can alternatively use a `curl` command, for example:
|
||||
|
||||
[source,js]
|
||||
[source,shell]
|
||||
------------------------------------------------------------
|
||||
curl -XPUT -u <user> 'http://<host>:<port>/_xpack/license' -H "Content-Type: application/json" -d @license.json
|
||||
------------------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
On Windows machine, use the following command:
|
||||
|
||||
[source,shell]
|
||||
------------------------------------------------------------
|
||||
gc .\license.json | Invoke-WebRequest -uri http://<host>:<port>/_xpack/license -Credential elastic -Method Put -ContentType "application/json"
|
||||
------------------------------------------------------------
|
||||
|
||||
In these examples,
|
||||
|
||||
* `<user>` is a user ID with the appropriate authority.
|
||||
* `<host>` is the hostname of the {es} node (`localhost` if executing
|
||||
locally)
|
||||
* `<port>` is the http port (defaults to `9200`)
|
||||
* `license.json` is the license JSON file
|
||||
|
||||
NOTE: If your {es} node has SSL enabled on the HTTP interface, you must
|
||||
start your URL with `https://`
|
||||
|
||||
If you previously had a license with more features than the basic license, you
|
||||
receive the following response:
|
||||
|
||||
[source,js]
|
||||
------------------------------------------------------------
|
||||
{
|
||||
"acknowledged": false,
|
||||
"license_status": "valid",
|
||||
"acknowledge": {
|
||||
"message": """This license update requires acknowledgement. To acknowledge the license, please read the following messages and update the license again, this time with the "acknowledge=true" parameter:""",
|
||||
"watcher": [
|
||||
"Watcher will be disabled"
|
||||
],
|
||||
"logstash": [
|
||||
"Logstash will no longer poll for centrally-managed pipelines"
|
||||
],
|
||||
"security": [
|
||||
"The following X-Pack security functionality will be disabled: ..." ]
|
||||
}
|
||||
}
|
||||
------------------------------------------------------------
|
||||
|
||||
To complete the update, you must re-submit the API request and set the
|
||||
`acknowledge` parameter to `true`. For example:
|
||||
|
||||
[source,js]
|
||||
------------------------------------------------------------
|
||||
POST _xpack/license?acknowledge=true
|
||||
{
|
||||
"licenses": [
|
||||
{
|
||||
"uid":"893361dc-9749-4997-93cb-802e3d7fa4xx",
|
||||
"type":"basic",
|
||||
"issue_date_in_millis":1411948800000,
|
||||
"expiry_date_in_millis":1914278399999,
|
||||
"max_nodes":1,
|
||||
"issued_to":"issuedTo",
|
||||
"issuer":"issuer",
|
||||
"signature":"xx"
|
||||
}
|
||||
]
|
||||
}
|
||||
------------------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[skip:license testing issues]
|
||||
|
||||
Alternatively:
|
||||
|
||||
[source,sh]
|
||||
------------------------------------------------------------
|
||||
curl -XPUT -u elastic 'http://<host>:<port>/_xpack/license?acknowledge=true' -H "Content-Type: application/json" -d @license.json
|
||||
------------------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
For more information about the features that are disabled when you downgrade
|
||||
your license, see {xpack-ref}/license-expiration.html[License Expiration].
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
[role="xpack"]
|
||||
[[licensing-apis]]
|
||||
== Licensing APIs
|
||||
|
||||
You can use the following APIs to manage your licenses:
|
||||
|
||||
* <<delete-license>>
|
||||
* <<get-license>>
|
||||
* <<get-trial-status>>
|
||||
* <<start-trial>>
|
||||
* <<update-license>>
|
||||
|
||||
|
||||
include::license/delete-license.asciidoc[]
|
||||
include::license/get-license.asciidoc[]
|
||||
include::license/get-trial-status.asciidoc[]
|
||||
include::license/start-trial.asciidoc[]
|
||||
include::license/update-license.asciidoc[]
|
||||
|
|
@ -1,13 +1,13 @@
|
|||
[role="xpack"]
|
||||
[[migration-api-deprecation]]
|
||||
== Deprecation Info APIs
|
||||
=== Deprecation Info APIs
|
||||
|
||||
The deprecation API is to be used to retrieve information about different
|
||||
cluster, node, and index level settings that use deprecated features that will
|
||||
be removed or changed in the next major version.
|
||||
|
||||
[float]
|
||||
=== Request
|
||||
==== Request
|
||||
|
||||
`GET /_xpack/migration/deprecations` +
|
||||
|
||||
|
|
@ -16,7 +16,7 @@ be removed or changed in the next major version.
|
|||
//=== Description
|
||||
|
||||
[float]
|
||||
=== Path Parameters
|
||||
==== Path Parameters
|
||||
|
||||
`index_name`::
|
||||
(string) Identifier for the index. It can be an index name or a wildcard
|
||||
|
|
@ -28,7 +28,7 @@ be removed or changed in the next major version.
|
|||
//=== Authorization
|
||||
|
||||
[float]
|
||||
=== Examples
|
||||
==== Examples
|
||||
|
||||
To see the list of offenders in your cluster, submit a GET request to the
|
||||
`_xpack/migration/deprecations` endpoint:
|
||||
|
|
|
|||
Loading…
Reference in New Issue