From 7ceff711cb9492d0ee2528e9fe034db4a6a69666 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ey=C3=BE=C3=B3r=20Magn=C3=BAsson?= Date: Fri, 1 Nov 2019 14:58:39 +0100 Subject: [PATCH 1/2] docs: restructure and add new basic guides --- docs/README.md | 39 +++--- docs/basics/README.md | 14 --- docs/examples/README.md | 5 +- docs/examples/demo-project.md | 8 +- docs/examples/using-garden-in-ci.md | 4 +- docs/guides/README.md | 54 ++++++++ .../cloud-provider-setup.md | 0 .../configuration-files.md | 2 +- .../container-modules.md | 0 .../development-workflows.md | 4 +- docs/{using-garden => guides}/hot-reload.md | 0 .../in-cluster-building.md | 0 .../local-kubernetes.md | 2 +- .../remote-kubernetes.md | 0 docs/{using-garden => guides}/terraform.md | 0 .../using-helm-charts.md | 0 .../using-remote-sources.md | 0 .../variables-and-templating.md | 0 docs/{basics => }/installation.md | 14 ++- docs/{basics => }/quick-start.md | 11 +- docs/reference/README.md | 3 +- docs/reference/commands.md | 1 + docs/reference/config.md | 3 +- docs/reference/glossary.md | 7 +- docs/reference/module-types/README.md | 5 + docs/reference/module-types/container.md | 2 +- docs/reference/module-types/exec.md | 2 +- docs/reference/module-types/helm.md | 2 +- docs/reference/module-types/kubernetes.md | 2 +- .../reference/module-types/maven-container.md | 2 +- docs/reference/module-types/openfaas.md | 2 +- docs/reference/module-types/terraform.md | 4 +- docs/reference/providers/README.md | 4 + docs/reference/providers/kubernetes.md | 2 +- docs/reference/providers/local-kubernetes.md | 2 +- docs/reference/providers/local-openfaas.md | 2 +- docs/reference/providers/maven-container.md | 2 +- docs/reference/providers/openfaas.md | 2 +- docs/reference/providers/terraform.md | 4 +- docs/reference/template-strings.md | 2 +- docs/{basics => }/stack-graph.md | 3 +- docs/troubleshooting.md | 5 + docs/using-garden/README.md | 57 +++------ docs/using-garden/adding-modules.md | 117 ++++++++++++++++++ docs/using-garden/adding-services.md | 111 +++++++++++++++++ docs/using-garden/creating-a-project.md | 115 +++++++++++++++++ docs/using-garden/running-tasks.md | 115 +++++++++++++++++ docs/using-garden/running-tests.md | 108 ++++++++++++++++ garden-service/src/docs/config.ts | 2 +- .../src/docs/templates/base-config.hbs | 3 +- .../src/docs/templates/commands.hbs | 1 + .../src/docs/templates/module-type.hbs | 2 +- .../src/docs/templates/provider.hbs | 2 +- .../src/docs/templates/template-strings.hbs | 2 +- .../src/plugins/terraform/terraform.ts | 4 +- 55 files changed, 740 insertions(+), 119 deletions(-) delete mode 100644 docs/basics/README.md create mode 100644 docs/guides/README.md rename docs/{using-garden => guides}/cloud-provider-setup.md (100%) rename docs/{using-garden => guides}/configuration-files.md (99%) rename docs/{using-garden => guides}/container-modules.md (100%) rename docs/{using-garden => guides}/development-workflows.md (97%) rename docs/{using-garden => guides}/hot-reload.md (100%) rename docs/{using-garden => guides}/in-cluster-building.md (100%) rename docs/{using-garden => guides}/local-kubernetes.md (98%) rename docs/{using-garden => guides}/remote-kubernetes.md (100%) rename docs/{using-garden => guides}/terraform.md (100%) rename docs/{using-garden => guides}/using-helm-charts.md (100%) rename docs/{using-garden => guides}/using-remote-sources.md (100%) rename docs/{using-garden => guides}/variables-and-templating.md (100%) rename docs/{basics => }/installation.md (94%) rename docs/{basics => }/quick-start.md (82%) rename docs/{basics => }/stack-graph.md (98%) create mode 100644 docs/using-garden/adding-modules.md create mode 100644 docs/using-garden/adding-services.md create mode 100644 docs/using-garden/creating-a-project.md create mode 100644 docs/using-garden/running-tasks.md create mode 100644 docs/using-garden/running-tests.md diff --git a/docs/README.md b/docs/README.md index 6eb2414393..b8b9b543e6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,30 +1,35 @@ # Table of Contents -* [Basics](./basics/README.md) - * [Installation](./basics/installation.md) - * [Quick Start](./basics/quick-start.md) - * [Stack Graph](./basics/stack-graph.md) +* [Installation](./installation.md) +* [Quick Start](./quick-start.md) +* [Stack Graph](./stack-graph.md) * [Using Garden](./using-garden/README.md) - * [Cloud Provider Set-up](./using-garden/cloud-provider-setup.md) - * [Configuration Files](./using-garden/configuration-files.md) - * [Container Modules](./using-garden/container-modules.md) - * [Development Workflows](./using-garden/development-workflows.md) - * [Helm Charts](./using-garden/using-helm-charts.md) - * [Hot Reload](./using-garden/hot-reload.md) - * [In-Cluster Building](./using-garden/in-cluster-building.md) - * [Local Kubernetes](./using-garden/local-kubernetes.md) - * [Remote Kubernetes](./using-garden/remote-kubernetes.md) - * [Remote Sources](./using-garden/using-remote-sources.md) - * [Terraform](./using-garden/terraform.md) - * [Variables and templating](./using-garden/variables-and-templating.md) + * [Creating a Project](./using-garden/creating-a-project.md) + * [Adding Modules](./using-garden/adding-modules.md) + * [Adding Services](./using-garden/adding-services.md) + * [Running Tests](./using-garden/running-tests.md) + * [Running Tasks](./using-garden/running-tasks.md) +* [Guides](./guides/README.md) + * [Cloud Provider Set-up](./guides/cloud-provider-setup.md) + * [Configuration Files](./guides/configuration-files.md) + * [Container Modules](./guides/container-modules.md) + * [Development Workflows](./guides/development-workflows.md) + * [Helm Charts](./guides/using-helm-charts.md) + * [Hot Reload](./guides/hot-reload.md) + * [In-Cluster Building](./guides/in-cluster-building.md) + * [Local Kubernetes](./guides/local-kubernetes.md) + * [Remote Kubernetes](./guides/remote-kubernetes.md) + * [Remote Sources](./guides/using-remote-sources.md) + * [Terraform](./guides/terraform.md) + * [Variables and templating](./guides/variables-and-templating.md) * [Example Projects](./examples/README.md) * [Demo Project](./examples/demo-project.md) * [TLS Project](./examples/tls-project.md) * [Using Garden in CI](./examples/using-garden-in-ci.md) * [Reference](./reference/README.md) + * [Glossary](./reference/glossary.md) * [Commands Reference](./reference/commands.md) * [Config Files Reference](./reference/config.md) - * [Glossary](./reference/glossary.md) * [Module Types](./reference/module-types/README.md) * [Container](./reference/module-types/container.md) * [Exec](./reference/module-types/exec.md) diff --git a/docs/basics/README.md b/docs/basics/README.md deleted file mode 100644 index 0faa84b825..0000000000 --- a/docs/basics/README.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -order: 1 ---- -# Basics - -The following articles cover the basics of installing and using Garden: - -* Installation instructions for your platform: [Installation](./installation.md). -* A very brief guide on the main commands you should be familiar with, and an example project to test them in: [Quick Start](./quick-start.md). -* An overview of the Stack Graph, and the framework's main concepts: [The Stack Graph](./stack-graph.md). - -If you're already familiar with the basics, feel free to move on to the next chapter: [Using Garden](../using-garden/README.md). - -Or dive right in by exploring our [configuration files](../using-garden/configuration-files.md) and [Example Projects](../examples/README.md). diff --git a/docs/examples/README.md b/docs/examples/README.md index 3dba0988c0..625df616ac 100644 --- a/docs/examples/README.md +++ b/docs/examples/README.md @@ -1,5 +1,6 @@ --- -order: 3 +order: 6 +title: Example Projects --- # Example Projects @@ -9,7 +10,7 @@ Here we see how to "gardenify" a pre-existing project, creating a project config ## [Using Garden in CI](./using-garden-in-ci.md) -In this example we demonstrate how to use Garden in a CI pipeline to run tests and deploy to preview and staging environments. Note that you'll need to have a [remote Kubernetes cluster](../using-garden/remote-kubernetes.md) set up to complete the steps in the guide. +In this example we demonstrate how to use Garden in a CI pipeline to run tests and deploy to preview and staging environments. Note that you'll need to have a [remote Kubernetes cluster](../guides/remote-kubernetes.md) set up to complete the steps in the guide. ## [TLS project](./tls-project.md) diff --git a/docs/examples/demo-project.md b/docs/examples/demo-project.md index 9fcc97db43..f194c3d8fe 100644 --- a/docs/examples/demo-project.md +++ b/docs/examples/demo-project.md @@ -13,7 +13,7 @@ In what follows you'll learn how to: ## Before you get started -This tutorial assumes that you already have a running [installation of Garden](../basics/installation.md). +This tutorial assumes that you already have a running [installation of Garden](../installation.md). ## Clone the example repo @@ -53,7 +53,7 @@ The task at hand is to configure these services so that they can run on the Gard ## Project-wide configuration -To begin with, every project needs a project-wide `garden.yml` [configuration file](../using-garden/configuration-files.md) at the root level. There we define, among other things, the name of the project, and the [providers](../reference/glossary.md#Provider) the project requires. +To begin with, every project needs a project-wide `garden.yml` [configuration file](../guides/configuration-files.md) at the root level. There we define, among other things, the name of the project, and the [providers](../reference/glossary.md#Provider) the project requires. Let's go ahead and create one: @@ -76,7 +76,7 @@ Above, we've specified the name of our project and configured it to use the `loc ## Module configuration -Now, let's turn to our services. Services live inside [modules](../reference/glossary.md#Module), and each module has its own `garden.yml` configuration file. You can read more about the difference between services and modules [here](../basics/stack-graph.md#structure-and-terminology). +Now, let's turn to our services. Services live inside [modules](../reference/glossary.md#Module), and each module has its own `garden.yml` configuration file. You can read more about the difference between services and modules [here](../stack-graph.md#structure-and-terminology). We'll start with the module for the `frontend`: @@ -134,7 +134,7 @@ services: port: http ``` -The [services](../using-garden/configuration-files.md#Services) field is specific to container modules, and defines the services exposed by the module. In this case, our containerized Node.js server. The other keys tell Garden how to expose our `/hello-frontend` endpoint. +The [services](../guides/configuration-files.md#Services) field is specific to container modules, and defines the services exposed by the module. In this case, our containerized Node.js server. The other keys tell Garden how to expose our `/hello-frontend` endpoint. ## Deploying diff --git a/docs/examples/using-garden-in-ci.md b/docs/examples/using-garden-in-ci.md index 75cba1a5fa..e56dc91a87 100644 --- a/docs/examples/using-garden-in-ci.md +++ b/docs/examples/using-garden-in-ci.md @@ -5,7 +5,7 @@ In this guide we'll demonstrate how Garden can fit into your continuous integrat * Use the same tool and the same set of commands for the entire development cycle, from source to finish. * No need to change your CI configuration when you change your stack since Garden holds the entire stack graph. * The only thing you need to install in CI is the Garden CLI and its dependencies (or use a ready-made Garden container image). -* When using [in-cluster building](../using-garden/in-cluster-building.md) your CI also uses the same build and test result cache as you and your team, which makes for a much faster pipeline. +* When using [in-cluster building](../guides/in-cluster-building.md) your CI also uses the same build and test result cache as you and your team, which makes for a much faster pipeline. To use Garden in your CI pipeline you need the following: @@ -31,7 +31,7 @@ To see it in action, you can fork the repository and follow the set-up steps bel ## Configure remote environments -Configuring Garden to work against a remote Kubernetes cluster is explained step by step in our [Remote Kubernetes guide](../using-garden/remote-kubernetes.md). For this example, we also use [in-cluster building](../using-garden/in-cluster-building.md). +Configuring Garden to work against a remote Kubernetes cluster is explained step by step in our [Remote Kubernetes guide](../guides/remote-kubernetes.md). For this example, we also use [in-cluster building](../guides/in-cluster-building.md). For this project we're using three environments: `local`, `preview` and `staging`. The `local` environment is the default and is configured for a local Kubernetes cluster that runs on the user's machine. The other two run on remote clusters. diff --git a/docs/guides/README.md b/docs/guides/README.md new file mode 100644 index 0000000000..e7fbe6a98b --- /dev/null +++ b/docs/guides/README.md @@ -0,0 +1,54 @@ +--- +order: 5 +title: Guides +--- + +# Guides + +## [Development Workflows](./development-workflows.md) + +In this article we discuss how to set up a new Garden project, the basic development workflow, how Garden's providers work, and the basics of testing and dependencies. + +## [Configuration Files](./configuration-files.md) + +This one is all about Garden's configuration files—an overview of project and module configs, setting up services, and a primer on tests. + +## [Container Modules](./container-modules.md) + +One of the most commonly used module types for Garden is the `container` module type. This guide walks through its usage and configuration. + +## [Local Kubernetes](./local-kubernetes.md) + +Garden works great with local Kubernetes setups. Here you'll find installation and usage instructions for some +common flavors of local Kubernetes setups, such as Minikube, Docker for Desktop and MicroK8s. + +## [Remote Kubernetes](./remote-kubernetes.md) + +Garden can also work smoothly with remote Kubernetes clusters. If you'd like to use a remote cluster, you may have some +additional considerations and requirements. Take a look at this guide for details. + +## [In-cluster Building](./in-cluster-building.md) + +One of Garden's most powerful features is the ability to build images in your Kubernetes development cluster, thus +avoiding the need for local Kubernetes clusters. This guide covers the requirements for in-cluster building and how +to set it up. + +## [Cloud Provider Set-up](./cloud-provider-setup.md) + +Instructions for creating and configuring Kubernetes clusters with GKE (Google), AKS (Azure), EKS and kops (AWS), and how to connect to them with Garden. + +## [Using Helm charts](./using-helm-charts.md) + +The [Helm](https://helm.sh/) package manager is one of the most commonly used tools for managing Kubernetes manifests. Garden supports using your own Helm charts, alongside your container modules. This guide shows you how to use 3rd-party (or otherwise external) Helm charts, as well as your own charts, in your Garden project. We also go through how to configure tests, tasks and hot-reloading for your charts. + +## [Using Remote Sources](./using-remote-sources.md) + +Instructions for how to import code from remote repositories into a Garden project. + +## [Hot Reload](./hot-reload.md) + +This article discusses how to use hot reloading, so that you can update running services on the fly as you make changes to their code, without losing state and without having to destroy and re-create containers. + +## [Terraform](./terraform.md) + +This article discusses how to use the Terraform provider, for provisioning infrastructure as part of your Garden project. diff --git a/docs/using-garden/cloud-provider-setup.md b/docs/guides/cloud-provider-setup.md similarity index 100% rename from docs/using-garden/cloud-provider-setup.md rename to docs/guides/cloud-provider-setup.md diff --git a/docs/using-garden/configuration-files.md b/docs/guides/configuration-files.md similarity index 99% rename from docs/using-garden/configuration-files.md rename to docs/guides/configuration-files.md index 587a093bc0..a86ef955f4 100644 --- a/docs/using-garden/configuration-files.md +++ b/docs/guides/configuration-files.md @@ -1,7 +1,7 @@ # Configuration Files Garden is configured via `garden.yml` configuration files, which Garden collects and compiles into a -[Stack Graph](../basics/stack-graph.md) of your project. +[Stack Graph](../stack-graph.md) of your project. The [project-wide](#project-configuration) `garden.yml` file should be located in the top-level directory of the project's Git repository. diff --git a/docs/using-garden/container-modules.md b/docs/guides/container-modules.md similarity index 100% rename from docs/using-garden/container-modules.md rename to docs/guides/container-modules.md diff --git a/docs/using-garden/development-workflows.md b/docs/guides/development-workflows.md similarity index 97% rename from docs/using-garden/development-workflows.md rename to docs/guides/development-workflows.md index 7ef7802494..2ceea2a199 100644 --- a/docs/using-garden/development-workflows.md +++ b/docs/guides/development-workflows.md @@ -1,7 +1,7 @@ # Development Workflows -Now that you've had a glimpse of the basic Garden commands in the [Quick Start](../basics/quick-start.md) guide, and -learned about the [Stack Graph](../basics/stack-graph.md), let's go through some typical Garden workflows. +Now that you've had a glimpse of the basic Garden commands in the [Quick Start](../quick-start.md) guide, and +learned about the [Stack Graph](../stack-graph.md), let's go through some typical Garden workflows. We'll keep using the [Demo Project](../examples/demo-project.md) example, but the same principles will apply for most Garden projects. diff --git a/docs/using-garden/hot-reload.md b/docs/guides/hot-reload.md similarity index 100% rename from docs/using-garden/hot-reload.md rename to docs/guides/hot-reload.md diff --git a/docs/using-garden/in-cluster-building.md b/docs/guides/in-cluster-building.md similarity index 100% rename from docs/using-garden/in-cluster-building.md rename to docs/guides/in-cluster-building.md diff --git a/docs/using-garden/local-kubernetes.md b/docs/guides/local-kubernetes.md similarity index 98% rename from docs/using-garden/local-kubernetes.md rename to docs/guides/local-kubernetes.md index c77d993d8d..cf66a3bf9a 100644 --- a/docs/using-garden/local-kubernetes.md +++ b/docs/guides/local-kubernetes.md @@ -74,4 +74,4 @@ If you happen to have installed both Minikube and a version of Docker for Mac wi is set as the current context, the first available context is used. (If you're not yet familiar with Garden configuration files, see: -[Configuration files](../using-garden/configuration-files.md)) +[Configuration files](../guides/configuration-files.md)) diff --git a/docs/using-garden/remote-kubernetes.md b/docs/guides/remote-kubernetes.md similarity index 100% rename from docs/using-garden/remote-kubernetes.md rename to docs/guides/remote-kubernetes.md diff --git a/docs/using-garden/terraform.md b/docs/guides/terraform.md similarity index 100% rename from docs/using-garden/terraform.md rename to docs/guides/terraform.md diff --git a/docs/using-garden/using-helm-charts.md b/docs/guides/using-helm-charts.md similarity index 100% rename from docs/using-garden/using-helm-charts.md rename to docs/guides/using-helm-charts.md diff --git a/docs/using-garden/using-remote-sources.md b/docs/guides/using-remote-sources.md similarity index 100% rename from docs/using-garden/using-remote-sources.md rename to docs/guides/using-remote-sources.md diff --git a/docs/using-garden/variables-and-templating.md b/docs/guides/variables-and-templating.md similarity index 100% rename from docs/using-garden/variables-and-templating.md rename to docs/guides/variables-and-templating.md diff --git a/docs/basics/installation.md b/docs/installation.md similarity index 94% rename from docs/basics/installation.md rename to docs/installation.md index bcc7b35185..687e8ef1fc 100644 --- a/docs/basics/installation.md +++ b/docs/installation.md @@ -1,3 +1,7 @@ +--- +order: 1 +title: Installation +--- # Installation This guide will walk you through setting up the Garden framework. @@ -8,7 +12,7 @@ Please follow the guide for your operating system: * [Windows](#windows) * [Linux](#linux) -If you'd like to run Kubernetes locally, please see our [local Kubernetes guide](../using-garden/local-kubernetes.md) +If you'd like to run Kubernetes locally, please see our [local Kubernetes guide](./guides/local-kubernetes.md) for installation and usage information. If you want to install Garden from source, see the instructions in our [contributor guide](https://github.com/garden-io/garden/tree/master/CONTRIBUTING.md). @@ -49,7 +53,7 @@ To install Docker, Kubernetes and kubectl, we recommend Docker for Mac. Please refer to their [installation guide](https://docs.docker.com/engine/installation/) for how to download and install it (which is a pretty simple process). -If you'd like to use a local Kubernetes cluster, please refer to the [local Kubernetes guide](../using-garden/local-kubernetes.md) +If you'd like to use a local Kubernetes cluster, please refer to the [local Kubernetes guide](./guides/local-kubernetes.md) for further information. ## Windows @@ -57,8 +61,8 @@ for further information. You can run Garden on Windows 10 Home, Pro or Enterprise editions. _Note: The Home edition doesn't support virtualization, but you can still use Garden if you're working with -[remote Kubernetes](../using-garden/remote-kubernetes.md) and -[in-cluster building](../using-garden/in-cluster-building.md)._ +[remote Kubernetes](./guides/remote-kubernetes.md) and +[in-cluster building](./guides/in-cluster-building.md)._ To install the Garden CLI and its dependencies, please use our installation script. To run the script, open PowerShell as an administrator and run: @@ -115,7 +119,7 @@ To install Docker, please follow the instructions in the [official documentation ### Step 4 (optional): Local Kubernetes -If you'd like to use a local Kubernetes cluster, please refer to the [local Kubernetes guide](../using-garden/local-kubernetes.md) +If you'd like to use a local Kubernetes cluster, please refer to the [local Kubernetes guide](./guides/local-kubernetes.md) for installation and usage information. ## Using Garden with proxies diff --git a/docs/basics/quick-start.md b/docs/quick-start.md similarity index 82% rename from docs/basics/quick-start.md rename to docs/quick-start.md index 895e6791df..6ae4743958 100644 --- a/docs/basics/quick-start.md +++ b/docs/quick-start.md @@ -1,10 +1,15 @@ +--- +order: 2 +title: Quick Start +--- + # Quick Start This guide will walk you through setting up the Garden framework. It assumes you already have Garden installed. If you don't, please check out our [installation guide](./installation.md). ## Using the CLI -With the CLI installed, we can now try out a few commands using the [Demo Project](../examples/demo-project.md) from our [example projects](../examples/README.md). The example project consists of a couple of basic modules, each defining one service. +With the CLI installed, we can now try out a few commands using the [Demo Project](./examples/demo-project.md) from our [example projects](./examples/README.md). The example project consists of a couple of basic modules, each defining one service. _Note: Check whether Kubernetes is running with `kubectl version`. You should see both a `Client Version` and a `Server Version` in the response. If not, please start it up before proceeding._ @@ -67,8 +72,8 @@ garden dev Go ahead, leave it running and change one of the files in the project, then watch it re-build. -That's it for now. Check out our [Using Garden](../using-garden/README.md) section for other features like hot reload, remote clusters, integration tests, and lots more. +That's it for now. Check out our [Using Garden](./guides/README.md) section for other features like hot reload, remote clusters, integration tests, and lots more. ## Next steps -To see how a Garden project is configured from scratch check, out the [Demo Project](../examples/demo-project.md) guide for a more in-depth presentation. +To see how a Garden project is configured from scratch check, out the [Demo Project](./examples/demo-project.md) guide for a more in-depth presentation. diff --git a/docs/reference/README.md b/docs/reference/README.md index 2d6ea3b1e9..30e4c3b473 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -1,5 +1,6 @@ --- -order: 4 +order: 7 +title: Reference --- # Reference diff --git a/docs/reference/commands.md b/docs/reference/commands.md index 98d41f450d..be6754fea0 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -1,4 +1,5 @@ --- +order: 2 title: Commands Reference --- diff --git a/docs/reference/config.md b/docs/reference/config.md index b5596da0be..cc6a62526c 100644 --- a/docs/reference/config.md +++ b/docs/reference/config.md @@ -1,11 +1,12 @@ --- +order: 3 title: Config Files Reference --- # garden.yml reference Below is the schema reference for the [Project](#project-configuration-keys) and [Module](#module-configuration-keys) `garden.yml` configuration files. For an introduction to configuring a Garden project, -please look at our [configuration guide](../using-garden/configuration-files.md). +please look at our [configuration guide](../guides/configuration-files.md). The reference is divided into four sections. The [first section](#project-configuration-keys) lists and describes the available schema keys for the project level configuration, and the [second section](#project-yaml-schema) contains the project level YAML schema. diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 99dcd89a6b..eff2345463 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -1,3 +1,8 @@ +--- +order: 1 +title: Glossary +--- + # Glossary #### Environment @@ -5,7 +10,7 @@ Represents the current configuration and status of any running services in the [ 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/configuration-files.md#project-configuration). +`garden.yml`](../guides/configuration-files.md#project-configuration). #### Module The unit of building in Garden. A module is defined by its [`garden.yml` configuration file](./config.md), diff --git a/docs/reference/module-types/README.md b/docs/reference/module-types/README.md index 548600580c..09b940f024 100644 --- a/docs/reference/module-types/README.md +++ b/docs/reference/module-types/README.md @@ -1,3 +1,8 @@ +--- +order: 4 +title: Module Types +--- + # Module Types * [Exec](./exec.md) diff --git a/docs/reference/module-types/container.md b/docs/reference/module-types/container.md index 625346585f..02bad37871 100644 --- a/docs/reference/module-types/container.md +++ b/docs/reference/module-types/container.md @@ -13,7 +13,7 @@ other module types like [helm](https://docs.garden.io/reference/module-types/hel [kubernetes](https://github.com/garden-io/garden/blob/master/docs/reference/module-types/kubernetes.md). Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration -guide](../../using-garden/configuration-files.md). +guide](../../guides/configuration-files.md). The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. diff --git a/docs/reference/module-types/exec.md b/docs/reference/module-types/exec.md index cf3c987c47..eee81103db 100644 --- a/docs/reference/module-types/exec.md +++ b/docs/reference/module-types/exec.md @@ -16,7 +16,7 @@ This means that include/exclude filters and ignore files are not applied to loca filtering is done during the sync. Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration -guide](../../using-garden/configuration-files.md). +guide](../../guides/configuration-files.md). The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. diff --git a/docs/reference/module-types/helm.md b/docs/reference/module-types/helm.md index e4bf76c30c..3086d34ffe 100644 --- a/docs/reference/module-types/helm.md +++ b/docs/reference/module-types/helm.md @@ -8,7 +8,7 @@ Specify a Helm chart (either in your repository or remote from a registry) to de Refer to the [Helm guide](https://docs.garden.io/using-garden/using-helm-charts) for usage instructions. Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration -guide](../../using-garden/configuration-files.md). +guide](../../guides/configuration-files.md). The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. diff --git a/docs/reference/module-types/kubernetes.md b/docs/reference/module-types/kubernetes.md index 13cdd8ac3f..28379ad1e7 100644 --- a/docs/reference/module-types/kubernetes.md +++ b/docs/reference/module-types/kubernetes.md @@ -16,7 +16,7 @@ If you need more advanced templating features you can use the [helm](https://docs.garden.io/reference/module-types/helm) module type. Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration -guide](../../using-garden/configuration-files.md). +guide](../../guides/configuration-files.md). The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. diff --git a/docs/reference/module-types/maven-container.md b/docs/reference/module-types/maven-container.md index 550dd42eb9..ac5bfbe645 100644 --- a/docs/reference/module-types/maven-container.md +++ b/docs/reference/module-types/maven-container.md @@ -18,7 +18,7 @@ To use it, make sure to add the `maven-container` provider to your project confi The provider will automatically fetch and cache Maven and the appropriate OpenJDK version ahead of building. Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration -guide](../../using-garden/configuration-files.md). +guide](../../guides/configuration-files.md). The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. diff --git a/docs/reference/module-types/openfaas.md b/docs/reference/module-types/openfaas.md index 97a1b5e74c..de5f8536f5 100644 --- a/docs/reference/module-types/openfaas.md +++ b/docs/reference/module-types/openfaas.md @@ -8,7 +8,7 @@ Deploy [OpenFaaS](https://www.openfaas.com/) functions using Garden. Requires ei `local-openfaas` provider to be configured. Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration -guide](../../using-garden/configuration-files.md). +guide](../../guides/configuration-files.md). The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. diff --git a/docs/reference/module-types/terraform.md b/docs/reference/module-types/terraform.md index af0fe58d88..fbb6f22f69 100644 --- a/docs/reference/module-types/terraform.md +++ b/docs/reference/module-types/terraform.md @@ -18,11 +18,11 @@ configurations, e.g. if you spin up an environment with the Terraform provider, that to configure another provider or other modules via `\${providers.terraform.outputs.}` template strings. -See the [Terraform guide](../../using-garden/terraform.md) for a high-level introduction to the `terraform` +See the [Terraform guide](../../guides/terraform.md) for a high-level introduction to the `terraform` provider. Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration -guide](../../using-garden/configuration-files.md). +guide](../../guides/configuration-files.md). The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. diff --git a/docs/reference/providers/README.md b/docs/reference/providers/README.md index 5e7e32b3d5..649cdf3cf2 100644 --- a/docs/reference/providers/README.md +++ b/docs/reference/providers/README.md @@ -1,3 +1,7 @@ +--- +order: 5 +title: Providers +--- # Providers * [Kubernetes](./kubernetes.md) diff --git a/docs/reference/providers/kubernetes.md b/docs/reference/providers/kubernetes.md index d9222489fb..4f3ccde3a8 100644 --- a/docs/reference/providers/kubernetes.md +++ b/docs/reference/providers/kubernetes.md @@ -4,7 +4,7 @@ title: Kubernetes # `kubernetes` reference -Below is the schema reference for the `kubernetes` provider. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../using-garden/configuration-files.md). +Below is the schema reference for the `kubernetes` provider. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../guides/configuration-files.md). The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. diff --git a/docs/reference/providers/local-kubernetes.md b/docs/reference/providers/local-kubernetes.md index da751fd977..5d78037d9f 100644 --- a/docs/reference/providers/local-kubernetes.md +++ b/docs/reference/providers/local-kubernetes.md @@ -4,7 +4,7 @@ title: Local Kubernetes # `local-kubernetes` reference -Below is the schema reference for the `local-kubernetes` provider. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../using-garden/configuration-files.md). +Below is the schema reference for the `local-kubernetes` provider. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../guides/configuration-files.md). The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. diff --git a/docs/reference/providers/local-openfaas.md b/docs/reference/providers/local-openfaas.md index 810f4d8228..f3541ea922 100644 --- a/docs/reference/providers/local-openfaas.md +++ b/docs/reference/providers/local-openfaas.md @@ -4,7 +4,7 @@ title: Local Openfaas # `local-openfaas` reference -Below is the schema reference for the `local-openfaas` provider. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../using-garden/configuration-files.md). +Below is the schema reference for the `local-openfaas` provider. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../guides/configuration-files.md). The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. diff --git a/docs/reference/providers/maven-container.md b/docs/reference/providers/maven-container.md index 45c0385278..ca39e8432e 100644 --- a/docs/reference/providers/maven-container.md +++ b/docs/reference/providers/maven-container.md @@ -4,7 +4,7 @@ title: Maven Container # `maven-container` reference -Below is the schema reference for the `maven-container` provider. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../using-garden/configuration-files.md). +Below is the schema reference for the `maven-container` provider. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../guides/configuration-files.md). The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. diff --git a/docs/reference/providers/openfaas.md b/docs/reference/providers/openfaas.md index ef3ff2b45f..5a0184a888 100644 --- a/docs/reference/providers/openfaas.md +++ b/docs/reference/providers/openfaas.md @@ -4,7 +4,7 @@ title: Openfaas # `openfaas` reference -Below is the schema reference for the `openfaas` provider. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../using-garden/configuration-files.md). +Below is the schema reference for the `openfaas` provider. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../guides/configuration-files.md). The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. diff --git a/docs/reference/providers/terraform.md b/docs/reference/providers/terraform.md index 3a84b80667..c19f8acf78 100644 --- a/docs/reference/providers/terraform.md +++ b/docs/reference/providers/terraform.md @@ -4,7 +4,7 @@ title: Terraform # `terraform` reference -Below is the schema reference for the `terraform` provider. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../using-garden/configuration-files.md). +Below is the schema reference for the `terraform` provider. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../guides/configuration-files.md). The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. @@ -69,7 +69,7 @@ If set to true, Garden will automatically run `terraform apply -auto-approve` wh Specify the path to a Terraform config directory, that should be resolved when initializing the provider. This is useful when other providers need to be able to reference the outputs from the stack. -See the [Terraform guide](../../using-garden/terraform.md) for more information. +See the [Terraform guide](../../guides/terraform.md) for more information. | Type | Required | | -------- | -------- | diff --git a/docs/reference/template-strings.md b/docs/reference/template-strings.md index 01a90ac0fb..7f17a394af 100644 --- a/docs/reference/template-strings.md +++ b/docs/reference/template-strings.md @@ -5,7 +5,7 @@ title: Template Strings Reference # Template string reference Below you'll find the schema of the keys available when interpolating template strings (see our -[Configuration Files](../using-garden/configuration-files.md) guide for more information and usage examples). +[Configuration Files](../guides/configuration-files.md) guide for more information and usage examples). Note that there are three sections below, since Project configs and Module configs have different keys available to them, and since additional keys are available under `providers` in Project configs. diff --git a/docs/basics/stack-graph.md b/docs/stack-graph.md similarity index 98% rename from docs/basics/stack-graph.md rename to docs/stack-graph.md index a38789b3eb..d8fe3a2880 100644 --- a/docs/basics/stack-graph.md +++ b/docs/stack-graph.md @@ -1,4 +1,5 @@ --- +order: 3 title: Stack Graph --- # The Stack Graph @@ -70,4 +71,4 @@ Note here the first four fields, which are common across all module types—`kin Also notice that the `container` module explicitly declares a service, whereas the `helm` module does not. This is dictated by the module type. Containers often only need to be built (e.g. base images for other containers), or may contain multiple services. A Helm chart, however, is generally a single deployable so the provider makes the service implicit when configuring it. -For more details on how to configure your project, take a look at the [configuration guide](../using-garden/configuration-files.md). +For more details on how to configure your project, take a look at the [configuration guide](./guides/configuration-files.md). diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 7fb04f3b69..3a01356309 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,3 +1,8 @@ +--- +order: 8 +title: Troubleshooting +--- + # Troubleshooting _This section could (obviously) use more work. Contributions are most appreciated!_ diff --git a/docs/using-garden/README.md b/docs/using-garden/README.md index 26c31c7c5a..2009ae9f7b 100644 --- a/docs/using-garden/README.md +++ b/docs/using-garden/README.md @@ -1,52 +1,27 @@ --- -order: 2 +order: 4 +title: Using Garden --- -# Using Garden - -## [Development Workflows](./development-workflows.md) - -In this article we discuss how to set up a new Garden project, the basic development workflow, how Garden's providers work, and the basics of testing and dependencies. - -## [Configuration Files](./configuration-files.md) - -This one is all about Garden's configuration files—an overview of project and module configs, setting up services, and a primer on tests. - -## [Container Modules](./container-modules.md) - -One of the most commonly used module types for Garden is the `container` module type. This guide walks through its usage and configuration. - -## [Local Kubernetes](./local-kubernetes.md) -Garden works great with local Kubernetes setups. Here you'll find installation and usage instructions for some -common flavors of local Kubernetes setups, such as Minikube, Docker for Desktop and MicroK8s. - -## [Remote Kubernetes](./remote-kubernetes.md) - -Garden can also work smoothly with remote Kubernetes clusters. If you'd like to use a remote cluster, you may have some -additional considerations and requirements. Take a look at this guide for details. - -## [In-cluster Building](./in-cluster-building.md) - -One of Garden's most powerful features is the ability to build images in your Kubernetes development cluster, thus -avoiding the need for local Kubernetes clusters. This guide covers the requirements for in-cluster building and how -to set it up. - -## [Cloud Provider Set-up](./cloud-provider-setup.md) - -Instructions for creating and configuring Kubernetes clusters with GKE (Google), AKS (Azure), EKS and kops (AWS), and how to connect to them with Garden. +# Using Garden -## [Using Helm charts](./using-helm-charts.md) +This section contains short guides on the main Garden constructs. They're useful for those getting started with Garden but also for those that need to brush up on these concepts or that haven't started using them. -The [Helm](https://helm.sh/) package manager is one of the most commonly used tools for managing Kubernetes manifests. Garden supports using your own Helm charts, alongside your container modules. This guide shows you how to use 3rd-party (or otherwise external) Helm charts, as well as your own charts, in your Garden project. We also go through how to configure tests, tasks and hot-reloading for your charts. +Each guide serves as a standalone introduction to the concept but it's still recommended that you go through them in order. -## [Using Remote Sources](./using-remote-sources.md) +There's no need to finish them all at once though. By adding a [project configuration](./creating-a-project.md), [modules](./adding-modules.md), and [services](./adding-modules.md), you can already deploy your project with Garden. You can then come back when you're ready to add [tests](./running-tests.md) and [tasks](./running-tasks.md). -Instructions for how to import code from remote repositories into a Garden project. +## [Creating a Project](./creating-a-project.md) +The first step to using Garden is to create a project level `garden.yml` configuration file. You'll learn how in this guide. -## [Hot Reload](./hot-reload.md) +## [Adding Modules](./adding-modules.md) +Modules are the basic unit of building in Garden. In this guide you'll learn how to split your project into modules that Garden can build. -This article discusses how to use hot reloading, so that you can update running services on the fly as you make changes to their code, without losing state and without having to destroy and re-create containers. +## [Adding Services](./adding-services.md) +Services are the basic unit of deployment in Garden. In this guide you'll learn how to add services to your modules so that you can deploy them. -## [Terraform](./terraform.md) +## [Running Tests](./running-tests.md) +This guide shows you how Garden can run your tests for you. -This article discusses how to use the Terraform provider, for provisioning infrastructure as part of your Garden project. +## [Running Tasks](./running-tests.md) +This guide shows you how Garden can run tasks for you, for example database migrations. diff --git a/docs/using-garden/adding-modules.md b/docs/using-garden/adding-modules.md new file mode 100644 index 0000000000..f9ac4936a7 --- /dev/null +++ b/docs/using-garden/adding-modules.md @@ -0,0 +1,117 @@ +--- +order: 3 +title: Adding Modules +--- + +# Adding Modules + +Modules are the basic **unit of building** in Garden. They are usually the first thing you add after creating the project level configuration. + +A module can correspond to a Dockerfile and its associated code, a remote Docker image, a Helm chart, an OpenFaaS function, and more, all depending on the module type. + +Below is a simple example of a module's `garden.yml` (from the [`demo-project`](https://github.com/garden-io/garden/tree/master/examples/demo-project) example project): + +```yaml +kind: Module +name: backend +description: Backend service container +type: container +services: + ... +tasks: + ... +tests: + ... +``` + +## How it Works + +A Garden project is usually split up into the project level `garden.yml` file and several module level configuration files: + +```console +. +├── garden.yml +├── module-a +│   ├── garden.yml +│   └── ... +├── module-b +│   └── garden.yml +│   └── ... +├── module-c +    └── garden.yml +    └── ... +``` + +> It's also possible to [include several modules in the same `garden.yml` file](../guides/configuration-files.md#multiple-modules-in-the-same-file) and/or with the project level configuration. + +Modules must have a type. Different module _types_ behave in different ways. For example, the `container` module type corresponds to a Docker image, either built from a local Dockerfile or pulled from a remote repository. + +Furthermore, modules can have [`services`](./adding-services.md), [`tests`](./running-tests.md) and [`tasks`](./running-tasks.md). + +You use the `garden build` command to build your modules. + +## Modules in the Stack Graph + +Modules correspond to a **build** action in the Stack Graph. + +- **Modules** can depend on other **modules** (via build dependencies). +- **Tasks**, **tests**, and **services** can depend on **modules** (via build dependencies). +- **Services** implicitly depend on the build step of their **parent module** + +## Examples + +You can learn more about different module types in the [module type reference docs](../reference/module-types/README.md). + +### Container Module + +Below is the configuration for a simple container module. Here we're assuming that the the Dockerfile and source files are in the same directory as the `garden.yml` file. + +```yaml +kind: Module +name: backend +description: Backend service container +type: container +``` + +### Multiple Modules in the Same File + +In this example, we declare multiple container modules in the same file. We use the `include` directive to tell Garden where the source code for each modules resides. + +```yaml +kind: Module +name: backend +description: Backend service container +type: container +include: + - ./backend +--- +kind: Module +name: frontend +description: Frontend service container +type: container +include: + - ./frontend +``` + +### Container Module with a Remote Image + +In this example we use the `image` directive to include an external Docker image with the project. This module has no source code of its own. + +```yaml +kind: Module +name: backend +description: Postgres DB container +type: container +image: postgres:11.4-alpine +``` + +## Further Reading + +* [Module type reference docs](../reference/module-types/README.md). +* [Multiple modules in the same configuration file](../guides/configuration-files.md#multiple-modules-in-the-same-file). +* [A guide on the container module type](../guides/container-modules.md). + +## Next Steps + +[Continue reading](./adding-services.md) for an introduction to adding services that Garden can deploy for you. + diff --git a/docs/using-garden/adding-services.md b/docs/using-garden/adding-services.md new file mode 100644 index 0000000000..733ee13f3d --- /dev/null +++ b/docs/using-garden/adding-services.md @@ -0,0 +1,111 @@ +--- +order: 4 +title: Adding Services +--- + +# Services + +Services are the basic **unit of deployment** in Garden. You add them when you want to run your code somewhere. A simple service configuration looks like this: + +```yaml +kind: Module +type: container +services: + - name: backend + ports: + - name: http + containerPort: 8080 +``` + +> Note that not all [modules types](../reference/module-types/README.md) have services. + +## How it Works + +Services belong to modules and you'll usually have a single service per module. You can think of a service as a running instance of your module. + +You deploy your services with the `garden deploy` command. You can also delete services with the `garden delete service` command. And you can get service logs with the `garden logs` command. + +### Calling Services + +> The following is specific to the Kubernetes providers. + +If you specify a `port` for a given service, other services from inside the cluster can reach it. By default, it's reachable from `http://my-service:/`. + +If you specify an `ingress`, your can reach your service from outside the cluster. For example by using the `garden call` command or with `curl`. + +The default ingress for local development is `http://demo-project.local.app.garden/`. You can override this by setting a `hostname` under the `ingress` directive. + +## Services in the Stack Graph + +Services correspond to a **deploy** action in the Stack Graph. + +- Services can depend on tasks and other services +- Tasks and tests can depend on services + +## Examples + +Here are some simple examples of services in Garden. Note that these are specific to Kubernetes. + +### Simple Container Service + +This example shows a backend service with a health check. Notice that it doesn't have an ingress since it's not meant to be reachable from the outside. + +Notice also that the `servicePort` is set to `80`, the default port. This is so that we can call the service directly from within the cluster with `http://backend/my-endpoint`. + +The `containerPort` (the port that the process inside the container is listening on) is set to `8080`. + +Finally, we set an environment variable that's available to the service at runtime, and can be referenced in our code. + +```yaml +kind: Module +type: container +services: + - name: backend + ports: + - name: http + containerPort: 8080 + servicePort: 80 + healthCheck: + httpGet: + path: /healthz + port: http + - env: + # You can access this variable at runtime in your code. + DATABASE_URL: https://my-database:5432/ +``` + +### Frontend Service + +This example shows a frontend service. It has an ingress so that it's reachable from outside the cluster. We've also set a custom `hostname` so that the full path becomes: `http://my-app.my-org/`. + +This service has a dependency on a `backend` service which means it won't be deployed until the `backend` service has been deployed and is responding to health checks. This also means that the service gets re-deployed on changes to the backend. + +```yaml +kind: Module +type: container +services: + - name: frontend + ports: + - name: http + containerPort: 8080 + ingresses: + - path: / + port: http + hostname: my-app.my-org + dependencies: + - backend +``` + +## Advanced + +A container service maps to a Kubernetes [Deployment object](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/). If you specify a `port`, Garden will create a [Service object](https://kubernetes.io/docs/concepts/services-networking/service/) for the Deployment. And if you specify an `ingress`, Garden will create a corresponding Kubernetes [Ingress object](https://kubernetes.io/docs/concepts/services-networking/ingress/). + +By default the Kubernetes provider does a rolling update for deployments. + +## Further Reading + +* For full service configuration by module type, please take a look at our [reference docs](../reference/module-types/README.md). + +## Next Steps + +In the [next section](./running-tests.md), we'll see how Garden can run your tests for you. diff --git a/docs/using-garden/creating-a-project.md b/docs/using-garden/creating-a-project.md new file mode 100644 index 0000000000..9b44e83ec5 --- /dev/null +++ b/docs/using-garden/creating-a-project.md @@ -0,0 +1,115 @@ +--- +order: 2 +title: Creating a Project +--- + +# Creating a Project + +The first step to using Garden is to create a project. You do this by adding a `garden.yml` file in the root directory of your project. + +```yaml +# garden.yml - located in the top-level directory of your project +kind: Project +name: my-project +environments: + - name: local +providers: + - name: local-kubernetes + environments: ["local"] +``` + +## How it Works + +The top-level `garden.yml` file is where project-wide configuration takes place. This includes environment configurations and project variables. Most importantly, it's where you declare and configure the *providers* you want to use for your project ([see below](#providers)). + +Garden treats the directory containing the project configuration as the project's top-level directory. Garden commands that run in subdirectories of the project root are assumed to apply to that project, and commands above/outside a project root will fail—similarly to how Git uses the location of the repo's `.git` directory as the repo's root directory. + +Every Garden command is run against one of the environments defined in the project level `garden.yml` file. You can specify the environment with the `--env` flag or by setting a `defaultEnvironment`. Alternatively, Garden defaults to the first environment in the `garden.yml` file. + +### Providers + +A project consists of one or more **modules** that each has a specific `type`, for example `container` or `kubernetes`. (We talk about adding modules in the [next guide](./adding-modules.md).) **Providers** implement some of the behaviour of these module types. + +Consider a project with the following three environments: + +```yaml + kind: Project + name: my-project + environments: + - name: empty + - name: local + - name: remote +providers: + - name: local-kubernetes + environments: ["local"] + - name: kubernetes + environments: ["remote"] + context: my-context + ... + --- + kind: Module + name: my-module + type: container + ... +``` + +Our choice of providers and their configuration dictates how the module in the example above is handled: + +1. If we run `garden build my-module --env empty`, the `build` handler for the `container` module type will do the build, essentially calling `docker build` behind the scenes. Running `garden deploy` will fail because no provider is configured to handle the deployment. +2. If we run `garden build my-module --env local`, the `local-kubernetes` provider will "step in". It will still build the module via Docker but it will also push the image to the local Kubernetes cluster. Running `garden deploy` will deploy the project to a local Kubernetes cluster such as Minikube or Docker Desktop. +3. If we run `garden build my-module --env remote`, the `kubernetes` provider will take over. It basically does the same thing as the `build` handler for the `local-kubernetes` provider, but requires some extra configuration. Running `garden deploy` will deploy the project to the remote cluster. + +Some of the most commonly used providers are the [local Kubernetes provider](../guides/local-kubernetes.md) and the [remote Kubernetes provider](../guides/remote-kubernetes.md). + +Here's the [full list of supported providers](../reference/providers/README.md). + +## Examples + +### Variables + +Variables defined in the project config are accessible in [template strings](../reference/template-strings.md) for all the project's module configurations. To illustrate, here's the project configuration from the `project-variables` example project: + +```yaml +# examples/project-variables/garden.yml +kind: Project +name: my-project +variables: + # This variable is referenced in the module configs, and overridden in the local project below + service-replicas: 3 +environments: + - name: local + variables: + # We only want one replica of each service when developing locally + service-replicas: 1 + - name: staging +providers: + - name: local-kubernetes + environments: ["local"] + - name: kubernetes + environments: ["staging"] + ... +``` + +... and the configuration for a module in the same project: + +```yaml +# examples/project-variables/backend/garden.yml +kind: Module +name: backend +description: Backend service container +type: container +services: + - name: backend + replicas: ${var.service-replicas} # <- Refers to the variable set in the project config + ... +``` + +## Further Reading + +* [Full project config reference](../reference/config.md). +* [A guide on template strings and setting project wide variables](../guides/variables-and-templating.md). +* [Template string reference](../reference/template-strings.md). + +## Next Steps + +Continue on to the next guide for an introduction to [adding modules](./adding-modules.md), the building blocks of any Garden project. \ No newline at end of file diff --git a/docs/using-garden/running-tasks.md b/docs/using-garden/running-tasks.md new file mode 100644 index 0000000000..3bb20df9c2 --- /dev/null +++ b/docs/using-garden/running-tasks.md @@ -0,0 +1,115 @@ +--- +order: 6 +title: Running Tasks +--- + +# Running Tasks + +You add tasks when you want Garden to execute specific commands before deploying a service or running a test. At its most basic, the configuration looks like this: + + # garden.yml + kind: Module + tasks: + - name: db-init + args: [rake, db:migrate] + - name: db-clear + args: [rake, db:rollback] + +> Note that not all [modules types](../reference/module-types/README.md) support tasks. + +## How it Works + +Tasks belong to modules and each module can have several tasks. A common use case for a task is a database migration. + +Tasks that have _dependents_ (i.e. something that depends on them) are run automatically by Garden. For example, if a service depends on a task being run before it is deployed, then Garden will automatically run that task before deploying the service. Other tasks will need to be run manually. + +Garden caches task results and re-runs the task if its dependencies, have changed. It is therefore recommended that you make sure your tasks are idempotent (i.e. can safely be run multiple times). + +Garden does **not re-run tasks** on changes when in watch mode. That is, when running Garden with the `--watch|-w` flag or when running `garden dev`. + +You can run a task manually with the `garden run task ` command. This will run the task regardless of whether or not the result is cached. + +You can view task results from the dashboard or by running `garden get task-result `. + +Task names must currently be unique across your project. + +## Tasks in the Stack Graph + +Tasks correspond to a **run** action in the Stack Graph. + +- Tasks can depend on other tasks and services. +- Tasks implicitly depend on their parent module's build task. +- Services and tests can depend on tasks. + +## Examples + + +### Database Migration + +Below is an example of a Helm module that uses the `postgresql` Helm chart. The module has a task for initializing the database and another one for clearing it. In the example we use environment variables to set the password. Notice also that the tasks depend on the `postgres` service being deployed. + +```yaml +kind: Module +type: helm +chart: stable/postgresql +... +tasks: + - name: db-init + command: [/bin/sh, -c] + args: [ + psql, + -w, + -U, postgres, + --host, postgres, + --port, 5432, + -d, postgres, + -c "CREATE TABLE IF NOT EXISTS votes (id VARCHAR(255) NOT NULL UNIQUE, vote VARCHAR(255) NOT NULL, created_at timestamp default NULL)" + ] + env: + PGPASSWORD: postgres + dependencies: + - postgres + - name: db-clear + args: [ + psql, + -w, + -U, postgres, + --host, postgres, + --port=5432, + -d, postgres, + -c, "TRUNCATE votes" + ] + env: + PGPASSWORD: postgres + dependencies: + - postgres +``` + +The full example is [available here](https://github.com/garden-io/garden/blob/v0.10.11/examples/vote-helm/postgres/garden.yml). There's [also a version](https://github.com/garden-io/garden/tree/v0.10.11/examples/vote) that uses the `container` module type instead of Helm charts. + +## Advanced + +### Kubernetes Provider + +Tasks are executed in their own Pod inside the project namespace. The Pod is removed once the task has finished running. + +Task results are stored as [ConfigMaps](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/) in the `` namespace with the format `task-result--`. + +To clear cached task results, you currently have to delete the ConfigMaps manually with kubectl. Here's an example of how that's done: + +```console +kubectl delete -n --metadata $(kubectl get configmap -n --metadata -o name | grep task-result) +``` + +### Exec Modules + +The `exec` module type runs tasks locally in your shell. By default, the `exec` module type executes tasks in the Garden build directory (under `.garden/build/`). By setting `local: true`, the tasks are executed in the module +source directory instead. + +## Further Reading + +* For full task configuration by module type, please take a look at our [reference docs](../reference/module-types/README.md). + +## Next Steps + +Take a look at our [Guides section](../guides/README.md) for more of an in-depth discussion on Garden concepts and capabilities. diff --git a/docs/using-garden/running-tests.md b/docs/using-garden/running-tests.md new file mode 100644 index 0000000000..cd62b93c18 --- /dev/null +++ b/docs/using-garden/running-tests.md @@ -0,0 +1,108 @@ +--- +order: 5 +title: Running Tests +--- + +# Running Tests + +You add tests when you want Garden to run your test suites for you. A simple configuration looks like this: + +```yaml +# garden.yml +kind: Module +tests: + - name: unit + args: [npm, run, test:unit] + - name: integ + args: [npm, run, test:integ] + dependencies: + - backend +``` + +> Note that not all [modules types](../reference/module-types/README.md) support tests. + +## How it Works + +Tests belong to modules and each module can have several tests. Because tests are a part of the Stack Graph and dependency aware, you can easily run integration tests that require other parts of your stack to be running. + +Garden caches test results and only re-runs the test if the module the test belongs to, or upstream dependents, have changed. For remote environments, the test results are stored at the cluster level so that the entire team can share the cached results. + +You use the `command` and `args` directives to specify how the test is run. If the execution exits with 0, the test is considered to have passed, otherwise failed. + +If you have expensive tests that you don't want to run on every watch event when in watch mode, you can use the `--skip-tests` flag or, alternatively, specify what tests to run with the `--test-names` flag. + +You can run a test manually with the `garden run test ` command. This will run the test regardless of whether or not the result is cached. + +You can view test results from the dashboard or by running `garden get test-result `. + +## Tests in the Stack Graph + +Tests correspond to a **test** action in the Stack Graph. + +- Tests can depend on services, and tasks. +- Tests implicitly depend on their parent module's build task. +- Currently, nothing else can depend on tests. + +## Examples + +For full test configuration by module type, please take a look at our [reference docs](../reference/module-types/README.md). + +### Integration Testing + +Below is an example of a `frontend` module that has a `unit` test and an `integ` test that depends on a `backend` module. The `integ` test checks whether the frontend gets the correct response from the backend. The example is based on our [vote example project](https://github.com/garden-io/garden/blob/v0.10.11/examples/vote). + +Here's the configuration for `frontend` module: + +```yaml +# garden.yml +kind: Module +type: container +name: frontend +tests: + - name: unit + args: [npm, run, test:unit] + - name: integ + args: [npm, run, test:integ] + timeout: 60 + dependencies: + - backend +``` + +The `integ` test looks like this: + +```javascript +// tests/integ/test.js +describe('POST /vote', () => { + it('respond with message from hello-function', async () => { + const result = await axios.post('', `vote=a`); + expect(result.status).to.eql(200); + }); +}); +``` + +Now when you're in watch mode and make a change to the `frontend`, Garden will re-run both the `unit` and `integ` tests for you. + +If you make a change to the backend `backend` module, Garden will first re-build and re-deploy the `backend`, and then run the `integ` test defined for the `frontend`. + +## Advanced + +### Kubernetes Provider + +Tests are executed in their own Pod inside the project namespace. The Pod is removed once the test has finished running. + +Tests results are stored as [ConfigMaps](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/) in the `garden-system--metadata` namespace with the format `test-result--` and shared across the team. + +To clear cached test results, you currently have to delete the ConfigMaps manually with kubectl. Here's an example: + +```console +kubectl delete -n garden-system--metadata $(kubectl get configmap -n garden-system--metadata -o name | grep test-result) +``` + +### Exec Modules + +The `exec` module type runs tests locally in your shell. By default, the `exec` module type executes tests in the Garden build directory (under `.garden/build/`). By setting `local: true`, the tests are executed in the module +source directory instead. + +## Next Steps + +In the [next section](./running-tasks.md), we'll see how Garden can execute tasks for your. For example populating a database after it has been deployed. \ No newline at end of file diff --git a/garden-service/src/docs/config.ts b/garden-service/src/docs/config.ts index 17703b5fa1..15510fa37a 100644 --- a/garden-service/src/docs/config.ts +++ b/garden-service/src/docs/config.ts @@ -621,7 +621,7 @@ export async function writeConfigReferenceDocs(docsRoot: string) { // Render module type docs const moduleTypeDir = resolve(referenceDir, "module-types") - const readme = ["# Module Types", ""] + const readme = ["---", "order: 4", "title: Module Types", "---", "", "# Module Types", ""] const moduleTypeDefinitions = await garden.getModuleTypeDefinitions() for (const { name } of moduleTypes) { diff --git a/garden-service/src/docs/templates/base-config.hbs b/garden-service/src/docs/templates/base-config.hbs index 6957a5a809..2c91648da6 100644 --- a/garden-service/src/docs/templates/base-config.hbs +++ b/garden-service/src/docs/templates/base-config.hbs @@ -1,11 +1,12 @@ --- +order: 3 title: Config Files Reference --- # garden.yml reference Below is the schema reference for the [Project](#project-configuration-keys) and [Module](#module-configuration-keys) `garden.yml` configuration files. For an introduction to configuring a Garden project, -please look at our [configuration guide](../using-garden/configuration-files.md). +please look at our [configuration guide](../guides/configuration-files.md). The reference is divided into four sections. The [first section](#project-configuration-keys) lists and describes the available schema keys for the project level configuration, and the [second section](#project-yaml-schema) contains the project level YAML schema. diff --git a/garden-service/src/docs/templates/commands.hbs b/garden-service/src/docs/templates/commands.hbs index 6dacfa3c0a..51bebdc7f0 100644 --- a/garden-service/src/docs/templates/commands.hbs +++ b/garden-service/src/docs/templates/commands.hbs @@ -1,4 +1,5 @@ --- +order: 2 title: Commands Reference --- diff --git a/garden-service/src/docs/templates/module-type.hbs b/garden-service/src/docs/templates/module-type.hbs index 35c7632a6f..280a54bd78 100644 --- a/garden-service/src/docs/templates/module-type.hbs +++ b/garden-service/src/docs/templates/module-type.hbs @@ -7,7 +7,7 @@ title: {{{frontmatterTitle}}} {{{docs}}} Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration -guide](../../using-garden/configuration-files.md). +guide](../../guides/configuration-files.md). The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. diff --git a/garden-service/src/docs/templates/provider.hbs b/garden-service/src/docs/templates/provider.hbs index 8c19488d17..9bee5b9a4b 100644 --- a/garden-service/src/docs/templates/provider.hbs +++ b/garden-service/src/docs/templates/provider.hbs @@ -4,7 +4,7 @@ title: {{{frontmatterTitle}}} # `{{{name}}}` reference -Below is the schema reference for the `{{{name}}}` provider. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../using-garden/configuration-files.md). +Below is the schema reference for the `{{{name}}}` provider. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../guides/configuration-files.md). The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. diff --git a/garden-service/src/docs/templates/template-strings.hbs b/garden-service/src/docs/templates/template-strings.hbs index 64a97c18eb..1059c38e35 100644 --- a/garden-service/src/docs/templates/template-strings.hbs +++ b/garden-service/src/docs/templates/template-strings.hbs @@ -5,7 +5,7 @@ title: Template Strings Reference # Template string reference Below you'll find the schema of the keys available when interpolating template strings (see our -[Configuration Files](../using-garden/configuration-files.md) guide for more information and usage examples). +[Configuration Files](../guides/configuration-files.md) guide for more information and usage examples). Note that there are three sections below, since Project configs and Module configs have different keys available to them, and since additional keys are available under `providers` in Project configs. diff --git a/garden-service/src/plugins/terraform/terraform.ts b/garden-service/src/plugins/terraform/terraform.ts index 5df988d412..6d77196468 100644 --- a/garden-service/src/plugins/terraform/terraform.ts +++ b/garden-service/src/plugins/terraform/terraform.ts @@ -37,7 +37,7 @@ const configSchema = providerConfigBaseSchema Specify the path to a Terraform config directory, that should be resolved when initializing the provider. This is useful when other providers need to be able to reference the outputs from the stack. - See the [Terraform guide](../../using-garden/terraform.md) for more information. + See the [Terraform guide](../../guides/terraform.md) for more information. `), // When you provide variables directly in \`terraform\` modules, those variables will // extend the ones specified here, and take precedence if the keys overlap. @@ -81,7 +81,7 @@ export const gardenPlugin = createGardenPlugin({ that to configure another provider or other modules via \`\${providers.terraform.outputs.}\` template strings. - See the [Terraform guide](../../using-garden/terraform.md) for a high-level introduction to the \`terraform\` + See the [Terraform guide](../../guides/terraform.md) for a high-level introduction to the \`terraform\` provider. `, serviceOutputsSchema: joi From 644ab6537e03d7dc9c7e7cb75c55b5d23748ae6b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ey=C3=BE=C3=B3r=20Magn=C3=BAsson?= Date: Wed, 6 Nov 2019 22:03:45 +0100 Subject: [PATCH 2/2] docs: update links after restructure Note: This will fail in CI since the links we're updating haven't breen created yet on docs.garden.io. They will be created automatically though on merge to master, so we can safely ignore the CI check. --- README.md | 16 ++++++++-------- docs/examples/using-garden-in-ci.md | 2 +- docs/reference/config.md | 10 +++++----- docs/reference/module-types/container.md | 4 ++-- docs/reference/module-types/exec.md | 4 ++-- docs/reference/module-types/helm.md | 6 +++--- docs/reference/module-types/kubernetes.md | 4 ++-- docs/reference/module-types/maven-container.md | 4 ++-- docs/reference/module-types/openfaas.md | 4 ++-- docs/reference/module-types/terraform.md | 4 ++-- examples/ambassador/README.md | 2 +- examples/demo-project/README.md | 2 +- examples/gatsby-hot-reload/src/pages/index.js | 2 +- examples/hot-reload/README.md | 2 +- examples/remote-k8s/README.md | 4 ++-- examples/remote-sources/README.md | 2 +- examples/vote-helm/README.md | 2 +- garden-service/src/config/common.ts | 2 +- garden-service/src/config/project.ts | 2 +- .../src/plugins/kubernetes/kubernetes.ts | 2 +- support/install.ps1 | 2 +- support/install.sh | 2 +- 22 files changed, 42 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index c0311c4117..26c6bd851a 100644 --- a/README.md +++ b/README.md @@ -20,17 +20,17 @@ - Spin up your whole stack with a single command, and (optionally) watch for changes. Only what’s needed gets re-built, re-deployed, and/or re-tested, so you get a **much faster feedback loop**. - **Shared development clusters with fast in-cluster building and image caching for Kubernetes.** This allows teams to easily share build and test results, and for CI to become much faster because it can use the same build and test caches as the team. - Get helpful information when your deployments fail. Garden collects events and logs and displays them prominently when issues come up, and strives to "fail fast", so that you don't need to wait for timeouts or dive into kubectl whenever something is wrong. -- Easily write [integration test suites](https://docs.garden.io/using-garden/development-workflows#tests-and-dependencies) that have runtime dependencies. Run tests *before* pushing your code to CI, and avoid having to mock or stub your own services. +- Easily write [integration test suites](https://docs.garden.io/guides/development-workflows#tests-and-dependencies) that have runtime dependencies. Run tests *before* pushing your code to CI, and avoid having to mock or stub your own services. - Define [tasks](https://github.com/garden-io/garden/tree/v0.10.14/examples/tasks) that run as part of your deployment process—e.g. database migrations or scaffolding. -- [Hot reload](https://docs.garden.io/using-garden/hot-reload) lets you near-instantaneously update code and static files in containers as they run, for services that support in-place reloading. -- [Remote sources](https://docs.garden.io/using-garden) support allows your project to automatically pull code from different repositories. +- [Hot reload](https://docs.garden.io/guides/hot-reload) lets you near-instantaneously update code and static files in containers as they run, for services that support in-place reloading. +- [Remote sources](https://docs.garden.io/guides/using-remote-sources) support allows your project to automatically pull code from different repositories. - The built-in web **dashboard** gives you a full overview of your stack (and many more UI features are planned to further aid with development). -- Build, test and deploy Docker containers, [Helm charts](https://docs.garden.io/using-garden/using-helm-charts), OpenFaaS functions and more. +- Build, test and deploy Docker containers, [Helm charts](https://docs.garden.io/guides/using-helm-charts), OpenFaaS functions and more. - An extensible plug-in system ensures you’ll later be able add anything that’s not on the above list, or create custom module types tailored to your needs (*due summer 2019*). ## Installation -*(Check out our documentation for more [detailed instructions](https://docs.garden.io/basics/installation))* +*(Check out our documentation for more [detailed instructions](https://docs.garden.io/installation))* ### macOS @@ -96,8 +96,8 @@ You can find Garden’s full documentation at [https://docs.garden.io](https://d Overview: -- [Basics](https://docs.garden.io/basics)—installation instructions, our quick start guide, and an overview of the main concepts around Garden. -- [Using Garden](https://docs.garden.io/using-garden)—development workflows, Garden configuration files, usage with remote Kubernetes clusters, and setting up hot reload. +- [Using Garden](https://docs.garden.io/basics)—short Guides on incrementally adding the main Garden constructs to your project. +- [Guides](https://docs.garden.io/guides)—development workflows, Garden configuration files, usage with remote Kubernetes clusters, and setting up hot reload. - [Example Projects](https://docs.garden.io/examples)—guides based on some of the [examples](https://github.com/garden-io/garden/tree/v0.10.14/examples). - [Reference](https://docs.garden.io/reference)—glossary, commands reference, configuration files reference, and template strings reference. - [FAQs](https://docs.garden.io/#faqs). @@ -108,7 +108,7 @@ The [examples](https://github.com/garden-io/garden/tree/v0.10.14/examples) folde Garden runs as a developer tool on your machine or in CI, that looks at your source code and configuration files, runs tests, and resolves your changes to update your development environment. Garden can watch your files and run continuously, or you can trigger it manually via the CLI. -For configuration, Garden is centered around the **[Stack Graph](https://docs.garden.io/basics/stack-graph)**, which allows you to fully codify how each part of your stack is built, deployed and tested—making your workflow reproducible and portable. +For configuration, Garden is centered around the **[Stack Graph](https://docs.garden.io/stack-graph)**, which allows you to fully codify how each part of your stack is built, deployed and tested—making your workflow reproducible and portable.

