| order | title |
|---|---|
2 |
The Stack Graph (Terminology) |
Garden centers around the Stack Graph, which allows you to describe your whole stack in a consistent, structured way, without creating massive scripts or monolithic configuration files.
We believe your configuration should be distributed, like your stack, so your configuration files are located next to each item described (such as container image, Helm chart, manifests and function). Garden scans for these configuration files, even across multiple repositories, validates them and compiles them into a graph that describes all the steps involved in building, deploying and testing your application.
Garden uses the graph to detect when actions need to be re-run by comparing your current code with previously built, deployed and tested versions.
The Stack Graph is essentially an opinionated graph structure, with a handful of pre-defined entity types and verbs:
- Project: The root of the graph. Contains one or more actions and configures providers.
- Provider: Providers are configured at the project level. They take care of initializing deployment environments, and control what happens within each node of the graph, e.g. how actions are built, deployed or tests run etc. They also specify action types and how they are configured.
- Actions are divided into four different kinds. Each specifies a type (e.g.
containerorhelm) which dictates how it is executed.- Build: A build action describes something you build.
- Deploy: A deploy is something you deploy and expect to stay up and running.
- Run: A run is something you run and wait for to finish.
- Test: A test is also something you run and wait for to finish, similar to tasks, but with slightly different semantics and separate commands for execution.
Each part of your stack describes itself using a simple configuration file. Garden collects all those declarations, validates, and compiles them into a DAG (a directed acyclic graph, meaning it must have no circular dependencies).
Additionally, Garden supports Workflows, which allow you to define a CI-like sequence of Garden commands and scripts to perform.
For more detail on all of the above, see the Using Garden section.
Importantly, what happens (building, deploying, running, etc) within each of the actions that the graph describes is completely pluggable via the providers. The Stack Graph is only opinionated in terms of flows and dependencies—what should happen when—but the how is pluggable.
All the Garden plugins are currently built-in; we will soon release a plugin SDK to allow any user to easily make their own plugins.
Garden generates a Garden version for each action, based on a hash of the source files and configuration involved, as well as any build and runtime dependencies. When using Garden, you'll see various instances of v-<some hash> strings scattered around logs, e.g. when building, deploying, running tests etc.
These versions are used by Garden and the Stack Graph to work out which actions need to be performed whenever you want to build, deploy, run a workflow, test your project etc. Specifically, Garden uses these generated versions to see which builds need to be performed, whether a deploy is up-to-date or a test has already been run, and so on.
Each version also factors in the versions of every dependency (both build and runtime dependencies, as is applicable for each case). This means that anytime a version of something that is depended upon changes, every dependant's version also changes.
For example if the source code of a container build action is changed it's version will change. The deploy action
referencing the build will also have a new version due it being dependant on the build. Any tests referencing the
deploy will also have new versions.
Head over to the Quickstart guide section to learn the basics on how to get up and running with Garden.
If you or your team has already set up a Garden project, you can also skip over to the Using Garden section, to learn more about the concepts and how to interact with Garden.