diff --git a/docs/README.md b/docs/README.md index 3b1b9933f8..f36c46ec52 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,7 +6,7 @@ * [How Garden Works](./basics/how-garden-works.md) * [Quickstart Guide](./basics/quickstart.md) -* [The Stack Graph (Terminology)](./basics/stack-graph.md) +* [Core Concepts](./basics/core-concepts.md) * [Garden vs Other Tools](./basics/garden-vs-other-tools.md) ## 🌳 Garden Seeds @@ -155,7 +155,6 @@ * [Custom Command template context](./reference/template-strings/custom-commands.md) * [Workflow template context](./reference/template-strings/workflows.md) * [Template Helper Functions](./reference/template-strings/functions.md) -* [Glossary](./reference/glossary.md) * [Commands](./reference/commands.md) * [Project Configuration](./reference/project-config.md) * [ConfigTemplate Reference](./reference/config-template-config.md) diff --git a/docs/basics/README.md b/docs/basics/README.md index a0c11ab1e3..ff11bd5bfe 100644 --- a/docs/basics/README.md +++ b/docs/basics/README.md @@ -3,9 +3,3 @@ order: 1 title: Basics --- -# Basics - -* [How Garden Works](./how-garden-works.md) -* [The Stack Graph (Terminology)](./stack-graph.md) -* [Quickstart Guide](./quickstart.md) - diff --git a/docs/basics/core-concepts.md b/docs/basics/core-concepts.md new file mode 100644 index 0000000000..46052ed17d --- /dev/null +++ b/docs/basics/core-concepts.md @@ -0,0 +1,79 @@ +--- +order: 2 +title: Core Concepts +--- + +Below you'll find a definition of all the core Garden concepts. + +### Garden CLI +An open-source standalone binary that's responsible for parsing **Garden config** and executing the **actions** defined there. + +### Web dashboard +A [free web app](https://app.garden.io) that's a part of our community tier that adds functionality to the Garden CLI such as storing command results, displaying logs, and more. + +### Garden config +A YAML config file with the ending `garden.yml` that includes some Garden configuration. + +### Project +The top-level unit of organization in Garden. A project consists of a project-level **Garden config** file and zero or more **actions**. + +A project can be a monorepo or span multiple repositories. + +Garden CLI commands are run in the context of a project. + +### Environment +The second level of organization in Garden after **project**. + +Each environment includes zero or more **providers** and can be used to set variables for the **actions** that belong to it. + +Environments can also be used to toggle what actions are used. For example, a Deploy action of type `helm` could be used to deploy an ephemeral database for a dev environment while a Deploy action of type `terraform` could be used to spin up a cloud managed database for a staging environment. + +### Plugin +Plugins are responsible for executing a given **action**. + +Garden has built-in plugins for Kubernetes, Helm, Pulumi, local scripts, and more, and we plan on releasing a PluginSDK that allows users to add their own. + +### Provider +The part of a Garden **plugin** that holds the main configuration and knows how to handle a given **action** type. + +For example, Garden has a `kubernetes` provider for remote environments and a `local-kubernetes` provider for local environments. Both can deploy an action of type `helm` but will handle them differently. + +Providers are listed in the project-level Garden config and are scoped to **environments**. + +### Action +Actions are core to how Garden works and the most basic unit of organization. They are the "atoms" of a Garden project and form the nodes of **the Stack Graph**. + +There are four actions _kinds_: +- **Build**: describes something you build. +- **Deploy**: something you deploy and expect to stay up and running. +- **Run**: something you run and wait for to finish. +- **Test**: also something you run and wait for to finish, similar to tasks, but with slightly different semantics and separate commands for execution. + +Running `garden build` will e.g. execute all the Build actions for that project (i.e., it will build the project). + +Similarly, actions have _types_ (e.g. `container`, `helm`, `exec`) that dictate how they're executed. + +Actions may define dependencies on other actions. For example, if a given Deploy action depends on a given Build, Garden will first execute the Build action and then the Deploy. Actions can also reference output from other actions. + +This is a powerful concept that allows you to model a system of almost any complexity by just focusing on a single part at a time. + +### Stack Graph +A DAG (_directed acyclic graph_) that the **actions** and their dependencies make up for a given **project** and **environment**. + +You can think of it as a blueprint of how to go from zero to a running system in a single command. + +### Versions +Garden generates a Garden version for each action, based on the source files and configuration involved, as well as any upstream dependencies. When using Garden, you'll see various instances of v- 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, or test your project. + +Each version also factors in the versions of every dependency. 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 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 and any Test actions referencing the Deploy will also have new versions. + +### Caching +Garden tracks the version of every file that belongs to a given **action** (and its upstream dependencies). + +Thanks to this and the graph structure, Garden can be very smart about what actions are actually need to be executed when running tests or deploying to existing environments. + +For example, when running the `garden test` command, Garden will figure out exactly what parts of the graph have changed and only execute the required actions but skip the others. diff --git a/docs/basics/stack-graph.md b/docs/basics/stack-graph.md deleted file mode 100644 index 5c027ea684..0000000000 --- a/docs/basics/stack-graph.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -order: 2 -title: The Stack Graph (Terminology) ---- - -# 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. - -## Structure and terminology - -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. `container` or `helm`) 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](../using-garden/workflows.md), 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](../using-garden/README.md) section. - -## Pluggability - -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. - -## Versions - -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-` 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. - -## Next Steps - -Head over to the [Quickstart guide](./quickstart.md) 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. diff --git a/docs/misc/faq.md b/docs/misc/faq.md index 9b19d2cd64..35997e8a74 100644 --- a/docs/misc/faq.md +++ b/docs/misc/faq.md @@ -41,7 +41,7 @@ See this [GitHub issue](https://github.com/garden-io/garden/issues/1954) for mor ### What do all those `v-` versions mean, and why are they different between building and deploying? -These are the _Garden versions_ that are computed for each action in the Stack Graph at runtime, based on source files and configuration for each action. See [here](../basics/stack-graph.md#versions) for more information about how these work and how they're used. +These are the _Garden versions_ that are computed for each action in the Stack Graph at runtime, based on source files and configuration for each action. See [here](../basics/core-concepts.md#versions) for more information about how these work and how they're used. You may notice that a version of a Build action is different from the version the Deploy for that Build. This is because the Deploy's version also factors in the runtime configuration for that deploy, which often differs between environments, but we don't want those changes to require a rebuild. diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md deleted file mode 100644 index 4d1046c116..0000000000 --- a/docs/reference/glossary.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -order: 6 -title: Glossary ---- - -# Glossary - -#### Environment -Represents the current configuration and status of any running services in the [project](#project), which may be -inspected and modified via the Garden CLI's `environment` command. - -Several named environment configurations may be defined (e.g. _dev_, _testing_, ...) in the [project's -`garden.yml`](../using-garden/projects.md). - -#### Module -The unit of building in Garden. A module is defined by its [`garden.yml` configuration file](../using-garden/configuration-overview.md), -located in the module's top-level directory. - -Each module has a plugin type, and may define one or more [services](#service). - -Essentially, a project is organized into modules at the granularity of its *build* steps. A module's build step may -depend on one or more other modules having already been built, as specified in its `garden.yml`, in which case those modules will be built -first, and their build output made available to the requiring module's build step. - -#### Project -The top-level unit of organization in Garden. A project consists of one or more [modules](#module), along with a -project-level [`garden.yml` configuration file](./project-config.md). - -Garden CLI commands are run in the context of a project, and are aware of all its configuration, modules and services. - -#### Provider -An implementation of a plugin type (e.g. `local-kubernetes` for the `container` plugin). - -Whenever "a module's type" is mentioned in the documentation, what's meant is "which provider will handle this module?" Providers are responsible for implementing a module type's behaviors—e.g. how to build, deploy or test the module. Providers need to be specified for all the module types used in the project. - -For example, both the `local-kubernetes` and `kubernetes` providers (`kubernetes` is the provider for remote Kubernetes) implement the `container` module type, but they handle deployments differently. `local-kubernetes` deploys to a local cluster, where `kubernetes` deploys to a remote cluster. - -For a comprehensive list of providers available in Garden, check out the [References](../reference/README.md) - -#### Service -The unit of deployment in Garden. Services are defined in their parent [module](#module)'s `garden.yml`, each -exposing [one or more ingress endpoints](../reference/module-types/container.md#servicesingresses). - -Services may depend on services defined in other modules, in which case those services will be deployed first, and -their deployment output made available to the requiring service's deploy step. diff --git a/docs/using-garden/configuration-overview.md b/docs/using-garden/configuration-overview.md index 1dcb543d6c..981d24cd05 100644 --- a/docs/using-garden/configuration-overview.md +++ b/docs/using-garden/configuration-overview.md @@ -6,7 +6,7 @@ title: Configuration Overview # Configuration Overview Garden is configured via `garden.yml` (or `*.garden.yml`) configuration files, which Garden collects and compiles into a -[Stack Graph](../basics/stack-graph.md) of your project. +[Stack Graph](../basics/core-concepts.md#stackgraph) of your project. The [project configuration](./projects.md) file should be located in the top-level directory of the project's Git repository. We suggest naming it `project.garden.yml` for clarity, but you can also use `garden.yml` or any filename ending with `.garden.yml`. diff --git a/docs/welcome.md b/docs/welcome.md index 45a7a2c03e..1d29dfed25 100644 --- a/docs/welcome.md +++ b/docs/welcome.md @@ -14,7 +14,7 @@ Here you'll find (hopefully) everything you need to know on how to set up and us * Next, go through the [Your First Project tutorial](./tutorials/your-first-project/README.md). This tutorial helps you create configuration for an example project that you can then apply to your own. And if you get stuck, don't hesitate to reach out to our [our Discord community](https://discord.gg/FrmhuUjFs6). * Finally, check-out our [Adopting Garden guide](./guides/adopting-garden.md) which gives you a high-level overview of how to adopt Garden and roll it out to your team. -**If your team has already set up a project for Garden**, and you just need to learn how to use the Garden CLI, you may find it helpful to skip straight to the [Installation](./basics/quickstart.md#step-1-install-garden) and [Using the CLI](./using-garden/using-the-cli.md) guides, but we do still recommend learning [How Garden Works](./basics/how-garden-works.md) and about [The Stack Graph and the general terminology](./basics/stack-graph.md). +**If your team has already set up a project for Garden**, and you just need to learn how to use the Garden CLI, you may find it helpful to skip straight to the [Installation](./basics/quickstart.md#step-1-install-garden) and [Using the CLI](./using-garden/using-the-cli.md) guides, but we do still recommend learning [How Garden Works](./basics/how-garden-works.md) and about [the core Garden concepts](./basics/core-concepts.md). **If you need help as an open source user**, please get in touch via [our Discord community](https://discord.gg/FrmhuUjFs6). Our team monitors it closely, and we encourage you to reach out with questions about Garden.