Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add GitOps docs for "No team" #22273

Closed
wants to merge 11 commits into from
Closed

Add GitOps docs for "No team" #22273

Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
376646c
Add GitOps docs for No team
lucasmrod Sep 20, 2024
0f65aa3
Update docs/Configuration/yaml-files.md
lucasmrod Sep 20, 2024
7ad0084
Update docs/Configuration/yaml-files.md
noahtalerman Sep 23, 2024
7f37c07
Update docs/Configuration/yaml-files.md
noahtalerman Sep 23, 2024
e43a4c6
Update docs/Configuration/yaml-files.md
noahtalerman Sep 23, 2024
dbc5820
Update docs/Configuration/yaml-files.md
noahtalerman Sep 23, 2024
363768f
Update yaml-files.md
noahtalerman Sep 23, 2024
6555ccc
Minor fixes
lucasmrod Sep 23, 2024
1e062cb
Update docs/Configuration/yaml-files.md
noahtalerman Sep 23, 2024
3cdd399
Update docs/Configuration/yaml-files.md
noahtalerman Sep 23, 2024
304fb24
Update docs/Configuration/yaml-files.md
noahtalerman Sep 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 52 additions & 8 deletions docs/Configuration/yaml-files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,9 @@ To learn how to set up a GitOps workflow see the [Fleet GitOps repo](https://git

## File structure

- `default.yml`- File where you define the queries, policies, controls, and agent options for all hosts. If you're using Fleet Premium, this file updates queries and policies that run on all hosts ("All teams"). Controls and agent options are defined for hosts on "No team."
- `teams/` - Folder where you define your teams in Fleet. These `teams/team-name.yml` files define the controls, queries, policies, and agent options for hosts assigned to the specified team. Teams are available in Fleet Premium.
- `default.yml` - File where you define the queries, policies and agent options for all hosts. If you're using Fleet Premium, this file updates queries and policies that run on all hosts ("All teams").
- `teams/no-team.yml` - File where you define the policies, controls, and software for hosts on "No team". Available in Fleet Premium.
- `teams/` - Folder where you define your teams in Fleet. These `teams/team-name.yml` files define the controls, queries, policies, software, and agent options for hosts assigned to the specified team. Available in Fleet Premium.
- `lib/` - Folder where you define policies, queries, configuration profiles, scripts, and agent options. These files can be referenced in top level keys in the `default.yml` file and the files in the `teams/` folder.
- `.github/workflows/workflow.yml` - The GitHub workflow file where you can add [environment variables](https://docs.github.com/en/actions/learn-github-actions/variables#defining-environment-variables-for-a-single-workflow).

Expand All @@ -24,8 +25,7 @@ name: # Only teams/team-name.yml. To edit a team's name, change `name` but don't
policies:
queries:
agent_options:
controls:
software:
controls: # Can be defined in teams/no-team.yml too.
org_settings: # Only default.yml
team_settings: # Only teams/team-name.yml
```
Expand All @@ -40,6 +40,8 @@ team_settings: # Only teams/team-name.yml
### policies

Polcies can be specified inline in your `default.yml` file or `teams/team-name.yml` files. They can also be specified in separate files in your `lib/` folder.
Policies defined in `default.yml` run on **all** hosts.
Policies defined in `teams/no-team.yml` run on hosts that belong to "No team".

#### Options

Expand Down Expand Up @@ -81,9 +83,16 @@ policies:
platform: darwin
critical: false
calendar_event_enabled: false
- name: Firefox on Linux installed and up to date
platform: linux
description: "This policy checks that Firefox is installed and up to date."
resolution: "Install Firefox version 129.0.2 or higher."
query: "SELECT 1 FROM deb_packages WHERE name = 'firefox' AND version_compare(version, '129.0.2') >= 0;"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's use 129.0.3 here; I know the query for 129.0.2 is bugged based on the rest of the build string Mozilla provides, so this is a bad example 😬

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't follow sorry, this example has been working for me on my Ubuntu VM.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, I tested an upgrade path from Firefox 129.0.0, as https://ftp.mozilla.org/pub/firefox/releases/129.0/linux-x86_64/en-US/firefox-129.0.deb. The version string on that .deb is 129.0~build2, which appears to pass the version_compare call against 129.0.2, so it wouldn't register as outdated and the upgrade wouldn't be pushed.

It looks like this isn't a one-off either, as e.g. the current 129.0.2 for amd64 is build1.

I was able to repro this in my QA of #20895 / #19551. Let me know if you need help repro'ing this.

Copy link
Member Author

@lucasmrod lucasmrod Sep 20, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh gotcha. Makes sense.

Isn't this broken for 129.0.3 too?

osquery> select version_compare('129.0~build2', '129.0.3') >= 0;
+-------------------------------------------------+
| version_compare('129.0~build2', '129.0.3') >= 0 |
+-------------------------------------------------+
| 1                                               |
+-------------------------------------------------+

We could amend the query to remove any build suffixes or add a patch version 0 when it isn't present.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, yep.

And yeah, we should take that into account on the query if we're using FF as an example. I'm sure it's not the only package with an issue like this.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, very hard to detect all edge cases with all apps, but... that's the point of this feature, you write a query per app (trade off ease of use vs flexibility). For most cases the compare_version SQL will work, if it doesn't you can modify it for your custom app/scripts.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep. Having this for FF May be a good way to show "if you need to customize for edge cases, this is how you could"

install_software:
package_path: "../lib/linux-firefox.deb.package.yml"
```

`default.yml` or `teams/team-name.yml`
`default.yml`, `teams/team-name.yml`, or `teams/no-team.yml`

```yaml
policies:
Expand Down Expand Up @@ -210,6 +219,8 @@ queries:

The `controls` section allows you to configure scripts and device management (MDM) features in Fleet.

Controls for hosts that are in "No team" can be defined in `default.yml` or in `teams/no-team.yml` (but not in both files).

- `scripts` is a list of paths to macOS, Windows, or Linux scripts.
- `windows_enabled_and_configured` specifies whether or not to turn on Windows MDM features (default: `false`). Can only be configured for all teams (`default.yml`).
- `enable_disk_encryption` specifies whether or not to enforce disk encryption on macOS and Windows hosts (default: `false`).
Expand Down Expand Up @@ -304,11 +315,15 @@ Can only be configure for all teams (`default.yml`).
> **Experimental feature**. This feature is undergoing rapid improvement, which may result in breaking changes to the API or configuration surface. It is not recommended for use in automated workflows.

The `software` section allows you to configure packages and Apple App Store apps that you want to install on your hosts.
Software for hosts that belong to "No team" have to be defined in `teams/no-team.yml`.
Software can also be specified in separate files in your `lib/` folder.

- `packages` is a list of software packages (.pkg, .msi, .exe, or .deb) and software specific options.
- `app_store_apps` is a list of Apple App Store apps.

##### Example
#### Example

##### Inline

```yaml
software:
Expand All @@ -326,20 +341,49 @@ software:
- app_store_id: '1091189122'
```

#### packages
##### packages

- `url` specifies the URL at which the software is located. Fleet will download the software and upload it to S3 (default: `""`).
- `install_script.path` specifies the command Fleet will run on hosts to install software. The [default script](https://github.com/fleetdm/fleet/tree/main/pkg/file/scripts) is dependent on the software type (i.e. .pkg).
- `pre_install_query.path` is the osquery query Fleet runs before installing the software. Software will be installed only if the [query returns results](https://fleetdm.com/tables/account_policy_data) (default: `""`).
- `post_install_script.path` is the script Fleet will run on hosts after intalling software (default: `""`).
- `self_service` specifies whether or not end users can install from **Fleet Desktop > Self-service**.

#### app_store_apps
##### app_store_apps

- `app_store_id` is the ID of the Apple App Store app. You can find this at the end of the app's App Store URL. For example, "Bear - Markdown Notes" URL is "https://apps.apple.com/us/app/bear-markdown-notes/id1016366447" and the `app_store_id` is `1016366447`.

> Make sure to include only the ID itself, and not the `id` prefix shown in the URL. The ID must be wrapped in quotes as shown in the example so that it is processed as a string.

##### Separate file

`lib/software-name.package.yml`:

```yaml
url: https://dl.tailscale.com/stable/tailscale-setup-1.72.0.exe
install_script:
path: ../lib/software/tailscale-install-script.ps1
self_service: true
```

`lib/software/tailscale-install-script.ps1`

```yaml
$exeFilePath = "${env:INSTALLER_PATH}"
$installProcess = Start-Process $exeFilePath `
-ArgumentList "/quiet /norestart" `
-PassThru -Verb RunAs -Wait
```

noahtalerman marked this conversation as resolved.
Show resolved Hide resolved
`default.yml`, `teams/team-name.yml`, or `teams/no-team.yml`

```yaml
software:
packages:
- path: ../lib/software-name.package.yml
# path is relative to default.yml or teams/team-name.yml
```

### org_settings and team_settings

#### features
Expand Down
Loading