Revise seeding data documentation structure and expanded hosts overview (#44642)
Updated the seeding data documentation to improve clarity and organization, expanding hosts overview.
This commit is contained in:
Andrew Mellor
@@ -2,15 +2,11 @@
|
||||
|
||||
When developing Fleet, it may be useful to create seed data that includes users and fleets.
|
||||
|
||||
## Setup
|
||||
|
||||
> In order to run scripts that make use of premium features, make sure you have started the server with the correct flags as described in [Testing](https://fleetdm.com/docs/contributing/testing-and-local-development#license-key).
|
||||
|
||||
Check out this Loom demo video that walks through creating fleets (formally "teams") seed data:
|
||||
https://www.loom.com/share/1c41a1540e8f41328a7a6cfc56ad0a01
|
||||
|
||||
For a text-based walkthrough, follow these steps:
|
||||
|
||||
## Create an environment variable file
|
||||
### Create an environment variable file
|
||||
|
||||
First, create an `env` file with the following contents:
|
||||
|
||||
@@ -22,9 +18,9 @@ export TOKEN=eyJhbGciOi... # your api token
|
||||
|
||||
> Note: store the `env` file somewhere you won't commit your token, or apply these 3 environment variables directly in the command line.
|
||||
|
||||
## Apply your environment variable file
|
||||
### Apply your environment variable file
|
||||
|
||||
Next, set the `FLEET_ENV_PATH` to point to the `env` file using the command line.
|
||||
Set the `FLEET_ENV_PATH` to point to the `env` file.
|
||||
|
||||
```sh
|
||||
export FLEET_ENV_PATH=./path/to/env/file/fleet_env
|
||||
@@ -32,9 +28,15 @@ export FLEET_ENV_PATH=./path/to/env/file/fleet_env
|
||||
|
||||
This will let the scripts in the `/tools/api/fleet/` folder source the `env` file.
|
||||
|
||||
## Run one of the bash scripts to seed the data
|
||||
|
||||
Finally, run one of the bash scripts located in the [/tools/api](https://github.com/fleetdm/fleet/tree/main/tools/api) directory.
|
||||
## Seeding users
|
||||
|
||||
Check out this Loom demo video that walks through creating fleets (formerly "teams") seed data:
|
||||
https://www.loom.com/share/1c41a1540e8f41328a7a6cfc56ad0a01
|
||||
|
||||
For a text-based walkthrough, follow these steps:
|
||||
|
||||
Run one of the bash scripts located in the [/tools/api](https://github.com/fleetdm/fleet/tree/main/tools/api) directory.
|
||||
|
||||
### Seed free users
|
||||
|
||||
@@ -69,7 +71,7 @@ The `fleet/create_figma` script will generate an environment to reflect the mock
|
||||
Each user generated by the script has its password set to `password123#`.
|
||||
|
||||
|
||||
## Related actions
|
||||
## User-related actions
|
||||
|
||||
### Import queries and policies
|
||||
|
||||
@@ -85,9 +87,52 @@ Like all regular users, seeded users' API tokens expire frequently. For an API t
|
||||
|
||||
Fleet supports [SSO users](https://fleetdm.com/docs/deploying/configuration#configuring-single-sign-on-sso). Create an [SSO test user](https://fleetdm.com/docs/contributing/testing-and-local-development#testing-sso) to test signing on with simple SAML.
|
||||
|
||||
### Create test hosts
|
||||
## Seeding test hosts
|
||||
|
||||
There are three ways to create test hosts in your local development environment:
|
||||
|
||||
| Method | Best for | Platforms | Resource usage |
|
||||
|---|---|---|---|
|
||||
| [osquery-perf](#osquery-perf) | Simulating many hosts at scale | macOS, Windows, Linux, iOS, iPadOS | Low |
|
||||
| [Docker test hosts](#docker-test-hosts) | Testing with real osqueryd instances | CentOS, Ubuntu | High (RAM-intensive) |
|
||||
| [fleetctl preview](#fleetctl-preview) | Quick demos and exploration | macOS (simulated) | Medium |
|
||||
|
||||
### osquery-perf
|
||||
|
||||
A lightweight Go tool that simulates thousands of hosts from a single machine.
|
||||
|
||||
- Supports **macOS, Windows, Linux, iOS, and iPadOS** via `--os_templates`
|
||||
- iOS/iPadOS devices enroll via MDM (requires local MDM setup and SCEP challenge)
|
||||
- Control host count, enrollment rate, query intervals, and agent behavior
|
||||
- First-time setup requires building a software database
|
||||
|
||||
See the full [osquery-perf README](https://github.com/fleetdm/fleet/tree/main/cmd/osquery-perf) for usage instructions and
|
||||
available flags.
|
||||
|
||||
### Docker test hosts
|
||||
|
||||
Runs real containerized `osqueryd` instances. More realistic but limited to a handful
|
||||
of hosts due to memory usage.
|
||||
|
||||
```sh
|
||||
cd tools/osquery
|
||||
ENROLL_SECRET=<YOUR_ENROLL_SECRET> docker-compose up
|
||||
```
|
||||
|
||||
See the [Docker test hosts](https://github.com/fleetdm/fleet/tree/main/tools/osquery) for scaling options and
|
||||
platform-specific instructions.
|
||||
|
||||
### fleetctl preview
|
||||
|
||||
Starts a complete Fleet environment with pre-configured simulated hosts in one command.
|
||||
Not recommended for development testing.
|
||||
|
||||
```sh
|
||||
fleetctl preview
|
||||
```
|
||||
|
||||
See `fleetctl preview --help` for available options.
|
||||
|
||||
To create a handful of test hosts, you can run containerized `osqueryd` [Docker test hosts](https://github.com/fleetdm/fleet/tree/main/tools/osquery). As these Docker test hosts are RAM intensive, alternatively, you can use `osquery-perf` to create thousands of [simulated test hosts](https://github.com/fleetdm/fleet/tree/main/cmd/osquery-perf).
|
||||
|
||||
|
||||
<meta name="pageOrderInSection" value="600">
|
||||
|
||||
Reference in New Issue
Block a user