From 22e9757e437629a85514fc1d70921772abc6425b 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] docs: restructure and add new basic guides (wip) --- docs/README.md | 39 +++--- docs/basics/README.md | 14 -- docs/examples/README.md | 3 +- docs/guides/README.md | 53 +++++++ .../cloud-provider-setup.md | 0 .../configuration-files.md | 0 .../container-modules.md | 0 .../development-workflows.md | 0 docs/{using-garden => guides}/hot-reload.md | 0 .../in-cluster-building.md | 0 .../local-kubernetes.md | 0 .../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 | 4 + docs/{basics => }/quick-start.md | 5 + docs/reference/README.md | 3 +- docs/reference/commands.md | 1 + docs/reference/config.md | 1 + docs/reference/glossary.md | 5 + docs/reference/module-types/README.md | 5 + docs/reference/providers/README.md | 4 + docs/{basics => }/stack-graph.md | 1 + docs/troubleshooting.md | 5 + docs/using-garden/README.md | 52 +------ docs/using-garden/adding-modules.md | 108 +++++++++++++++ docs/using-garden/adding-services.md | 107 ++++++++++++++ docs/using-garden/creating-a-project.md | 131 ++++++++++++++++++ docs/using-garden/running-tasks.md | 107 ++++++++++++++ docs/using-garden/running-tests.md | 105 ++++++++++++++ garden-service/src/docs/config.ts | 10 +- .../src/docs/templates/base-config.hbs | 1 + .../src/docs/templates/commands.hbs | 1 + 35 files changed, 682 insertions(+), 83 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 (100%) rename docs/{using-garden => guides}/container-modules.md (100%) rename docs/{using-garden => guides}/development-workflows.md (100%) 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 (100%) 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 (99%) rename docs/{basics => }/quick-start.md (98%) rename docs/{basics => }/stack-graph.md (99%) 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 049ef8557b..6095ec1540 100644 --- a/docs/examples/README.md +++ b/docs/examples/README.md @@ -1,5 +1,6 @@ --- -order: 3 +order: 6 +title: Example Projects --- # Example Projects diff --git a/docs/guides/README.md b/docs/guides/README.md new file mode 100644 index 0000000000..14a3911c9a --- /dev/null +++ b/docs/guides/README.md @@ -0,0 +1,53 @@ +--- +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 100% rename from docs/using-garden/configuration-files.md rename to docs/guides/configuration-files.md 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 100% rename from docs/using-garden/development-workflows.md rename to docs/guides/development-workflows.md 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 100% rename from docs/using-garden/local-kubernetes.md rename to docs/guides/local-kubernetes.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 99% rename from docs/basics/installation.md rename to docs/installation.md index bcc7b35185..232c406565 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. diff --git a/docs/basics/quick-start.md b/docs/quick-start.md similarity index 98% rename from docs/basics/quick-start.md rename to docs/quick-start.md index 895e6791df..340526aaa5 100644 --- a/docs/basics/quick-start.md +++ b/docs/quick-start.md @@ -1,3 +1,8 @@ +--- +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). 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 23cd6833c8..23b380e37b 100644 --- a/docs/reference/config.md +++ b/docs/reference/config.md @@ -1,4 +1,5 @@ --- +order: 3 title: Config Files Reference --- diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 99dcd89a6b..e1e3dae0ce 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -1,3 +1,8 @@ +--- +order: 1 +title: Glossary +--- + # Glossary #### Environment 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/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/basics/stack-graph.md b/docs/stack-graph.md similarity index 99% rename from docs/basics/stack-graph.md rename to docs/stack-graph.md index a38789b3eb..d5dff9a79e 100644 --- a/docs/basics/stack-graph.md +++ b/docs/stack-graph.md @@ -1,4 +1,5 @@ --- +order: 3 title: Stack Graph --- # The Stack Graph 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..de2895a16d 100644 --- a/docs/using-garden/README.md +++ b/docs/using-garden/README.md @@ -1,52 +1,6 @@ --- -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 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. +## TODO \ No newline at end of file diff --git a/docs/using-garden/adding-modules.md b/docs/using-garden/adding-modules.md new file mode 100644 index 0000000000..9a06e9926f --- /dev/null +++ b/docs/using-garden/adding-modules.md @@ -0,0 +1,108 @@ +--- +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](https://github.com/garden-io/garden/tree/master/examples/demo-project)) example project): + +``` +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]([https://docs.garden.io/using-garden/configuration-files#multiple-modules-in-the-same-file](https://docs.garden.io/using-garden/configuration-files#multiple-modules-in-the-same-file)) and/or with the project level configuration. + +Modules must have a type and 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` , `tests` and `tasks`. + +You use the `garden build` command to build your modules. + +Check out our [container module guide]([https://docs.garden.io/using-garden/container-modules](https://docs.garden.io/using-garden/container-modules)) for more information. + +## Modules in the Stack Graph + +Modules correspond to a **build** action in the Stack Graph. + +- Modules can depend on other modules (via a build dependency) +- Tasks, tests, and services can depend on modules (via a build dependency) +- 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](#todo) + +### Container Module + +Below is the configuration for a simple container module. Here we're assuming that the source code is 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 it's own + +```yaml +kind: Module +name: backend +description: Postgres DB container +type: container +image: postgres:11.4-alpine +``` \ No newline at end of file diff --git a/docs/using-garden/adding-services.md b/docs/using-garden/adding-services.md new file mode 100644 index 0000000000..51e75c409b --- /dev/null +++ b/docs/using-garden/adding-services.md @@ -0,0 +1,107 @@ +--- +order: 4 +title: Adding Services +--- + +# Services + +You add services when you have something to deploy. 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. A service is the entity that Garden deploys. You can think of a service as a running version of your module. + +You deploy your services with the `garden deploy` command. You can also delete services with the `garden delete service` command. + +You can get service logs with the `garden logs` command. + +A service is deployed once it's responding to health checks or, provider specific status checks if no health check is set. + +### Kubernetes Specific Configuration + +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 + +For full service configuration by module type, please take a look at our [reference docs](https://www.notion.so/reference/module-types/README.md). + +### Backend 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 your 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 + +### Kubernetes Providers + +A 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. \ No newline at end of file diff --git a/docs/using-garden/creating-a-project.md b/docs/using-garden/creating-a-project.md new file mode 100644 index 0000000000..32cda8672f --- /dev/null +++ b/docs/using-garden/creating-a-project.md @@ -0,0 +1,131 @@ +--- +order: 2 +title: Creating a Project +--- + +# Creating a Project + +The first step to get started using Garden is to add a `garden.yml` file at the root of your project. Here's a basic example: + +```yaml +# garden.yml - located in the top-level directory of your project +kind: Project +name: my-project +environments: + - name: local + providers: + - name: local-kubernetes +``` + +## 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)[#picking a provider]. + +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 in 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 *type* (we talk about adding modules in the [next guide](./adding-modules). For example `container` or `kubernetes`. 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 + providers: + - name: local-kubernetes + - name: remote + providers: + - name: kubernetes + context: my-context + ... + --- + kind: Module + name: my-module + type: container + ... +``` + +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. + +### Picking a Provider + +With this in mind, you pick providers based on how you want to "handle" your module types. The top choices are currently the [local Kubernetes provider]([https://docs.garden.io/using-garden/local-kubernetes](https://docs.garden.io/using-garden/local-kubernetes)) and the [remote Kubernetes provider]([https://docs.garden.io/using-garden/remote-kubernetes](https://docs.garden.io/using-garden/remote-kubernetes)). + +Here's the [full list of supported providers]([https://docs.garden.io/reference/providers](https://docs.garden.io/reference/providers)). + +## Examples + +Take a look at our [config file reference docs]([https://docs.garden.io/reference/config](https://docs.garden.io/reference/config)) for the full project config reference. + +### Variables + +Variables defined in the project config are accessible in template strings 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 + providers: + - name: local-kubernetes + variables: + # We only want one replica of each service when developing locally + service-replicas: 1 + - name: testing + providers: + - name: kubernetes + ... +``` + +... 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 + ... +``` + +### Sharing Environment Config + +It's possible to share environment configs between providers. This is useful if the same provider configuration is shared between environments. + +```yaml +kind: Project +name: my-project +environments: + - name: local + variables: + service-replicas: 1 + name: staging + variables: + service-replicas: 3 + name: prod + variables: + service-replicas: 5 +providers: + - name: local-kubernetes + environments: [local] + - name: kubernetes + environments: [staging, prod] + ... +``` + +Continue on to the next guide for an introduction to [adding modules](./adding-modules), 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..0b3aca79e8 --- /dev/null +++ b/docs/using-garden/running-tasks.md @@ -0,0 +1,107 @@ +--- +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. + +Garden caches tasks results and re-runs the task if the module the task belongs to, or upstream dependents, have changed. It is therefore recommended that tasks are idempotent. + +Garden does **not re-run tasks** on changes when in watch mode. + +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. + +// TODO Use an image? + +- Tasks can depend on other tasks and services. +- Services and tests can depend on tasks. + +## Examples + +For full task configuration by module type, please take a look at our [reference docs](https://www.notion.so/reference/module-types/README.md). + +### 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 `db` 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 Module + +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. \ No newline at end of file diff --git a/docs/using-garden/running-tests.md b/docs/using-garden/running-tests.md new file mode 100644 index 0000000000..08de132ace --- /dev/null +++ b/docs/using-garden/running-tests.md @@ -0,0 +1,105 @@ +--- +order: 5 +title: Running Tests +--- + +# Running Tests + +You add tests when you want Garden to run your test suite 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 it 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. + +// TODO Use an image? + +- Tests can depend on modules, services, and tasks. +- Nothing depends on tests. + +## Examples + +For full test configuration by module type, please take a look at our [reference docs](https://www.notion.so/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 Module + +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. \ No newline at end of file diff --git a/garden-service/src/docs/config.ts b/garden-service/src/docs/config.ts index b96cd85bb8..ba95c6a091 100644 --- a/garden-service/src/docs/config.ts +++ b/garden-service/src/docs/config.ts @@ -608,7 +608,15 @@ 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..bc3e7ca437 100644 --- a/garden-service/src/docs/templates/base-config.hbs +++ b/garden-service/src/docs/templates/base-config.hbs @@ -1,4 +1,5 @@ --- +order: 3 title: Config Files Reference --- 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 ---