|
1 | 1 | [](https://fleet-ci.elastic.co/job/Ingest-manager/job/fleet-server/job/main/)
|
2 | 2 |
|
3 |
| -# Fleet Server implementation |
| 3 | +# Fleet Server |
4 | 4 |
|
5 |
| -## Development |
6 |
| - |
7 |
| -fleet-server is under development. The following are notes to help developers onboarding to the project to quickly get running. These notes might change at any time. |
| 5 | +Fleet server is the control server to manage a fleet of [elastic-agents](https://github.com/elastic/elastic-agent). |
8 | 6 |
|
9 |
| -## Setup for fleet-server development |
| 7 | +For production deployments the fleet-server is supervised and bootstrapped by an elastic-agent. |
10 | 8 |
|
11 |
| -### ES and Kinaba from SNAPSHOTS API |
| 9 | +To assist with development the fleet-server may run in a stand-alone mode. |
12 | 10 |
|
13 |
| -Download them from the snapshots API: |
14 |
| -Edit the version and OS/arch to suit your system, or [check the API](https://artifacts-api.elastic.co/v1/search/8.4-SNAPSHOT) (change the version if needed) if the ones below does not suit you. |
15 |
| - - 8.4.0-SNAPSHOT-linux-x86_64.tar.gz |
16 |
| - - 8.4.0-SNAPSHOT-darwin-aarch64.tar.gz |
17 |
| - - 8.4.0-SNAPSHOT-windows-x86_64.zip |
| 11 | +## Compatibility and upgrades |
18 | 12 |
|
19 |
| -TODO: parse the JSON to get the URL |
20 |
| -```shell |
21 |
| -wget https://snapshots.elastic.co/8.4.0-64eb2b35/downloads/elasticsearch/elasticsearch-8.4.0-SNAPSHOT-linux-x86_64.tar.gz |
22 |
| -wget https://snapshots.elastic.co/8.4.0-64eb2b35/downloads/kibana/kibana-8.4.0-SNAPSHOT-linux-x86_64.tar.gz |
| 13 | +Fleet-server communicates with Elasticsearch. Elasticsearch must be on the same version or newer. |
| 14 | +Fleet server is always on the exact same version as the Elastic Agent running fleet-server. |
| 15 | +Any Elastic Agent enrolling into a fleet-server must be the same version or older. |
| 16 | +For Kibana it is assumed it is on the same version as Elasticsearch. With this the compatibility looks as following: |
23 | 17 | ```
|
24 |
| - |
25 |
| -Follow the instructions for [ElasticSearch](https://www.elastic.co/downloads/elasticsearch) and [Kibana](https://www.elastic.co/downloads/kibana) |
26 |
| - |
27 |
| -### fleet-server+agent on a Vagrant VM |
28 |
| - |
29 |
| -The Vagrant machine assumes the `elastic-agent`, `beats` and `fleet-server` repos are in the same folder. |
30 |
| -Thus, it mounts `../` to `/vagrant` on the Vagrant machine. The vagrant machine IP address is `192.168.56.43`. |
31 |
| -Use `https://192.168.56.43:8220` as fleet-server host. |
32 |
| - |
33 |
| -### Grab or build the Elastic-Agent |
34 |
| - |
35 |
| -For detailed instructions, check the [Elastic-Agent](https://github.com/elastic/elastic-agent) repo. |
36 |
| -```shell |
37 |
| -cd YOUR_ELASTIC_AGENT_FOLDER |
38 |
| -SNAPSHOT=true EXTERNAL=true PLATFORMS="linux/amd64" PACKAGES="tar.gz" mage -v dev:package # adjust PLATFORMS and PACKAGES to your system and needs. |
| 18 | +Elastic Agent <= Elastic Agent with fleet-server <= Elasticsearch / Kibana |
39 | 19 | ```
|
40 | 20 |
|
41 |
| -### Build and Package |
| 21 | +There might be differences on the bugfix version. |
42 | 22 |
|
43 |
| -Change `release-linux/amd64` to `release-YOUR_OS/platform`. Run `make list-platforms` to check |
44 |
| -out the possible values. |
| 23 | +For upgrades Elasticsearch/Kibana must be upgraded first, then the Elastic Agent with fleet-server followed by any other Elastic Agents. |
45 | 24 |
|
46 |
| -The `DEV=true` will allow the binary to be debugged ~~with a debugger~~. |
| 25 | +## MacOSX Version |
47 | 26 |
|
48 |
| -```shell |
49 |
| -DEV=true SNAPSHOT=true make release-linux/amd64 |
| 27 | +The [golang-crossbuild](https://github.com/elastic/golang-crossbuild) produces images used for testing/building. |
| 28 | +The `golang-crossbuild:1.16.X-darwin-debian10` images expects the minimum MacOSX version to be 10.14+. |
50 | 29 |
|
51 |
| -vagrant up |
52 |
| -vagrant ssh |
53 |
| -``` |
| 30 | +## Development |
54 | 31 |
|
55 |
| -For the Elastic-Agent to use your build of the fleet-server, unpack the elastic agent and add your fleet-server tar.gz and sha512 to |
56 |
| -`elastic-agent-8.Y.Z-SNAPSHOT-OS-ARCH/data/elastic-agent-*/downloads/`. |
| 32 | +The following are notes to help developers onboarding to the project to quickly get running. These notes might change at any time. |
57 | 33 |
|
58 |
| -Then go to `Kibana > Managment > Fleet` and follow the instructions there. |
| 34 | +### Development build |
59 | 35 |
|
60 |
| -#### tl;dr/example: |
| 36 | +To compile the fleet-server in development mode set the env var `DEV=true`. |
| 37 | +When compiled in development mode the fleet-server will support debugging and stand-alone execution. |
| 38 | +i.e.: |
61 | 39 | ```shell
|
62 |
| -cp /vagrant/elastic-agent/build/distributions/elastic-agent-8.4.0-SNAPSHOT-linux-x86_64.tar.gz* ./ |
63 |
| -tar xzvf elastic-agent-8.4.0-SNAPSHOT-linux-x86_64.tar.gz |
64 |
| -cd elastic-agent-8.4.0-SNAPSHOT-linux-x86_64 |
65 |
| -cp /vagrant/fleet-server/build/distributions/fleet-server-8.4.0-SNAPSHOT-linux-x86_64.tar.gz* ./data/elastic-agent-494b79/downloads/ |
66 |
| -./elastic-agent install ... |
| 40 | +SNAPSHOT=true DEV=true make release-darwin/amd64 |
| 41 | +GOOS=darwin GOARCH=amd64 go build -tags="dev" -gcflags="all=-N -l" -ldflags="-X main.Version=8.7.0 -X main.Commit=31668e0 -X main.BuildTime=2022-12-23T20:06:20Z" -buildmode=pie -o build/binaries/fleet-server-8.7.0-darwin-x86_64/fleet-server . |
67 | 42 | ```
|
68 | 43 |
|
69 |
| -## Setup for Elastic-Agent development |
| 44 | +Change `release-darwin/amd64` to `release-YOUR_OS/platform`. |
| 45 | +Run `make list-platforms` to check out the possible values. |
70 | 46 |
|
71 |
| -### From source |
72 |
| -To run and test fleet-server, a recent version of Elastic Agent and Kibana are needed. In the following Elastic Agent and Kibana are built from source. The fleet-server itself is not built from source but pulled from the latest snapshot build. It would be possible to also pull Elastic Agent or Kibana from the latest snapshot but the assumption that is made here that whoever is testing this, is likely developing either Elastic Agent or on the Kibana side. |
| 47 | +The `SNAPSHOT` flag sets the snapshot version flag. |
73 | 48 |
|
| 49 | +### Running a development build |
74 | 50 |
|
75 |
| -### Kibana setup |
| 51 | +#### ES and Kibana from SNAPSHOTS API on host |
76 | 52 |
|
77 |
| -The source code of Kibana must be checked out. After checkout, the following command must be run: |
| 53 | +Download SNAPSHOT builds for Elasticsearch and Kibana from the snapshots API: |
| 54 | +Edit the version and OS/arch to suit your system, or [check the API](https://artifacts-api.elastic.co/v1/search/8.7-SNAPSHOT) (change the version if needed) if the ones below does not suit you. |
| 55 | + - 8.7.0-SNAPSHOT-linux-x86_64.tar.gz |
| 56 | + - 8.7.0-SNAPSHOT-darwin-aarch64.tar.gz |
| 57 | + - 8.7.0-SNAPSHOT-windows-x86_64.zip |
78 | 58 |
|
| 59 | +TODO: parse the JSON to get the URL |
| 60 | +```shell |
| 61 | +wget https://snapshots.elastic.co/8.7.0-19f30181/downloads/elasticsearch/elasticsearch-8.7.0-SNAPSHOT-linux-x86_64.tar.gz |
| 62 | +wget https://snapshots.elastic.co/8.7.0-19f30181/downloads/kibana/kibana-8.7.0-SNAPSHOT-linux-x86_64.tar.gz |
79 | 63 | ```
|
80 |
| -yarn kbn bootstrap |
81 |
| -``` |
82 |
| - |
83 |
| -This will take a while the first time it is run. An error might be return in case not a valid node version is installed. Use nvm to install the correct version. |
84 | 64 |
|
85 |
| -Now the following two commands must be run in parallel: |
86 |
| - |
87 |
| -``` |
88 |
| -# Start ES |
89 |
| -yarn es snapshot -E xpack.security.authc.api_key.enabled=true |
| 65 | +Generally you will need to unarchive and run the binaries: |
90 | 66 |
|
91 |
| -# Start KB |
92 |
| -yarn start --no-base-path |
| 67 | +```shell |
| 68 | +tar -xzf elasticsearch-8.7.0-SNAPSHOT-linux-x86_64.tar.gz |
| 69 | +cd elasticsearch-8.7.0-SNAPSHOT |
| 70 | +./bin/elasticsearch |
93 | 71 | ```
|
94 | 72 |
|
95 |
| -As soon as all is running, go to `http://localhost:5601`, enter `elastic/changeme` as credential and navigate to Fleet. Trigger the Fleet setup. As soon as this is completed, copy the `policy id` and `enrollment token` for the fleet-server policy. The policy id can be copied from the URL, the enrollment token can be found in the Enrollment Token list. |
96 |
| - |
97 |
| -NOTE: This step can be skipped if the full command below for the Elastic Agent is used. |
| 73 | +The elasticsearch output will output the `elastic` user's password and a Kibana configuration string. |
98 | 74 |
|
99 |
| -Now Kibana is running and ready. The next step is to setup Elastic Agent. |
| 75 | +```shell |
| 76 | +tar -xzf kibana-8.7.0-SNAPSHOT-linux-x86_64.tar.gz |
| 77 | +cd kibana-8.7.0-SNAPSHOT |
| 78 | +./bin/kibana |
| 79 | +``` |
100 | 80 |
|
101 |
| -## Elastic-Agent |
| 81 | +The kibana output will show a URL that will need to be visted in order to configure Kibana with the string elasticsearch provides. |
102 | 82 |
|
103 |
| -To build the Elastic Agent from source, check out the [elastic-agent repository](https://github.com/elastic/elastic-agent), then run the following command: |
| 83 | +More instructions for setup can be found in the [Elastic Stack Installation Guide](https://www.elastic.co/guide/en/elastic-stack/current/installing-elastic-stack.html). |
104 | 84 |
|
105 |
| -``` |
106 |
| -SNAPSHOT=true DEV=true PLATFORMS=linux|darwin|windows mage package |
107 |
| -``` |
| 85 | +#### fleet-server stand alone |
108 | 86 |
|
109 |
| -The above assumes you are running on OS X. Set `PLATFORMS` to the one in you are running on. This speeds up packaging as it only builds it for your platform. As soon as this is completed (it might take a while for the first time) navigate to `build/distributions` and unpackage the `.tar.gz`. Change working directory to the elastic-agent directory and start the Elastic Agent: |
| 87 | +Access the Fleet UI on Kibana and generate a fleet-server policy. |
| 88 | +Set the following env vars with the information from Kibana: |
| 89 | +- `ELASTICSEARCH_CA_TRUSTED_FINGERPRINT` |
| 90 | +- `ELASTICSEARCH_SERVICE_TOKEN` |
| 91 | +- `FLEET_SERVER_POLICY_ID` |
110 | 92 |
|
111 |
| -``` |
112 |
| -KIBANA_HOST=http://localhost:5601 KIBANA_USERNAME=elastic KIBANA_PASSWORD=changeme ELASTICSEARCH_HOST=http://localhost:9200 ELASTICSEARCH_USERNAME=elastic ELASTICSEARCH_PASSWORD=changeme KIBANA_FLEET_SETUP=1 FLEET_SERVER_ENABLE=1 sudo ./elastic-agent container |
| 93 | +Create a self-signed TLS CA and cert+key for the fleet-server instance, you can use [elasticsearch-certutil](https://www.elastic.co/guide/en/elasticsearch/reference/current/certutil.html) for this: |
| 94 | +```shell |
| 95 | +# Create a CA |
| 96 | +../elasticsearch/bin/elasticsearch-certutil ca --pem --out stack.zip |
| 97 | +unzip stack.zip |
| 98 | +# Create a cert+key |
| 99 | +../elasticsearch/bin/elasticsearch-certutil cert --pem --ca-cert ca/ca.crt --ca-key ca/ca.key --ip $HOST_IP_ADDR --out cert.zip |
| 100 | +unzip cert.zip |
113 | 101 | ```
|
114 | 102 |
|
115 |
| -This will start up Elastic Agent with fleet-server and directly enroll it. In addition, Fleet is set up inside Kibana. In case the setup is done already in Kibana manually, the following command can be used: |
| 103 | +Ensure that `server.ssl.enabled: true` is set as well as the `server.ssl.certificate` and `server.ssl.key` attributes in `fleet-server.yml` |
116 | 104 |
|
| 105 | +Then run the fleet-server: |
| 106 | +```shell |
| 107 | +./build/binaries/fleet-server-8.7.0-darwin-x86_64/fleet-server -c fleet-server.yml |
117 | 108 | ```
|
118 |
| -sudo ./elastic-agent enroll --fleet-server=http://elastic:changeme@localhost:9200 --fleet-server-policy={fleet-server-policy-id} --enrollment-token={policy-enrollment-token} |
119 |
| -``` |
120 |
| - |
121 |
| -## Running Elastic Agent with fleet-server in container |
| 109 | +By default the fleet-server will attempt to connect to Elasticsearch on `https://localhost:9200`, if this needs to be changed set it with `ELASTICSEARCH_HOSTS` |
| 110 | +The fleet-server should appear as an agent with the ID `dev-fleet-server`. |
122 | 111 |
|
123 |
| -If you want to run Elastic Agent and fleet-server in a container but built Kibana from source, you have to add the following to your `config/kibana.dev.yml`: |
124 |
| - |
125 |
| -``` |
126 |
| -server.host: 0.0.0.0 |
127 |
| -``` |
| 112 | +Any additional agents will need the `ca/ca.crt` file to enroll (or will need to use the `--insecure` flag). |
128 | 113 |
|
129 |
| -This makes sure, Kibana is accessible from the container. Start Kibana as before but for Elasticsearch, run the following command: |
| 114 | +#### fleet-server+agent on a Vagrant VM |
130 | 115 |
|
131 |
| -``` |
132 |
| -yarn es snapshot -E xpack.security.authc.api_key.enabled=true -E http.host=0.0.0.0 |
| 116 | +The development Vagrant machine assumes the `elastic-agent`, `beats`, and `fleet-server` repos are in the same folder. |
| 117 | +Thus, it mounts `../` to `/vagrant` on the Vagrant machine. The vagrant machine IP address is `192.168.56.43`. |
| 118 | +Use `https://192.168.56.43:8220` as fleet-server host. |
| 119 | +```shell |
| 120 | +vagrant up |
| 121 | +vagrant ssh |
133 | 122 | ```
|
134 | 123 |
|
135 |
| -This makes sure also Elasticsearch is accessible to the container. |
| 124 | +##### Build the elastic-agent |
136 | 125 |
|
137 |
| -Start the Elastic Agent with the following command: |
138 |
| - |
139 |
| -``` |
140 |
| -docker run -e KIBANA_HOST=http://{YOUR-IP}:5601 -e KIBANA_USERNAME=elastic -e KIBANA_PASSWORD=changeme -e ELASTICSEARCH_HOST=http://{YOUR-IP}:9200 -e ELASTICSEARCH_USERNAME=elastic -e ELASTICSEARCH_PASSWORD=changeme -e KIBANA_FLEET_SETUP=1 -e FLEET_SERVER_ENABLE=1 -e FLEET_SERVER_INSECURE_HTTP=1 docker.elastic.co/beats/elastic-agent:8.0.0-SNAPSHOT |
| 126 | +Once in the Vagrant VM, and assuming that the repos are correctly mounted in `/vagrant`. |
| 127 | +Build the agent by running: |
| 128 | +```shell |
| 129 | +cd /vagrant/elastic-agent |
| 130 | +SNAPSHOT=true EXTERNAL=true PLATFORMS="linux/amd64" PACKAGES="tar.gz" mage -v dev:package # adjust PLATFORMS and PACKAGES to your system and needs. |
141 | 131 | ```
|
142 | 132 |
|
143 |
| -Replace {YOUR-IP} with the IP address of your machine. |
| 133 | +For detailed instructions, check the [Elastic-Agent](https://github.com/elastic/elastic-agent) repo. |
144 | 134 |
|
145 |
| -## fleet-server repo |
| 135 | +##### Run the elastic-agent+fleet-server in Vagrant |
146 | 136 |
|
147 |
| -By default the above will download the most recent snapshot build for fleet-server. To use your own development build, run `make release` in the fleet-server repository, go to `build/distributions` and copy the `.tar.gz` and `sha512` file to the `data/elastic-agent-{hash}/downloads` inside the elastic-agent directory. Now you run with your own build of fleet-server. |
| 137 | +Copy and unpack the elastic-agent `.tar.gz` file and replace the `fleet-server` binary in `elastic-agent-8.Y.Z-SNAPSHOT-OS-ARCH/data/elastic-agent-*/components/` with the snapshot from the fleet-server repo. |
148 | 138 |
|
| 139 | +Then go to `Kibana > Managment > Fleet` and follow the instructions there. |
149 | 140 |
|
150 |
| -## Compatibility and upgrades |
| 141 | +The vagrant machine IP address is `192.168.56.43`. |
| 142 | +Use `https://192.168.56.43:8220` as fleet-server host. |
151 | 143 |
|
152 |
| -Fleet server is always on the exact same version as Elastic Agent running fleet-server. Any Elastic Agent enrolling into a fleet-server must be the same version or older. Fleet-server communicates with Elasticsearch. Elasticsearch must be on the same version or newer. For Kibana it is assumed it is on the same version as Elasticsearch. With this the compatibility looks as following: |
| 144 | +##### tl;dr/example: |
153 | 145 |
|
| 146 | +```shell |
| 147 | +cp /vagrant/elastic-agent/build/distributions/elastic-agent-8.7.0-SNAPSHOT-linux-x86_64.tar.gz* ./ |
| 148 | +tar -xzf elastic-agent-8.7.0-SNAPSHOT-linux-x86_64.tar.gz |
| 149 | +cd elastic-agent-8.7.0-SNAPSHOT-linux-x86_64 |
| 150 | +cp build/binaries/fleet-server-8.7.0-SNAPSHOT-linux-x86_64/fleet-server ./data/elastic-agent-494b79/components/ |
| 151 | +./elastic-agent install ... |
154 | 152 | ```
|
155 |
| -Elastic Agent <= Elastic Agent with fleet-server) <= Elasticsearch / Kibana |
156 |
| -``` |
157 |
| - |
158 |
| -There might be differences on the bugfix version. |
159 |
| - |
160 |
| -If an upgrade is done, Elasticsearch / Kibana have to be upgraded first, then Elastic Agent with fleet-server and last the Elastic Agents. |
161 |
| - |
162 |
| - |
163 |
| -## MacOSX Version |
164 |
| - |
165 |
| -The [golang-crossbuild](https://github.com/elastic/golang-crossbuild) produces images used for testing/building. |
166 |
| -The `golang-crossbuild:1.16.X-darwin-debian10` images expects the minimum MacOSX version to be 10.14+. |
0 commit comments