In attempting to set up Prefect 0.14.15 for Flow execution across multiple Agents using the Docker Compose file produced by prefect server config, I was surprised to discover that that Prefect's Server requires a Tenant in order for an Agent to connect. I investigated to find that Prefect's docs provide info on the usage syntax of their create-tenant and list-tenants CLI operations. However, I've looked extensively through the linked pages — along with the rest of Prefect's documentation and accompanying tutorials — for any mention of Tenants, and only found the following brief mention:
Once authenticated, user-based API keys can be used to generate short-lived JWT auth tokens for any tenant the user belongs to. These API keys inherit any permissions the user has in that tenant, allowing full API access.
What, exactly, is a Tenant in Prefect? It doesn't appear to be specific to Prefect's Hybrid Execution model. How, then, does it fit into the interactions between the Server, Agents, and Client before and during the execution of a Prefect Flow? What does it mean to say that a user "belongs to" or is "in" a tenant? And what is accomplished by requiring it to register an Agent with the Server?
A tenant has far less meaning in Prefect Server than Prefect Cloud but since Cloud is built on the open source Server code, the idea persists there.
A tenant is the top-level object which all other objects exist in. A user in a tenant cannot access anything in another tenant. In Cloud, this permissioning is strictly enforced to limit the scope of a user's access. In Server, you just need a tenant to begin using the system because most objects will be linked back to a tenant. Typically, a default tenant is created for you during startup if you use the Prefect CLI prefect server start or you can toggle automatic creation in the Prefect Server Helm chart.
When an agent is registered with the server, we store details about that agent in the 'agents' table of the database. In Server, your agent is associated with the default tenant. In Cloud, your agent is associated with the tenant that the API Key used to start the agent belongs to.
When you run a flow, the Client must talk to the server to report the status of the flow. As with the agent, this flow run is associated with a tenant. In Cloud, this inherits the API Key of the agent. In Server, we will continue to use the default tenant.
tldr; Tenants are the basis for Prefect Cloud Teams that a user belongs to and are used for permissioning. In Prefect Server, you just need to have one; create it and forget about it (or use our standard tooling which creates it for you).