You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -516,7 +516,7 @@ You can customize your stack using profile settings, see [Elastic Package profil
516
516
517
517
There are different providers supported, that can be selected with the --provider flag.
518
518
- compose: Starts a local stack using Docker Compose. This is the default.
519
-
- environment: Prepares an existing stack to be used to test packages. Missing components are started locally using Docker Compose. Environment variables are used to configure the access to the existing Elasticsearch and Kibana instances.
519
+
- environment: Prepares an existing stack to be used to test packages. Missing components are started locally using Docker Compose. Environment variables are used to configure the access to the existing Elasticsearch and Kibana instances. You can learn more about this in [this document](./docs/howto/use_existing_stack.md).
520
520
- serverless: Uses Elastic Cloud to start a serverless project. Requires an Elastic Cloud API key.
521
521
522
522
### `elastic-package stack update`
@@ -700,7 +700,7 @@ There are available some environment variables that could be used to change some
700
700
-`ELASTIC_PACKAGE_ELASTICSEARCH_API_KEY`: API key to connect to elasticsearch and kibana. When set it takes precedence over username and password.
701
701
-`ELASTIC_PACKAGE_ELASTICSEARCH_USERNAME`: User name to connect to elasticsearch and kibana (e.g. elastic)
702
702
-`ELASTIC_PACKAGE_ELASTICSEARCH_PASSWORD`: Password of that user.
-`ELASTIC_PACKAGE_ELASTICSEARCH_CA_CERT`: Path to the CA certificate to connect to the Elastic stack services.
705
705
706
706
- To configure an external metricstore while running benchmarks (more info at [system benchmarking docs](https://github.com/elastic/elastic-package/blob/main/docs/howto/system_benchmarking.md#setting-up-an-external-metricstore) or [rally benchmarking docs](https://github.com/elastic/elastic-package/blob/main/docs/howto/rally_benchmarking.md#setting-up-an-external-metricstore)):
Copy file name to clipboardExpand all lines: cmd/stack.go
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -51,7 +51,7 @@ You can customize your stack using profile settings, see [Elastic Package profil
51
51
52
52
There are different providers supported, that can be selected with the --provider flag.
53
53
- compose: Starts a local stack using Docker Compose. This is the default.
54
-
- environment: Prepares an existing stack to be used to test packages. Missing components are started locally using Docker Compose. Environment variables are used to configure the access to the existing Elasticsearch and Kibana instances.
54
+
- environment: Prepares an existing stack to be used to test packages. Missing components are started locally using Docker Compose. Environment variables are used to configure the access to the existing Elasticsearch and Kibana instances. You can learn more about this in [this document](./docs/howto/use_existing_stack.md).
55
55
- serverless: Uses Elastic Cloud to start a serverless project. Requires an Elastic Cloud API key.`
56
56
57
57
conststackShellinitLongDescription=`Use this command to export to the current shell the configuration of the stack managed by elastic-package.
# HOWTO: Use `elastic-package` with an existing stack
2
+
3
+
4
+
## Introduction
5
+
6
+
`elastic-package` supports the use of environment variables to customize how it
7
+
interacts with the environment where it is running. Some of these variables can
8
+
be used to define the target Elastic Stack for many of its subcommands.
9
+
10
+
There are some commands that only need to reach Elasticsearch or Kibana, for
11
+
these commands you only need to configure the environment variables required to
12
+
configure these services. In other cases elastic-package needs to be able to
13
+
enroll agents, specially for system testing, for these cases you can use
14
+
the `environment` stack provider.
15
+
16
+
17
+
### Environment variables for existing stacks
18
+
19
+
Some `elastic-package` subcommands only need access to Elasticsearch or Kibana,
20
+
for them it is enough with setting some environment variables to define how to
21
+
reach them.
22
+
This is the case of subcommands such as `install`, `dump` or `export`, that use
23
+
the APIs to do their work, but don't need to manage Elastic Agents or a Fleet
24
+
Server.
25
+
26
+
Two environment variables are required to tell elastic-package about the target
27
+
Elasticsearch and Kibana hosts:
28
+
-`ELASTIC_PACKAGE_ELASTICSEARCH_HOST` for Elasticsearch.
29
+
-`ELASTIC_PACKAGE_KIBANA_HOST` for Kibana.
30
+
31
+
`elastic-package` can connect to services exposed through HTTPS or HTTP. If you
32
+
are using HTTPS with self-signed certificates you can set
33
+
`ELASTIC_PACKAGE_CA_CERT` to the path of the certificate of your CA.
34
+
35
+
If your stack requires authentication, you can use the following environment
36
+
variables:
37
+
-`ELASTIC_PACKAGE_ELASTICSEARCH_API_KEY` for authentication based on API keys.
38
+
-`ELASTIC_PACKAGE_ELASTICSEARCH_USERNAME` and
39
+
`ELASTIC_PACKAGE_ELASTICSEARCH_PASSWORD` for basic authentication.
40
+
41
+
You can read more about the available environment variables in the [README](https://github.com/elastic/elastic-package/blob/main/README.md#useful-environment-variables).
42
+
43
+
44
+
### The `environment` stack provider
45
+
46
+
Some `elastic-package` subcommands expect some Fleet configuration, a running
47
+
Fleet Server, and to be able to manage Elastic Agents. This is specially the
48
+
case of system tests and benchmarks.
49
+
For these cases you can use the `environment` stack provider, that takes care of
50
+
filling these gaps for a running stack.
51
+
You can also use this provider to setup Fleet, with a running agent, for any
52
+
existing stack.
53
+
54
+
The `environment` provider runs Elastic Agents and other services as local
55
+
containers using Docker Compose. These services run on their own networks, so
56
+
they cannot access Elasticsearch and Kibana listening only on `localhost`.
57
+
If you want to use `elastic-package` with a stack running natively on localhost,
58
+
you will need to configure it to listen in all interfaces (`0.0.0.0`).
59
+
60
+
:warning: The `environment` provider modifies the Fleet configuration of the
61
+
target stack. Avoid using it in environments that you use for other purpouses,
62
+
specially in production environments. :warning:
63
+
64
+
To use the `environment` provider with an existing stack, setup the environment
65
+
variables as described in the previous section, and then run:
66
+
```sh
67
+
elastic-package stack up -v -d --provider environment
68
+
```
69
+
70
+
After this command finishes succesfully, your environment will be ready to use
71
+
with Fleet and it will have an enrolled Elastic Agent. `elastic-package` will be
72
+
configured to run any of its commands with it.
73
+
74
+
To clean up everything, run:
75
+
```sh
76
+
elastic-package stack down
77
+
```
78
+
79
+
You can have multiple stacks configured, with different providers, if you use
80
+
profiles. You can read more about them in the [README](https://github.com/elastic/elastic-package/blob/main/README.md#elastic-package-profiles-1).
81
+
82
+
83
+
### Example: Using elastic-package with Kibana development environment
84
+
85
+
One of the use cases of the environment provider is to be able to use
86
+
`elastic-package` with other development environments, as could be the Kibana
87
+
development environment.
88
+
89
+
Once you have a working [Kibana development environment](https://github.com/elastic/kibana/blob/main/CONTRIBUTING.md),
90
+
you can follow the instructions described in this document.
91
+
92
+
First you need to ensure that Elasticsearch and Kibana are listening on all
93
+
interfaces, so containers can connect:
94
+
```sh
95
+
yarn es snapshot --license trial -E network.host=0.0.0.0 -E discovery.type=single-node
96
+
yarn start --host 0.0.0.0
97
+
```
98
+
99
+
Take note of the address logged when starting kibana, on this document we are
100
+
assuming that it is `http://localhost:5601/xyz`.
101
+
102
+
Then configure the required environment variables:
0 commit comments