From d017df52dcdccdfd0e5b1cae989b41b281134001 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Tue, 4 Feb 2020 12:55:34 -0800 Subject: [PATCH] [docs] Documentation updates from APM (#15835) --- libbeat/docs/command-reference.asciidoc | 114 ++++++++++++++++++ libbeat/docs/security/api-keys.asciidoc | 2 +- libbeat/docs/shared-securing-beat.asciidoc | 2 +- libbeat/docs/shared-systemd.asciidoc | 2 +- libbeat/docs/template-config.asciidoc | 3 - .../elasticsearch/docs/elasticsearch.asciidoc | 15 +++ 6 files changed, 132 insertions(+), 6 deletions(-) diff --git a/libbeat/docs/command-reference.asciidoc b/libbeat/docs/command-reference.asciidoc index 41d4e4e39ec..2a3f114f4e8 100644 --- a/libbeat/docs/command-reference.asciidoc +++ b/libbeat/docs/command-reference.asciidoc @@ -17,6 +17,8 @@ :deploy-command-short-desc: Deploys the specified function to your serverless environment +:apikey-command-short-desc: Manage API Keys for communication between APM agents and server. + ifndef::serverless[] ifndef::no_dashboards[] :export-command-short-desc: Exports the configuration, index template, ILM policy, or a dashboard to stdout @@ -98,6 +100,9 @@ more information, see https://www.elastic.co/subscriptions and ifeval::["{beatname_lc}"=="functionbeat"] |<> | {deploy-command-short-desc}. endif::[] +ifdef::apm-server[] +|<> |{apikey-command-short-desc}. +endif::[] |<> |{export-command-short-desc}. |<> |{help-command-short-desc}. ifndef::serverless[] @@ -123,6 +128,115 @@ endif::[] Also see <>. +ifdef::apm-server[] +[[apikey-command]] +==== `apikey` command + +experimental::[] + +Communication between APM agents and APM Server now supports sending an +<>. +APM Server provides an `apikey` command that can create, verify, invalidate, +and show information about API Keys for agent/server communication. +Most operations require the `manage_api_key` cluster privilege, +and you must ensure that `apm-server.api_key` or `output.elasticsearch` are configured appropriately. + +*SYNOPSIS* + +["source","sh",subs="attributes"] +---- +{beatname_lc} apikey SUBCOMMAND [FLAGS] +---- + +*SUBCOMMANDS* + +// tag::apikey-subcommands[] +*`create`*:: +Create an API Key with the specified privilege(s). No required flags. ++ +The user requesting to create an API Key needs to have APM privileges used by the APM Server. +A superuser, by default, has these privileges. For other users, +you can create them. Create a role that is then assigned to the user: ++ +["source","sh",subs="attributes"] +---- +PUT /_security/role/apm-privileges { + "applications": [{ + "application": "apm", + "privileges": ["sourcemap:write", "event:write", "config_agent:read"], + "resources": ["*"] + }] +} +---- + +*`info`*:: +Query API Key(s). `--id` or `--name` required. + +*`invalidate`*:: +Invalidate API Key(s). `--id` or `--name` required. + +*`verify`*:: +Check if a credentials string has the given privilege(s). + `--credentials` required. +// end::apikey-subcommands[] + +*FLAGS* + +*`--agent-config`*:: +Required for agents to read configuration remotely. Valid with the `create` and `verify` subcommands. +When used with `create`, gives the `config_agent:read` privilege to the created key. +When used with `verify`, asks for the `config_agent:read` privilege. + +*`--credentials CREDS`*:: +Required for the `verify` subcommand. Specifies the credentials for which to to check privileges. +Credentials are the base64 encoded representation of the API key's `id:name`. + +*`--expiration TIME`*:: +When used with `create`, specifies the expiration for the key, e.g., "1d" (default never). + +*`--id ID`*:: +ID of the API key. Valid with the `info` and `invalidate` subcommands. +When used with `info`, queries the specified ID. +When used with `invalidate`, deletes the specified ID. + +*`--ingest`*:: +Required for ingesting events. Valid with the `create` and `verify` subcommands. +When used with `create`, gives the `event:write` privilege to the created key. +When used with `verify`, asks for the `event:write` privilege. + +*`--json`*:: +Prints the output of the command as JSON. +Valid with all `apikey` subcommands. + +*`--name NAME`*:: +Name of the API key(s). Valid with the `create`, `info`, and `invalidate` subcommands. +When used with `create`, specifies the name of the API key to be created (default: "apm-key"). +When used with `info`, specifies the API key to query (multiple matches are possible). +When used with `invalidate`, specifies the API key to delete (multiple matches are possible). + +*`--sourcemap`*:: +Required for uploading sourcemaps. Valid with the `create` and `verify` subcommands. +When used with `create`, gives the `sourcemap:write` privilege to the created key. +When used with `verify`, asks for the `sourcemap:write` privilege. + +*`--valid-only`*:: +When used with `info`, only returns valid API Keys (not expired or invalidated). + +{global-flags} + +*EXAMPLES* + +["source","sh",subs="attributes"] +----- +{beatname_lc} apikey create --ingest --agent-config --name example-001 +{beatname_lc} apikey info --name example-001 --valid-only +{beatname_lc} apikey invalidate --name example-001 +----- + +For more information, see <>. + +endif::[] + ifeval::["{beatname_lc}"=="functionbeat"] [[deploy-command]] ==== `deploy` command diff --git a/libbeat/docs/security/api-keys.asciidoc b/libbeat/docs/security/api-keys.asciidoc index aeb143c5065..aef276417a4 100644 --- a/libbeat/docs/security/api-keys.asciidoc +++ b/libbeat/docs/security/api-keys.asciidoc @@ -17,7 +17,7 @@ See the {es} API key documentation for more information: information to {es}. If you are sending both to the same cluster, you can use the same API key. For different clusters, you need to use an API key per cluster. -NOTE: For security reasons, we recommend using a unique API key per Beat instance. +NOTE: For security reasons, we recommend using a unique API key per {beatname_uc} instance. You can create as many API keys per user as necessary. [[beats-api-key-publish]] diff --git a/libbeat/docs/shared-securing-beat.asciidoc b/libbeat/docs/shared-securing-beat.asciidoc index 2cf2f7ee3fd..531ca18fd12 100644 --- a/libbeat/docs/shared-securing-beat.asciidoc +++ b/libbeat/docs/shared-securing-beat.asciidoc @@ -27,7 +27,7 @@ endif::[] -- ifdef::apm-server[] -include::../secure-communication-agents.asciidoc[] +include::{docdir}/secure-communication-agents.asciidoc[] endif::[] //sets block macro for https.asciidoc included in next section diff --git a/libbeat/docs/shared-systemd.asciidoc b/libbeat/docs/shared-systemd.asciidoc index 7f80a463edb..4f677858dfe 100644 --- a/libbeat/docs/shared-systemd.asciidoc +++ b/libbeat/docs/shared-systemd.asciidoc @@ -95,5 +95,5 @@ include drop-in unit files. If you need to add a drop-in manually, use +systemctl edit {beatname_lc}.service+. ifdef::apm-server[] -include::./../config-ownership.asciidoc[] +include::{docdir}/config-ownership.asciidoc[] endif::apm-server[] diff --git a/libbeat/docs/template-config.asciidoc b/libbeat/docs/template-config.asciidoc index 9889997cadc..69ddfe6745e 100644 --- a/libbeat/docs/template-config.asciidoc +++ b/libbeat/docs/template-config.asciidoc @@ -83,7 +83,6 @@ setup.template.settings: _source.enabled: false ---------------------------------------------------------------------- -ifeval::["{beatname_lc}"!="apm-server"] *`setup.template.append_fields`* experimental[]:: A list of fields to be added to the template and {kib} index pattern. This setting adds new fields. It does not overwrite or change existing fields. @@ -129,5 +128,3 @@ setup.template.json.name: "template-name NOTE: If the JSON template is used, the `fields.yml` is skipped for the template generation. - -endif::[] diff --git a/libbeat/outputs/elasticsearch/docs/elasticsearch.asciidoc b/libbeat/outputs/elasticsearch/docs/elasticsearch.asciidoc index 1296133c982..8528d29e9b8 100644 --- a/libbeat/outputs/elasticsearch/docs/elasticsearch.asciidoc +++ b/libbeat/outputs/elasticsearch/docs/elasticsearch.asciidoc @@ -31,6 +31,15 @@ output.elasticsearch: password: "{pwd}" ------------------------------------------------------------------------------ +To use an API key to connect to {es}, use `api_key`. + +["source","yaml",subs="attributes,callouts"] +------------------------------------------------------------------------------ +output.elasticsearch: + hosts: ["https://localhost:9200"] + api_key: "KnR6yE41RrSowb0kQ0HWoA" +------------------------------------------------------------------------------ + If the Elasticsearch nodes are defined by `IP:PORT`, then add `protocol: https` to the yaml file. ["source","yaml",subs="attributes,callouts"] @@ -118,6 +127,12 @@ is best used with load balancing mode enabled. Example: If you have 2 hosts and The default value is 1. +===== `api_key` + +Instead of using usernames and passwords, +you can use API keys to secure communication with {es}. +For more information, see <>. + ===== `username` The basic authentication username for connecting to Elasticsearch.