diff --git a/docs/examples/using-garden-in-ci.md b/docs/examples/using-garden-in-ci.md index e56dc91a87..c511f889ea 100644 --- a/docs/examples/using-garden-in-ci.md +++ b/docs/examples/using-garden-in-ci.md @@ -14,7 +14,7 @@ To use Garden in your CI pipeline you need the following: For the purposes of this example we'll be using [CircleCI](https://circleci.com) and deploying to a Google Kubernetes Engine (GKE) cluster. However, the instructions below can easily be applied to other CI platforms and cloud providers. -The guide is based on the [Remote Kubernetes](https://docs.garden.io/using-garden/remote-kubernetes) example. In what follows we assume that you've read that guide and that you have a running Kubernetes cluster to work with. +The guide is based on the [Remote Kubernetes](https://docs.garden.io/guides/remote-kubernetes) example. In what follows we assume that you've read that guide and that you have a running Kubernetes cluster to work with. ## Prerequisites diff --git a/docs/reference/config.md b/docs/reference/config.md index cc6a62526c..3168b4a92a 100644 --- a/docs/reference/config.md +++ b/docs/reference/config.md @@ -61,7 +61,7 @@ The default environment to use when calling commands without the `--env` paramet Specify a list of filenames that should be used as ".ignore" files across the project, using the same syntax and semantics as `.gitignore` files. By default, patterns matched in `.gitignore` and `.gardenignore` files, found anywhere in the project, are ignored when scanning for modules and module sources. Note that these take precedence over the project `module.include` field, and module `include` fields, so any paths matched by the .ignore files will be ignored even if they are explicitly specified in those fields. -See the [Configuration Files guide] (https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories) for details. +See the [Configuration Files guide] (https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories) for details. | Type | Required | Default | | --------------- | -------- | -------------------------------- | @@ -176,7 +176,7 @@ Specify a list of POSIX-style paths or globs that should be scanned for Garden m Note that you can also _exclude_ path using the `exclude` field or by placing `.gardenignore` files in your source tree, which use the same format as `.gitignore` files. See the -[Configuration Files guide](https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories) for details. +[Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories) for details. Also note that specifying an empty list here means _no paths_ should be included. @@ -198,7 +198,7 @@ modules: [modules](#modules) > exclude Specify a list of POSIX-style paths or glob patterns that should be excluded when scanning for modules. -Note that you can also explicitly _include_ files using the `include` field. If you also specify the `include` field, the paths/patterns specified here are filtered from the files matched by `include`. See the [Configuration Files guide](https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories) for details. +Note that you can also explicitly _include_ files using the `include` field. If you also specify the `include` field, the paths/patterns specified here are filtered from the files matched by `include`. See the [Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories) for details. | Type | Required | | --------------- | -------- | @@ -501,7 +501,7 @@ when responding to filesystem watch events, and when staging builds. Note that you can also _exclude_ files using the `exclude` field or by placing `.gardenignore` files in your source tree, which use the same format as `.gitignore` files. See the -[Configuration Files guide](https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories) for details. +[Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories) for details. Also note that specifying an empty list here means _no sources_ should be included. @@ -525,7 +525,7 @@ watch events, and when staging builds. Note that you can also explicitly _include_ files using the `include` field. If you also specify the `include` field, the files/patterns specified here are filtered from the files matched by `include`. See the -[Configuration Files guide](https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories)for details. +[Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories)for details. | Type | Required | | --------------- | -------- | diff --git a/docs/reference/module-types/container.md b/docs/reference/module-types/container.md index 02bad37871..dcf7f6d98a 100644 --- a/docs/reference/module-types/container.md +++ b/docs/reference/module-types/container.md @@ -77,7 +77,7 @@ when responding to filesystem watch events, and when staging builds. Note that you can also _exclude_ files using the `exclude` field or by placing `.gardenignore` files in your source tree, which use the same format as `.gitignore` files. See the -[Configuration Files guide](https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories) for details. +[Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories) for details. Also note that specifying an empty list here means _no sources_ should be included. @@ -101,7 +101,7 @@ watch events, and when staging builds. Note that you can also explicitly _include_ files using the `include` field. If you also specify the `include` field, the files/patterns specified here are filtered from the files matched by `include`. See the -[Configuration Files guide](https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories)for details. +[Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories)for details. | Type | Required | | --------------- | -------- | diff --git a/docs/reference/module-types/exec.md b/docs/reference/module-types/exec.md index eee81103db..753740fd1c 100644 --- a/docs/reference/module-types/exec.md +++ b/docs/reference/module-types/exec.md @@ -80,7 +80,7 @@ when responding to filesystem watch events, and when staging builds. Note that you can also _exclude_ files using the `exclude` field or by placing `.gardenignore` files in your source tree, which use the same format as `.gitignore` files. See the -[Configuration Files guide](https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories) for details. +[Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories) for details. Also note that specifying an empty list here means _no sources_ should be included. @@ -104,7 +104,7 @@ watch events, and when staging builds. Note that you can also explicitly _include_ files using the `include` field. If you also specify the `include` field, the files/patterns specified here are filtered from the files matched by `include`. See the -[Configuration Files guide](https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories)for details. +[Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories)for details. | Type | Required | | --------------- | -------- | diff --git a/docs/reference/module-types/helm.md b/docs/reference/module-types/helm.md index 3086d34ffe..64ccebde1b 100644 --- a/docs/reference/module-types/helm.md +++ b/docs/reference/module-types/helm.md @@ -5,7 +5,7 @@ title: Helm # `helm` reference Specify a Helm chart (either in your repository or remote from a registry) to deploy. -Refer to the [Helm guide](https://docs.garden.io/using-garden/using-helm-charts) for usage instructions. +Refer to the [Helm guide](https://docs.garden.io/guides/using-helm-charts) for usage instructions. Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration guide](../../guides/configuration-files.md). @@ -72,7 +72,7 @@ when responding to filesystem watch events, and when staging builds. Note that you can also _exclude_ files using the `exclude` field or by placing `.gardenignore` files in your source tree, which use the same format as `.gitignore` files. See the -[Configuration Files guide](https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories) for details. +[Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories) for details. Also note that specifying an empty list here means _no sources_ should be included. @@ -96,7 +96,7 @@ watch events, and when staging builds. Note that you can also explicitly _include_ files using the `include` field. If you also specify the `include` field, the files/patterns specified here are filtered from the files matched by `include`. See the -[Configuration Files guide](https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories)for details. +[Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories)for details. | Type | Required | | --------------- | -------- | diff --git a/docs/reference/module-types/kubernetes.md b/docs/reference/module-types/kubernetes.md index 28379ad1e7..eb6a845a5f 100644 --- a/docs/reference/module-types/kubernetes.md +++ b/docs/reference/module-types/kubernetes.md @@ -80,7 +80,7 @@ when responding to filesystem watch events, and when staging builds. Note that you can also _exclude_ files using the `exclude` field or by placing `.gardenignore` files in your source tree, which use the same format as `.gitignore` files. See the -[Configuration Files guide](https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories) for details. +[Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories) for details. Also note that specifying an empty list here means _no sources_ should be included. @@ -104,7 +104,7 @@ watch events, and when staging builds. Note that you can also explicitly _include_ files using the `include` field. If you also specify the `include` field, the files/patterns specified here are filtered from the files matched by `include`. See the -[Configuration Files guide](https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories)for details. +[Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories)for details. | Type | Required | | --------------- | -------- | diff --git a/docs/reference/module-types/maven-container.md b/docs/reference/module-types/maven-container.md index ac5bfbe645..af11d4aa0a 100644 --- a/docs/reference/module-types/maven-container.md +++ b/docs/reference/module-types/maven-container.md @@ -82,7 +82,7 @@ when responding to filesystem watch events, and when staging builds. Note that you can also _exclude_ files using the `exclude` field or by placing `.gardenignore` files in your source tree, which use the same format as `.gitignore` files. See the -[Configuration Files guide](https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories) for details. +[Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories) for details. Also note that specifying an empty list here means _no sources_ should be included. @@ -106,7 +106,7 @@ watch events, and when staging builds. Note that you can also explicitly _include_ files using the `include` field. If you also specify the `include` field, the files/patterns specified here are filtered from the files matched by `include`. See the -[Configuration Files guide](https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories)for details. +[Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories)for details. | Type | Required | | --------------- | -------- | diff --git a/docs/reference/module-types/openfaas.md b/docs/reference/module-types/openfaas.md index de5f8536f5..24527e7244 100644 --- a/docs/reference/module-types/openfaas.md +++ b/docs/reference/module-types/openfaas.md @@ -72,7 +72,7 @@ when responding to filesystem watch events, and when staging builds. Note that you can also _exclude_ files using the `exclude` field or by placing `.gardenignore` files in your source tree, which use the same format as `.gitignore` files. See the -[Configuration Files guide](https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories) for details. +[Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories) for details. Also note that specifying an empty list here means _no sources_ should be included. @@ -96,7 +96,7 @@ watch events, and when staging builds. Note that you can also explicitly _include_ files using the `include` field. If you also specify the `include` field, the files/patterns specified here are filtered from the files matched by `include`. See the -[Configuration Files guide](https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories)for details. +[Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories)for details. | Type | Required | | --------------- | -------- | diff --git a/docs/reference/module-types/terraform.md b/docs/reference/module-types/terraform.md index fbb6f22f69..90bcf2bd33 100644 --- a/docs/reference/module-types/terraform.md +++ b/docs/reference/module-types/terraform.md @@ -86,7 +86,7 @@ when responding to filesystem watch events, and when staging builds. Note that you can also _exclude_ files using the `exclude` field or by placing `.gardenignore` files in your source tree, which use the same format as `.gitignore` files. See the -[Configuration Files guide](https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories) for details. +[Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories) for details. Also note that specifying an empty list here means _no sources_ should be included. @@ -110,7 +110,7 @@ watch events, and when staging builds. Note that you can also explicitly _include_ files using the `include` field. If you also specify the `include` field, the files/patterns specified here are filtered from the files matched by `include`. See the -[Configuration Files guide](https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories)for details. +[Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories)for details. | Type | Required | | --------------- | -------- | diff --git a/examples/ambassador/README.md b/examples/ambassador/README.md index ecf5c35b9b..08642ca91e 100644 --- a/examples/ambassador/README.md +++ b/examples/ambassador/README.md @@ -4,7 +4,7 @@ This example project demonstrates how to use the [Ambassador API Gateway](https: Even though we chose Ambassador for this project, the same principles apply to e.g. [Traefik](https://traefik.io/), which also supports configuring route mappings via service annotations. -The project is based on our [simple-project example](https://github.com/garden-io/garden/tree/v0.9.0-docfix.2/examples/simple-project) and installs Ambassador via the [Helm module type](https://docs.garden.io/reference/module-types/helm). To learn more about using Helm charts with Garden, take a look at our [Helm user guide](https://docs.garden.io/using-garden/using-helm-charts). +The project is based on our [simple-project example](https://github.com/garden-io/garden/tree/v0.9.0-docfix.2/examples/simple-project) and installs Ambassador via the [Helm module type](https://docs.garden.io/reference/module-types/helm). To learn more about using Helm charts with Garden, take a look at our [Helm user guide](https://docs.garden.io/guides/using-helm-charts). ## Usage diff --git a/examples/demo-project/README.md b/examples/demo-project/README.md index 4e97c83d4d..759c0bfc2a 100644 --- a/examples/demo-project/README.md +++ b/examples/demo-project/README.md @@ -1,3 +1,3 @@ # Demo project -A very basic demo project for Garden. Used in the [Quick Start guide](https://docs.garden.io/basics/quick-start). +A very basic demo project for Garden. Used in the [Quick Start guide](https://docs.garden.io/quick-start). diff --git a/examples/gatsby-hot-reload/src/pages/index.js b/examples/gatsby-hot-reload/src/pages/index.js index 7c18d73b63..b0e2ae5c74 100644 --- a/examples/gatsby-hot-reload/src/pages/index.js +++ b/examples/gatsby-hot-reload/src/pages/index.js @@ -5,7 +5,7 @@ import Layout from '../components/layout' const IndexPage = () => (

Hot reload demo

-

We're using Garden's hot reload functionality in combination with Gatsby (running inside a container) to live-update this page.

+

We're using Garden's hot reload functionality in combination with Gatsby (running inside a container) to live-update this page.

) diff --git a/examples/hot-reload/README.md b/examples/hot-reload/README.md index bf9ac29a17..bc2305bb37 100644 --- a/examples/hot-reload/README.md +++ b/examples/hot-reload/README.md @@ -73,4 +73,4 @@ And you can verify the change by running `garden call node-service` again: } ``` -Check out the [docs](https://docs.garden.io/using-garden/hot-reload) for more information on hot-reloading. Hot-reloading also works with spring-boot, for which we have a dedicated [example project](https://github.com/garden-io/garden/tree/master/examples/spring-boot-hot-reload). \ No newline at end of file +Check out the [docs](https://docs.garden.io/guides/hot-reload) for more information on hot-reloading. Hot-reloading also works with spring-boot, for which we have a dedicated [example project](https://github.com/garden-io/garden/tree/master/examples/spring-boot-hot-reload). \ No newline at end of file diff --git a/examples/remote-k8s/README.md b/examples/remote-k8s/README.md index 961b381b48..fab57c2c8b 100644 --- a/examples/remote-k8s/README.md +++ b/examples/remote-k8s/README.md @@ -2,9 +2,9 @@ This project shows how you can configure Garden to work against a remote Kubernetes cluster, in addition to a local cluster. We also go through how to configure TLS for your `container` services, and set up -[in-cluster building](https://docs.garden.io/using-garden/in-cluster-building). +[in-cluster building](https://docs.garden.io/guides/in-cluster-building). -The example follows the [Remote Kubernetes guide](https://docs.garden.io/using-garden/remote-kubernetes). Please look +The example follows the [Remote Kubernetes guide](https://docs.garden.io/guides/remote-kubernetes). Please look at the guide for more details on how to configure your own project. ## Setup diff --git a/examples/remote-sources/README.md b/examples/remote-sources/README.md index 527f790a79..f249d0e8b8 100644 --- a/examples/remote-sources/README.md +++ b/examples/remote-sources/README.md @@ -1,6 +1,6 @@ # Remote sources example project -This example demonstrates how you can import remote sources and remote modules into a Garden project. Take a look at the [Using Remote Sources](https://docs.garden.io/using-garden) section of our docs for more details. +This example demonstrates how you can import remote sources and remote modules into a Garden project. Take a look at the [Using Remote Sources](https://docs.garden.io/guides/using-remote-sources) section of our docs for more details. ## About diff --git a/examples/vote-helm/README.md b/examples/vote-helm/README.md index eb85895b33..f3ae7b226e 100644 --- a/examples/vote-helm/README.md +++ b/examples/vote-helm/README.md @@ -13,7 +13,7 @@ Furthermore, to showcase the chart re-use feature, the `api` and `result` module as a base. For more details on how to use Helm charts, please refer to our -[Helm user guide](https://docs.garden.io/using-garden). +[Helm user guide](https://docs.garden.io/guides/using-helm-charts). The usage and workflow is the same as in the [vote project](../vote/README.md), please refer to that for usage instructions. diff --git a/garden-service/src/config/common.ts b/garden-service/src/config/common.ts index 7295a472cc..1b746bcd3b 100644 --- a/garden-service/src/config/common.ts +++ b/garden-service/src/config/common.ts @@ -30,7 +30,7 @@ export interface DeepPrimitiveMap { // } export const includeGuideLink = - "https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories" + "https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories" export const enumToArray = (Enum) => Object.values(Enum).filter((k) => typeof k === "string") as string[] diff --git a/garden-service/src/config/project.ts b/garden-service/src/config/project.ts index b247937f21..995da91bee 100644 --- a/garden-service/src/config/project.ts +++ b/garden-service/src/config/project.ts @@ -221,7 +221,7 @@ export const projectSchema = joi so any paths matched by the .ignore files will be ignored even if they are explicitly specified in those fields. See the [Configuration Files guide] - (https://docs.garden.io/using-garden/configuration-files#including-excluding-files-and-directories) + (https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories) for details. `), environmentDefaults: environmentConfigSchema diff --git a/garden-service/src/plugins/kubernetes/kubernetes.ts b/garden-service/src/plugins/kubernetes/kubernetes.ts index 468fa864e4..16aa8f26dd 100644 --- a/garden-service/src/plugins/kubernetes/kubernetes.ts +++ b/garden-service/src/plugins/kubernetes/kubernetes.ts @@ -163,7 +163,7 @@ export const gardenPlugin = createGardenPlugin({ name: "helm", docs: dedent` Specify a Helm chart (either in your repository or remote from a registry) to deploy. - Refer to the [Helm guide](https://docs.garden.io/using-garden/using-helm-charts) for usage instructions. + Refer to the [Helm guide](https://docs.garden.io/guides/using-helm-charts) for usage instructions. `, moduleOutputsSchema: helmModuleOutputsSchema, schema: helmModuleSpecSchema, diff --git a/support/install.ps1 b/support/install.ps1 index 532930b37a..966dee1191 100644 --- a/support/install.ps1 +++ b/support/install.ps1 @@ -95,7 +95,7 @@ $ErrorActionPreference = "Stop" # Start here. Write-Host(" Hi! This script will install the Garden CLI, after checking and installing missing dependencies. -Please refer to the Basics section of our documentation at https://docs.garden.io/basics for details. +Please refer to the Installation section of our documentation at https://docs.garden.io/installation for details. Please note that you may need to answer prompts during the installation. diff --git a/support/install.sh b/support/install.sh index f79b22b2c1..bd839fb159 100755 --- a/support/install.sh +++ b/support/install.sh @@ -79,5 +79,5 @@ echo "Add the Garden CLI to your path by adding the following to your .bashrc/.z echo "" echo " export PATH=\$PATH:\$HOME/.garden/bin" echo "" -echo "Head over to our Quick Start guide for next steps: https://docs.garden.io/basics/quick-start" +echo "Head over to our Quick Start guide for next steps: https://docs.garden.io/quick-start" echo "" \ No newline at end of file