Simplify Rover usage with per-project configuration

# Simplify Rover usage with per-project configuration # Problems to solve 1. People new to Apollo have to go through too many hoops to start from scratch and have a satisfying subgraph dev experience. 2. New subgraph developers on existing subgraphs need to learn too much to get started, inhibiting developer adoption. # Suggested Solution Config as code for subgraph developers (details below). This solution means: 1) Infrastructure can be easily integrated into version control to track infrastructure changes over time 2) Automation becomes much easier for GraphOS adopters because rover commands no longer need to be wrapped in scripts and makefiles 3) Infrastructure becomes standardized, so the current friction experienced by developers moving from one subgraph project to another is significantly reduced 4) Reduces the need for manual intervention by developers, saving time and money for our customers 5) Configuration drift between multiple variants becomes much easier to manage and understand 6) Allows organizations to scale up their operations and usage of Apollo much faster # prior art The following are links to documentation for some popular devtool configuration manifests. [wundergraph.config.js](https://docs.wundergraph.com/docs/wundergraph-config-ts-reference) [stellate.ts](https://stellate.co/docs/reference/configuration) [(hasura) config.yaml](https://hasura.io/docs/latest/hasura-cli/config-reference/) [datadog-ci.json](https://docs.datadoghq.com/serverless/libraries_integrations/cli/#configuration-file) [dgraph.yaml](https://dgraph.io/docs/deploy/config/#configuration-file) [MongoDB cluster config](https://www.mongodb.com/docs/atlas/cli/stable/cluster-config-file/) [fly.toml](https://fly.io/docs/reference/configuration/) [Cargo.toml](https://doc.rust-lang.org/cargo/reference/manifest.html) [wrangler.toml](https://developers.cloudflare.com/workers/wrangler/configuration/) [.circleci/config.yml](https://circleci.com/docs/configuration-reference/) [.git](https://git-scm.com/docs/gitrepository-layout) [package.json](https://docs.npmjs.com/cli/v9/configuring-npm/package-json) [railway.toml](https://docs.railway.app/deploy/config-as-code) # usage today `$ rover template use` `$ cd products` `$ npm install` `$ npm run start` `$ rover dev --name products --url http://localhost:4000 --schema schema.graphql` `$ rover subgraph check averys-supercloud@current --name products --schema schema.graphql` `$ railway up` `$ rover subgraph publish averys-supercloud@current --name products --schema schema.graphql --routing-url https://products.averyharnish.com` --- Looking at the usage today, you can see a large number of arguments that are repeated over and over again. New developers not only have to learn difficult federation problems and distributed systems, but they also have to remember the correct arguments across multiple commands that rarely, if ever, change. # desired usage `$ rover template use` `$ cd products` `$ npm install` `$ npm run start` `$ rover subgraph init` `$ rover dev` `$ rover subgraph check` `$ railway up` `$ rover subgraph publish` This usage is much cleaner, the project is created and bootstrapped exactly one time, and that configuration is serialized to disk in a conventional, human readable format that can be committed to version control. Developers can make incremental changes to their projects, and GraphOS will do the rest. --- # Roadmap thoughts 1. Phase 1 - save and read subgraph configuration from disk for dev, checks, and publishes instead of requiring explicit argument usage every time a. `rover subgraph init` creates `.apollo` and a `subgraph.yaml` by prompting the user for the inputs it needs b. The `subgraph.yaml` includes top-level configuration that applies to all variants: `graph_id`, `name`, `schema`, `local_url`, and `default_variant`. `graph_id` correlates to the ID of a graph ref in Studio (create this graph during `init` if it does not exist in studio already). `name` is the name of the subgraph. `schema` gives Rover a way to receive the schema for a subgraph, with introspection via `local_url` _or_ by pointing to a file on disk. `default_variant` specifies a variant that is used by default, if left unspecified, variants will default to `current`. c. The `subgraph.yaml` includes per-variant configuration that only applies to a single variant: `routing_url` is the first that comes to mind. Different variant configuration can be used with subgraph commands by passing a `--variant` argument. d. Environment variable substitution is allowed in `.apollo` much like it is in router configuration `${PORT}` should be usable in `local_url` for instance e. After this, in a directory with a `.apollo/subgraph.yaml`, `rover subgraph check`, `rover dev`, and `rover subgraph publish` should work with 0 arguments. 2. Phase 2 - enable subgraph developers to only modify their subgraph a. `rover dev` now takes a `<GRAPH_REF>` argument and also works in directories with a `.apollo/subgraph.yaml`, and it fetches all subgraphs from a supergraph and spins up a local router that points to a locally running subgraph (no tunneling, no cloud router, just do the thing.) ## Announcement Draft Announcing Configuration as Code for all Subgraph Developers Today we are launching a new feature of GraphOS that adds in-source configuration to improve developer experience and simplify delivery automation. --- ### Later... 1. Introduce a `.apollo/client.yaml` configuration file that is laid out similarly to subgraph style projects, but includes configuration for managing operation collections. Implementation and necessary config TBD, but should follow the same pattern of the subgraph config and commands (`rover client init` and `rover client publish` should initialize and publish operation collections). 2. Do the same for `readme` commands and `contract` commands 3. Allow the decoupling of subgraphs from supergraphs a. Implement subgraphs as entities in the API by allowing subgraph publishes that are not necessarily associated with a supergraph (and may eventually be associated with _multiple_ supergraphs) b. Make `graph_id` optional in `subgraph.yml` c. Introduce a `.apollo/supergraph.yaml` that includes a list of subgraphs to include in the supergraph, governance controls, router configuration, etc. by implementing `rover supergraph init` and `rover supergraph publish`