Configuration files for multiple teams #384
Conversation
| spec: | ||
| config: | ||
| team_name: default | ||
| options: |
There was a problem hiding this comment.
I haven't really thought about it because I haven't had a need for it in other fleet types, but I imagine options will be mostly the same with minor differences across teams. With that in mind, it would be good to support YAML anchors to reduce required duplication.
I'm putting this on options, but the same thing applies for basically any piece of config here.
Good example: https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/
(I don't know whether or not this is currently supported in any of fleet config; if it is, can mostly ignore this comment other than maybe updating docs to reference it)
There was a problem hiding this comment.
Ah, this is the first time I've seen YAML anchors. Thank you for the examples link. I assume Fleet config support anchors but I'll try to confirm this.
I imagine options will be mostly the same with minor differences across teams
This is very helpful information.
| always: | ||
| - "SELECT user AS username FROM logged_in_users WHERE user <> '' ORDER BY time LIMIT 1" | ||
| interval: | ||
| 3600: "SELECT total_seconds AS uptime FROM uptime" |
There was a problem hiding this comment.
I... clearly haven't used interval decorators or I probably would have noticed this in the existing fleet config.
It looks like interval is a map of int (seconds) to string (query). However, what happens if I want to run two queries at the same interval? I suspect maybe this should instead be something like:
interval:
- query: "SELECT thing FROM some_place"
interval: 3600
- query: "SELECT other_thing FROM other_place"
interval: 3600
| spec: | ||
| secrets: | ||
| - active: true | ||
| name: "default" |
There was a problem hiding this comment.
Will name of secret be something that can be targeted by queries?
Currently, you can target (non-exhaustive list):
- individual host
- hosts by labels
I imagine in the new world of teams, it might be useful to support querying by team, querying by secret name, and querying by the current query targeting options.
There was a problem hiding this comment.
No, we're not planning on supporting querying by name.
Querying by team will be supported.
We don't plan to support querying by name because the working hypothesis is that teams will be used primarily for host segmentation.
Multiple enroll secrets can correspond to the same team, however, query targeting will be limited to team, host, and label
There was a problem hiding this comment.
Targeting suggestions:
- intersection / union of different combinations of team / host / label
I imagine wanting to do something like: run this query on anything except this one specific team. That might be possible with labels, but only if there's a way to treat 'team' membership as part of label definition.
examples/config-many-files/teams.yml
Outdated
| spec: | ||
| teams: | ||
| - name: workstations | ||
| hosts: |
There was a problem hiding this comment.
Imagine I have a team (whether created by fleetctl or the UI).
In this team, I've created a secret (as shown in the teams-enroll-secret.yml example) that maps to the workstations team.
I assume that if I enroll with that secret, I'll get added to to the workstations team.
So... scenario:
- host_00001, host_00002, ..., host_0000n are currently enrolled, using the secret above
If I apply the example config file, will this remove all of the existing hosts from the team? Will they end up re-enrolling / being put back in the team by the enroll secret?
Manually specifying host names for the team seems more like an optional addition / manual override of hosts and adding them to a specific team. Is that a better way of thinking about it, rather than looking at the hosts here as an exhaustive list of hosts in a given team?
(I'm basing this on other concepts currently in fleet, such as packs, where if I have queryA, queryB in a pack, but then I apply a pack config with just queryA via fleetctl, it will stop scheduling queryB in the pack. If this is different behavior for different concepts, it will be important to make this clear in the documentation and possibly in the naming of this new concept.)
There was a problem hiding this comment.
I assume that if I enroll with that secret, I'll get added to to the workstations team.
You're correct :)
If I apply the example config file, will this remove all of the existing hosts from the team? Will they end up re-enrolling / being put back in the team by the enroll secret?
If you apply the example config file, the hosts that are specified as members of the servers team will be transferred from the workstations team to the servers team using a new API endpoint. The hosts that are specified as members so the workstations team will remain on the workstations team.
Is that a better way of thinking about it, rather than looking at the hosts here as an exhaustive list of hosts in a given team?
This is a great question. The current thinking is yes, specifying host names and users here acts as a manual override of hosts and users by transferring and adding them to a different team. As you've said this behavior is different from the current config concept in Fleet. I'm curious if it makes more sense to have this config file act as an exhaustive list. I think including all hosts and users on a team would be very difficult to maintain/update.
There was a problem hiding this comment.
I think including all hosts and users on a team would be very difficult to maintain/update.
Very much agree, but wanted to confirm. I like the way you're thinking about the implementation of this one. It still would probably good to make this really clear in docs since it does differ from other fleet config concepts.
examples/config-many-files/teams.yml
Outdated
| - hwardware_serial2 | ||
| - hwardware_serial3 | ||
| users: | ||
| - email1 |
There was a problem hiding this comment.
Same comment as about hosts above.
Also - I imagine this is sort of a v0, but I'm starting to think about what definitions of roles for RBAC will look like.
There was a problem hiding this comment.
Good point. I've added the role key in commit 63fca2b. You're right in that this is sort of a v0. The teams.yml config file closely aligns with the draft /teams API endpoint described in the REST API for multiple teams draft PR.
|
@nyanshak I've added comments to each file that include descriptions for what each piece of the config does. |
| @@ -0,0 +1,68 @@ | |||
| # This configuration file manages the osquery options in Fleet. | |||
| # The `team_name` key determines which team's hosts the spec applies to. | |||
| # The current thinking is that options specified for `team_name` default | |||
There was a problem hiding this comment.
+1 to having default set of options.
Additionally - probably worth thinking about having multiple sets of default options (default, as well as overrides for macOS, linux, etc.).
And similarly, the options block per-team should probably support overrides per-platform specific to that team. 🤷♀️
There was a problem hiding this comment.
probably worth thinking about having multiple sets of default options (default, as well as overrides for macOS, linux, etc.)
Agree. The current thinking is that the default options will support platform-specific overrides.
And similarly, the options block per-team should probably support overrides per-platform specific to that team.
Also agree. The team-specific options will also support per-platform overrides.
The current thinking is that overrides specified for each team will only apply to that team.
For example, if overrides are specified for macOS machines in the default set of options, those overrides will not apply to macOS machines that are assigned to a specific team.
The same goes for the team-specific options to default options direction. If overrides are specified for Linux machines in team-specific options, these overrides will not apply to hosts that receive the default options (because they're not a member of a specific team)
examples/config-many-files/teams.yml
Outdated
| @@ -0,0 +1,27 @@ | |||
| # This configuration file allows for the manaing of teams in Fleet. | |||
There was a problem hiding this comment.
Nit: spell-check: manaing -> managing
examples/config-many-files/teams.yml
Outdated
| - email: email1 | ||
| role: admin | ||
| - email: email2 | ||
| role: maintainer |
There was a problem hiding this comment.
Are roles pre-defined or user-defined?
If pre-defined, can I see any docs around what the roles mean?
If user-defined, are there config files / specs around how to define roles?
(also I'm guessing that this PR is probably working on conceptualizing several concepts that don't have complete implementations, so it's a fair response to just say "coming soon")
There was a problem hiding this comment.
Roles will be pre-defined.
can I see any docs around what the roles mean?
I'm currently working on a draft of these docs here! I'll ping you when I make more progress this week.
…o enroll-secret.yml. Add team specific options and enroll secrets to yeams.yml.
|
@nyanshak We've recently updated our thinking for the changes to the configuration files that will be used, upon the release of the Teams feature, to manage agent options (osquery options), enroll secrets, and teams in Fleet. I've updated this PRs description and the |
This PR is a working draft of the configuration file format that will be included with the introduction of multiple teams in Fleet #288.
Like #383, the additions included do not exactly reflect what will be implemented during the project. The expectation is that there will be much discussion and change.
The configuration files included in this PR:
config.ymlFleet Basic customers will have access to the Teams feature. Teams allows Fleet users to separate hosts into exclusive groups.
config.ymlfile. See theteams.ymlconfiguration file for an example of team specific agent options.enroll-secret.ymlFleet Basic customers will have access to the Teams feature. Teams allows Fleet users to separate hosts into exclusive groups.
teams.ymlconfiguration file for an example of team specific enroll secrets.teams.ymlFleet Basic customers will have access to the Teams feature. Teams allows Fleet users to separate hosts into exclusive groups. In addition, Teams allows Fleet users to define the level of access each user, within their organization, has to these groups of hosts.
membersproperty allows users to define which users have access to the hosts assigned to the given team. This property also specifies therolefor each user.agent_optionsfield allows users to define the agent options to be applied to the hosts that are assigned to the given team. The agent options supplied here will override the global agent options specified by thisconfig.ymlfile.enroll_secretsproperty allows users to define unique enroll secrets for the given team. Hosts that enrolls to Fleet using the enroll secrets specified in this file will be automatically assigned to the given team in Fleet.