mirror of
https://github.com/empayre/fleet.git
synced 2024-11-06 00:45:19 +00:00
Improve developer documentation: Update seed data documentation (#7904)
This commit is contained in:
RachelElysia
GitHub
parent
753483ffd6
commit
3054450065
@ -31,7 +31,7 @@ The best practice is to create a team with test (canary) hosts first and then tu
|
||||
|
||||
Here's how to turn on the software inventory feature for only your 🐣 Servers (canaries) team:
|
||||
|
||||
1. Log in to Fleet with `fleetctl login`. If you use single-sign on (SSO) to log in to Fleet, check out the [documentation for logging in with SSO](https://fleetdm.com/docs/using-fleet/fleetctl-cli#logging-in-with-saml-sso-authentication).
|
||||
1. Log in to Fleet with `fleetctl login`. If you use single sign-on (SSO) to log in to Fleet, check out the [documentation for logging in with SSO](https://fleetdm.com/docs/using-fleet/fleetctl-cli#logging-in-with-saml-sso-authentication).
|
||||
|
||||
1. Run the `fleetctl get teams --yaml --name "🐣 Servers (canaries)" > "🐣 Servers (canaries)".yaml` command. This will create a YAML file in your current working directory. You may have to log in to Fleet with `fleetctl login`.
|
||||
|
||||
|
||||
@ -4,7 +4,8 @@ Fleet's [standard query library](https://fleetdm.com/queries) includes a growing
|
||||
|
||||
## Importing the queries in Fleet
|
||||
|
||||
### After cloning the fleetdm/fleet repo, import the queries using fleetctl:
|
||||
After cloning the fleetdm/fleet repo, import the queries and policies found in `docs/01-Using-Fleet/standard-query-library/standard-query-library.yml` using [fleetctl](https://fleetdm.com/docs/using-fleet/fleetctl-cli):
|
||||
|
||||
```
|
||||
fleetctl apply -f docs/01-Using-Fleet/standard-query-library/standard-query-library.yml
|
||||
```
|
||||
@ -13,7 +14,7 @@ fleetctl apply -f docs/01-Using-Fleet/standard-query-library/standard-query-libr
|
||||
|
||||
Do you want to add your own query?
|
||||
|
||||
1. Please copy the following YAML section and paste it at the bottom of the [`standard-query-library.yml`](./standard-query-library.yml) file.
|
||||
1. Please copy the following YAML section and paste it at the bottom of the [`standard-query-library.yml`](https://github.com/fleetdm/fleet/blob/main/docs/01-Using-Fleet/standard-query-library/standard-query-library.yml) file.
|
||||
|
||||
```yaml
|
||||
---
|
||||
|
||||
@ -2,47 +2,86 @@
|
||||
|
||||
When developing Fleet, it may be useful to create seed data that includes users and teams.
|
||||
|
||||
|
||||
> 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 teams seed data:
|
||||
https://www.loom.com/share/1c41a1540e8f41328a7a6cfc56ad0a01
|
||||
|
||||
For a text-based walkthrough, check out the following steps:
|
||||
For a text-based walkthrough, follow these steps:
|
||||
|
||||
## Create an environment variable file
|
||||
|
||||
First, create an `env` file with the following contents:
|
||||
|
||||
```
|
||||
export SERVER_URL=https://localhost:8080 # your Fleet server URL and port
|
||||
export CURL_FLAGS='-k -s' # set insecure flag
|
||||
export TOKEN=eyJhbGciOi... # your login token
|
||||
export TOKEN=eyJhbGciOi... # your api token
|
||||
```
|
||||
|
||||
Next, set the `FLEET_ENV_PATH` to point to the `env` file. This will let the scripts in the `fleet/` folder source the env file.
|
||||
> 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
|
||||
|
||||
Next, set the `FLEET_ENV_PATH` to point to the `env` file using the command line.
|
||||
|
||||
```
|
||||
export FLEET_ENV_PATH=/Users/victor/fleet_env
|
||||
export FLEET_ENV_PATH=./path/to/env/file/fleet_env
|
||||
```
|
||||
|
||||
Finally, run one of the bash scripts located in the [/tools/api](../../tools/api/README.md) directory.
|
||||
This will let the scripts in the `/tools/api/fleet/` folder source the `env` file.
|
||||
|
||||
The `fleet/create_free` script will generate an environment to roughly reflect an installation of Fleet Free. The script creates three users with different roles.
|
||||
## 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.
|
||||
|
||||
### Seed free users
|
||||
|
||||
The `fleet/create_free` script will generate an environment to roughly reflect an installation of Fleet Free. The script creates 3 users with different roles. From the fleet directory, run:
|
||||
|
||||
```
|
||||
./tools/api/fleet/teams/create_free
|
||||
```
|
||||
|
||||
The `fleet/create_premium` script will generate an environment to roughly reflect an installation of Fleet Premium. The script will create two teams of four users with different roles.
|
||||
<img width="1000" alt="Test users for a free account" src="https://user-images.githubusercontent.com/71795832/193676340-2b68aba2-802f-41a7-8817-5b704d5dedac.png">
|
||||
|
||||
### Seed premium users
|
||||
|
||||
The `fleet/create_premium` script will generate an environment to roughly reflect an installation of Fleet Premium. The script will create 2 teams of 7 users with different roles. From the fleet directory, run:
|
||||
|
||||
```
|
||||
./tools/api/fleet/teams/create_premium
|
||||
```
|
||||
|
||||
The `fleet/create_figma` script will generate an environment to reflect the mockups in the Fleet EE (current) Figma file. The script creates three teams and twelve users with different roles.
|
||||
<img width="1000" alt="Test users for a premium account" src="https://user-images.githubusercontent.com/71795832/193676358-2afc266a-aecf-472c-b854-51cefed4f7dc.png">
|
||||
|
||||
### Seed designing users
|
||||
|
||||
The `fleet/create_figma` script will generate an environment to reflect the mockups in the Fleet EE (current) Figma file. The script creates 3 teams and 12 users with different roles. From the fleet directory, run:
|
||||
|
||||
```
|
||||
./tools/api/fleet/teams/create_figma
|
||||
```
|
||||
|
||||
Each user-generated by the script has its password set to `user123#`.
|
||||
<img width="1000" alt="Users for designing in Figma" src="https://user-images.githubusercontent.com/71795832/193676371-d775e5a4-528b-4067-a025-3ce571b0be1f.png">
|
||||
|
||||
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](./Testing-and-local-development.md#license-key).
|
||||
Each user generated by the script has its password set to `password123#`.
|
||||
|
||||
<meta name="pageOrderInSection" value="600">
|
||||
|
||||
## Related actions
|
||||
|
||||
### Import queries and policies
|
||||
|
||||
After seeding users and teams, check out [importing queries and policies](https://fleetdm.com/docs/using-fleet/standard-query-library#importing-the-queries-in-fleet) from Fleet's [standard query library](https://fleetdm.com/queries).
|
||||
|
||||
### Create an API-only user
|
||||
|
||||
Like all regular users, seeded users' API tokens expire frequently. For an API token that does not expire, create an [API-only user](https://fleetdm.com/docs/using-fleet/fleetctl-cli#using-fleetctl-with-an-api-only-user).
|
||||
|
||||
### Create a single sign-on (SSO) user
|
||||
|
||||
> Set up [SMTP options](https://fleetdm.com/docs/contributing/testing-and-local-development#email) in your developer environment first to invite a SSO user.
|
||||
|
||||
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.
|
||||
@ -223,7 +223,7 @@ The Fleet repo includes tools to start testing osquery hosts. Please see the doc
|
||||
|
||||
### Manually testing email with MailHog
|
||||
|
||||
To intercept sent emails while running a Fleet development environment, first, in the Fleet UI, navigate to the Organization settings page under Admin.
|
||||
To intercept sent emails while running a Fleet development environment, first, as an Admin in the Fleet UI, navigate to the Organization settings.
|
||||
|
||||
Then, in the "SMTP options" section, enter any email address in the "Sender address" field, set the "SMTP server" to `localhost` on port `1025`, and set "Authentication type" to `None`. Note that you may use any active or inactive sender address.
|
||||
|
||||
|
||||
@ -22,6 +22,7 @@ This page includes a list of available resources and their API routes.
|
||||
|
||||
## Authentication
|
||||
|
||||
- [Retrieve your API token](#retrieve-your-api-token)
|
||||
- [Log in](#log-in)
|
||||
- [Log out](#log-out)
|
||||
- [Forgot password](#forgot-password)
|
||||
@ -32,6 +33,8 @@ This page includes a list of available resources and their API routes.
|
||||
- [Initiate SSO](#initiate-sso)
|
||||
- [SSO callback](#sso-callback)
|
||||
|
||||
### Retrieve your API token
|
||||
|
||||
All API requests to the Fleet server require API token authentication unless noted in the documentation. API tokens are tied to your Fleet user account.
|
||||
|
||||
To get an API token, retrieve it from the "Account settings" > "Get API token" in the Fleet UI (`/profile`). Or, you can send a request to the [login API endpoint](#log-in) to get your token.
|
||||
|
||||
@ -751,12 +751,12 @@ Fleet policy requires that:
|
||||
|
||||
1. Fleet software engineering and product development are required to follow security best practices. The product should be "Secure by Design" and "Secure by Default."
|
||||
|
||||
2. Fleet performs quality assurance activities. This may include
|
||||
2. Fleet performs quality assurance activities. This may include:
|
||||
|
||||
* peer code reviews prior to merging new code into the main development branch
|
||||
(e.g., master branch).
|
||||
* thorough product testing before releasing it to production (e.g., unit testing
|
||||
and integration testing).
|
||||
* Peer code reviews prior to merging new code into the main development branch
|
||||
(e.g., main branch)
|
||||
* Thorough product testing before releasing it to production (e.g., unit testing
|
||||
and integration testing)
|
||||
|
||||
3. Risk assessment activities (i.e., threat modeling) must be performed for a new product or extensive changes to an existing product.
|
||||
|
||||
|
||||
@ -33,7 +33,7 @@ const (
|
||||
ssoAccountInvalid ssoErrCode = "account_invalid"
|
||||
)
|
||||
|
||||
// ssoError is an error that occurs during the Single-Sign-On flow. Its code
|
||||
// ssoError is an error that occurs during the single sign-on flow. Its code
|
||||
// indicates the type of error.
|
||||
type ssoError struct {
|
||||
err error
|
||||
|
||||
@ -5,7 +5,7 @@ First, create a `env` file with the following contents:
|
||||
```
|
||||
export SERVER_URL=https://localhost:8080 # your fleet server url and port
|
||||
export CURL_FLAGS='-k -s' # set insecure flag
|
||||
export TOKEN=eyJhbGciOi... # your login token
|
||||
export TOKEN=eyJhbGciOi... # your api token
|
||||
```
|
||||
|
||||
Next set the `FLEET_ENV_PATH` to point to the `env` file. This will let the scripts in the `fleet/` folder source the env file.
|
||||
@ -13,7 +13,7 @@ Next set the `FLEET_ENV_PATH` to point to the `env` file. This will let the scri
|
||||
# Examples
|
||||
|
||||
```
|
||||
export FLEET_ENV_PATH=/Users/victor/fleet_env
|
||||
export FLEET_ENV_PATH=./path/to/env/file/fleet_env
|
||||
|
||||
# get my user info
|
||||
./tools/api/fleet/me
|
||||
|
||||
@ -24,7 +24,7 @@ create_user_endpoint="api/latest/fleet/users/admin"
|
||||
|
||||
# Create Anna
|
||||
data='{
|
||||
"name": "Anna",
|
||||
"name": "Anna G. Admin",
|
||||
"email": "anna@organization.com",
|
||||
"password": "password123#",
|
||||
"invited_by": 1,
|
||||
@ -35,7 +35,7 @@ curl -X POST $CURL_FLAGS -H "Authorization: Bearer $TOKEN" "$SERVER_URL/$create_
|
||||
|
||||
# Create Mary
|
||||
data='{
|
||||
"name": "Mary",
|
||||
"name": "Mary G. Maintainer",
|
||||
"email": "mary@organization.com",
|
||||
"password": "password123#",
|
||||
"invited_by": 1,
|
||||
@ -46,7 +46,7 @@ curl -X POST $CURL_FLAGS -H "Authorization: Bearer $TOKEN" "$SERVER_URL/$create_
|
||||
|
||||
# Create Oliver
|
||||
data='{
|
||||
"name": "Oliver",
|
||||
"name": "Oliver G. Observer",
|
||||
"email": "oliver@organization.com",
|
||||
"password": "password123#",
|
||||
"invited_by": 1,
|
||||
@ -57,7 +57,7 @@ curl -X POST $CURL_FLAGS -H "Authorization: Bearer $TOKEN" "$SERVER_URL/$create_
|
||||
|
||||
# Create Marco
|
||||
data='{
|
||||
"name": "Marco",
|
||||
"name": "Marco Mixed Roles",
|
||||
"email": "marco@organization.com",
|
||||
"password": "password123#",
|
||||
"invited_by": 1,
|
||||
@ -93,9 +93,27 @@ data='{
|
||||
}'
|
||||
curl -X POST $CURL_FLAGS -H "Authorization: Bearer $TOKEN" "$SERVER_URL/$create_user_endpoint" -d "$data" --insecure
|
||||
|
||||
|
||||
# Create Manny
|
||||
data='{
|
||||
"name": "Manny T. Maintainer",
|
||||
"email": "manny@organization.com",
|
||||
"password": "password123#",
|
||||
"invited_by": 1,
|
||||
"global_role": null,
|
||||
"admin_forced_password_reset": false,
|
||||
"teams": [
|
||||
{
|
||||
"id": 1,
|
||||
"role": "maintainer"
|
||||
}
|
||||
]
|
||||
}'
|
||||
curl -X POST $CURL_FLAGS -H "Authorization: Bearer $TOKEN" "$SERVER_URL/$create_user_endpoint" -d "$data" --insecure
|
||||
|
||||
# Create Toni
|
||||
data='{
|
||||
"name": "Toni",
|
||||
"name": "Toni T. Observer",
|
||||
"email": "toni@organization.com",
|
||||
"password": "password123#",
|
||||
"invited_by": 1,
|
||||
|
||||
@ -277,7 +277,7 @@ parasails.registerPage('state-of-device-management', {
|
||||
challengesEncountered: [
|
||||
{label: 'Too complicated to configure and understand', percent: '36.1', color: '#A182DF'},
|
||||
{label: 'Confusing or limited documentation', percent: '34.2', color: '#E59CC4'},
|
||||
{label: 'Integrating with single-sign on (Okta, SAML, etc.)', percent: '32.7', color: '#F1AC8C'},
|
||||
{label: 'Integrating with single sign-on (Okta, SAML, etc.)', percent: '32.7', color: '#F1AC8C'},
|
||||
{label: 'Hard to get support', percent: '32.7', color: '#91D4C7'},
|
||||
{label: 'Unable to automate everything we want with the API', percent: '32.2', color: '#C4C2CE'},
|
||||
{label: 'Didn’t know where to start', percent: '30.7', color: '#8191E5'},
|
||||
@ -299,7 +299,7 @@ parasails.registerPage('state-of-device-management', {
|
||||
{label: 'Collecting security data from enrolled devices', percent: '25.9', color: '#8191E5'},
|
||||
{label: 'GitOps workflows for configuration', percent: '24.4', color: '#23AD8E'},
|
||||
{label: 'Remotely locking or wiping devices', percent: '23.4', color: '#E5D698'},
|
||||
{label: 'Integration with single-sign on (Okta, etc.)', percent: '23.4', color: '#B99EEF'},
|
||||
{label: 'Integration with single sign-on (Okta, etc.)', percent: '23.4', color: '#B99EEF'},
|
||||
{label: '24/7 support', percent: '23.4', color: '#CB73A3'},
|
||||
{label: 'Developer-friendly API and webhooks', percent: '22.9', color: '#E3B6A0'},
|
||||
{label: 'Device posture information available in API or integrations ("zero trust")', percent: '22.9', color: '#91D49C'},
|
||||
|
||||
Loading…
Reference in New Issue
Block a user