From 3de331f3f5d723f1d6d17a82d0cf32e3a26be4ee Mon Sep 17 00:00:00 2001 From: Thorarinn Sigurdsson Date: Tue, 26 Mar 2019 21:22:58 +0100 Subject: [PATCH] docs: fixes and updates --- README.md | 24 ++--- docs/basics/README.md | 2 +- docs/basics/installation.md | 23 ++--- docs/basics/quick-start.md | 6 +- docs/basics/stack-graph.md | 8 +- docs/reference/glossary.md | 18 ++-- docs/using-garden/README.md | 10 +- docs/using-garden/configuration-files.md | 69 +++++++------- docs/using-garden/features-and-usage.md | 114 +++++++++++++---------- docs/using-garden/hot-reload.md | 10 +- docs/using-garden/remote-clusters.md | 2 + garden-service/package-lock.json | 52 +++-------- 12 files changed, 165 insertions(+), 173 deletions(-) diff --git a/README.md b/README.md index 4775fb77d9..63d8688066 100644 --- a/README.md +++ b/README.md @@ -14,9 +14,9 @@ With the Stack Graph, each part of your stack can _describe itself_ using simple ## Key features -- Spin up your whole stack with a single command, and (optionally) watch for changes. Because of the Stack Graph, only what's needed gets re-built, re-deployed, and/or re-tested, so you get **much faster feedback loops**. +- Spin up your whole stack with a single command, and (optionally) watch for changes. Because of the Stack Graph, only what's needed gets re-built, re-deployed, and/or re-tested, so you get a **much faster feedback loop**. - Easily write [integration test suites](https://docs.garden.io/using-garden/features-and-usage#testing-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/master/examples/tasks) that run as part of your deployment process, e.g. database migrations or scaffolding. +- Define [tasks](https://github.com/garden-io/garden/tree/master/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/examples/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). @@ -33,27 +33,27 @@ _Note: The project is in beta. APIs may still change slightly across versions, Head over to the [Basics](https://docs.garden.io/basics) section in our documentation for details on how to set up and use Garden, or look through our [Simple Project](https://docs.garden.io/examples/simple-project) -guide to get a quick sense of how it works. +guide for a brief introduction to how it works. ## Documentation -You can find the full Garden documentation at [https://docs.garden.io](https://docs.garden.io/). +You can find Garden's full documentation at [https://docs.garden.io](https://docs.garden.io/). Overview: -- [Basics](https://docs.garden.io/basics), for installation instructions, our quick start guide, and an overview of the main concepts around Garden. -- [Using Garden](https://docs.garden.io/using-garden), for features and usage, Garden configuration files, usage with remote clusters, and setting up hot reload. -- [Example Projects](https://docs.garden.io/examples) contains guides based on some of the [examples](https://github.com/garden-io/garden/tree/v0.9.6/examples). -- [Reference](https://docs.garden.io/reference), for the glossary, commands reference, configuration files reference, and template strings reference. +- [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)—features and usage, Garden configuration files, usage with remote 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.9.6/examples). +- [Reference](https://docs.garden.io/reference)—glossary, commands reference, configuration files reference, and template strings reference. - [FAQs](https://docs.garden.io/faqs). ## Examples -There are examples of how to use Garden in a myriad of different ways in the [examples](https://github.com/garden-io/garden/tree/v0.9.3/examples) folder of our repository. +The [examples](https://github.com/garden-io/garden/tree/v0.9.3/examples) folder of our repository shows a myriad of different ways to use Garden. For written guides based on some of these examples, check out the [examples section](https://docs.garden.io/examples) of our documentation. -Here are some simple examples of how Garden configuration files look: +Here are a few simple examples of Garden configuration files: ```yaml kind: Module @@ -95,11 +95,11 @@ Please browse our [examples directory](https://github.com/garden-io/garden/tree/ ## Support -Please join the Garden [Slack workspace](http://chat.garden.io) to ask questions, discuss how Garden might fit into your workflow, or even just chat about all things DevOps. +Please join the Garden [Slack workspace](http://chat.garden.io) to ask questions, discuss how Garden might fit into your workflow, or just chat about all things DevOps. ## Acknowledgements -Garden would not be possible without an amazing ecosystem of open-source projects. Here are just some of the projects that Garden uses, either directly or indirectly: +Garden would not be possible without an amazing ecosystem of open-source projects. Here are some of the projects that Garden uses, either directly or indirectly: - [Kubernetes](https://kubernetes.io/) - [OpenFaaS](https://www.openfaas.com/) diff --git a/docs/basics/README.md b/docs/basics/README.md index 6d99a3e993..baf58f12f0 100644 --- a/docs/basics/README.md +++ b/docs/basics/README.md @@ -8,4 +8,4 @@ The following articles cover the basics of installing and using Garden: 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). +Or dive right in by exploring our [configuration files](../using-garden/configuration-files.md) and [Example Projects](../examples/README.md). diff --git a/docs/basics/installation.md b/docs/basics/installation.md index 96a3812343..0b0712ab5a 100644 --- a/docs/basics/installation.md +++ b/docs/basics/installation.md @@ -18,7 +18,7 @@ steps below if you prefer. #### Step 1: Install Homebrew -If you haven't already set up homebrew, please follow [their instructions](https://brew.sh/) to set it up. +If you haven't already set up Homebrew, please follow [their installation instructions](https://brew.sh/). #### Step 2: Docker and local Kubernetes @@ -37,7 +37,7 @@ configure and use, but we do fully support it on Mac. Please look at the #### Step 3: Install `garden-cli` -We have a Homebrew tap and package that you can use to easily install `garden-cli` and all dependencies: +We have a Homebrew tap and package that you can use to easily install `garden-cli` and its dependencies: ```sh brew tap garden-io/garden @@ -50,10 +50,7 @@ To later upgrade to the newest version, simply run `brew update` and then `brew You can run Garden on Windows 10 Pro or Enterprise editions (the Home edition unfortunately does not work because it does not include support for virtualization). -To install the Garden CLI, please use our automated installation script, which will -check for dependencies, install missing dependencies if needed, and finally install the Garden CLI. - -To run the script, open PowerShell as an Administrator and run: +To install the Garden CLI and its dependencies, please use our installation script. To run the script, open PowerShell as an administrator and run: ```PowerShell Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/garden-io/garden/master/support/install.ps1')) @@ -64,7 +61,7 @@ The things the script will check for are the following: * The [Chocolatey](https://chocolatey.org) package manager. The script installs it automatically if necessary. * _git_, _rsync_ and _Docker for Windows_. The script will install or upgrade those via Chocolatey. * Whether you have Hyper-V enabled. This is required for _Docker for Windows_. If you do not already have it enabled, - the script will enable it but you will need to restart your computer before starting Docker for Windows. + the script will enable it, but you will need to restart your computer before starting Docker for Windows. * Whether you have Kubernetes enabled in your _Docker for Windows_ installation. To later upgrade to the newest version, simply re-run the above script. @@ -129,12 +126,12 @@ since it uses the `local-kubernetes` plugin by default, but you can configure it `garden.yml` as follows: ```yaml -project: - environments: - - name: local - providers: - - name: local-kubernetes - context: minikube +kind: Project +environments: + - name: local + providers: + - name: local-kubernetes + context: minikube ``` If you happen to have installed both Minikube and a version of Docker for Mac with Kubernetes support enabled, diff --git a/docs/basics/quick-start.md b/docs/basics/quick-start.md index c370b7ca2b..34d336ce95 100644 --- a/docs/basics/quick-start.md +++ b/docs/basics/quick-start.md @@ -4,9 +4,9 @@ This guide will walk you through setting up the Garden framework. It assumes you ## Using the CLI -With the CLI installed, we can now try out a few commands using the [Simple Project](../examples/simple-project.md) from our [example projects](../examples/README.md). The example project consists of a couple of simple modules, each defining one service. +With the CLI installed, we can now try out a few commands using the [Simple Project](../examples/simple-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 if 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._ +_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._ Clone the repo and change into the `simple-project` directory: @@ -33,7 +33,7 @@ This builds Docker images for `go-service` and `node-service` respectively. Next garden deploy ``` -And that's it! The `garden build` step above is actually unnecessary (only included here for clarity), since `garden deploy` will also rebuild modules as needed. The services are now running on the Garden framework. You can see for yourself by querying the `/hello` endpoint of `go-service`'s running container: +And that's it! The `garden build` step above is actually unnecessary (only included here for clarity), since `garden deploy` will also rebuild modules as needed. The services are now running in your Kubernetes cluster. You can see for yourself by querying the `/hello` endpoint of `go-service`'s running container: ```sh garden call go-service/hello-go diff --git a/docs/basics/stack-graph.md b/docs/basics/stack-graph.md index c8eb5edb2d..bc313c1c13 100644 --- a/docs/basics/stack-graph.md +++ b/docs/basics/stack-graph.md @@ -2,7 +2,7 @@ Garden centers around the _Stack Graph_, which allows you to describe your whole stack in a consistent, structured way. -Garden uses the graph to detect when modules need to re-built or re-tested, services re-deployed etc., by looking at your current code and comparing against previously built, deployed and tested versions. +Garden uses the graph to detect when modules need to be re-built or re-tested, services re-deployed etc. by comparing your current code with previously built, deployed and tested versions. ## Structure @@ -10,12 +10,12 @@ The Stack Graph is essentially an opinionated graph structure, with a handful of * **Project**: The root of the graph. Contains one or more _modules_ and configures _providers_. * **Provider**: Providers are configured at the project level. They take care of initializing deployment environments, and control what happens within each node of the graph, e.g. how modules are built, services are deployed etc. They also specify _module types_ and how they are configured. -* **Module**: A module is something you _build_. Each module specifies a type (e.g. `container` or `helm`) which dictates how it is configured, deployed etc. It can contain zero or more _services_, _tasks_ and _tests_. It can also have build dependencies. +* **Module**: A module is something you _build_. Each module specifies a type (e.g. `container` or `helm`) which dictates how it is configured, built, deployed etc. It can contain zero or more _services_, _tasks_ and _tests_. It can also have build dependencies. * **Service**: A service is something you _deploy_. It can depend on other services, as well as tasks. * **Task**: A task is something you _run_ and wait for to finish. It can depend on other services and tasks. * **Test**: A test is also something you run and wait for to finish, similar to tasks, but with slightly different semantics and separate commands for execution. It can depend on services and tasks (but notably services and tasks cannot depend on tests). -Each part of your stack _describes itself_ using a simple configuration file, and Garden collects all those declarations, validates, and compiles them into a DAG (a directed acyclic graph, meaning it should have no circular dependencies). +Each part of your stack _describes itself_ using a simple configuration file. Garden collects all those declarations, validates, and compiles them into a DAG (a directed acyclic graph, meaning it should have no circular dependencies). Importantly, what happens within each of the actions that the graph describes—building, deploying, running etc.—is completely pluggable via the providers. The Stack Graph is only opinionated in terms of flows and dependencies—_what_ should happen _when_—but the _how_ is pluggable. @@ -53,7 +53,7 @@ tests: dependencies: [my-other-service] ``` -Note here the first four fields, which are common across all module types. Other fields are specified by the corresponding _provider_. +Note here the first four fields, which are common across all module types—`kind`, `type`, `name` and `description`. Other fields are specified by the corresponding _provider_. Also notice that the `container` module explicitly declares a service, whereas the `helm` module does not. This is dictated by the provider. 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. diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index c6e025844a..f85bbc04fe 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -8,11 +8,8 @@ Several named environment configurations may be defined (e.g. _dev_, _testing_, `garden.yml`](../using-garden/configuration-files.md#project-configuration). #### Module -The basic unit of configuration in Garden. A module is defined by its -[`garden.yml` configuration file](./config.md), located in the module's top-level -directory, -which -is a subdirectory of the [project](#project) repository's top-level directory. +The unit of building in Garden. A module is defined by its [`garden.yml` configuration file](./config.md), +located in the module's top-level directory. Each module has a plugin type, and may define one or more [services](#service). @@ -20,18 +17,21 @@ Essentially, a project is organized into modules at the granularity of its *buil depend on one or more other modules having already been built, as specified in its `garden.yml`, in which case those modules will be built first, and their build output made available to the requiring module's build step. -#### Provider -A [module's](#module) plugin type defines its behavior when it is built, deployed, run and tested. Currently, `container` (for "standard" containerized services) and `openfaas` (for serverless functions) are the only stable plugin types. - #### Project The top-level unit of organization in Garden. A project consists of one or more [modules](#module), along with a project-level [`garden.yml` configuration file](./config.md). -Garden CLI commands are run in the context of a project, and are aware of all its modules and services. +Garden CLI commands are run in the context of a project, and are aware of all its configuration, modules and services. #### Provider An implementation of a plugin type (e.g. `local-kubernetes` for the `container` plugin). +Whenever "a module's type" is mentioned in the documentation, what's meant is "which provider will handle this module?" Providers are responsible for implementing a module type's behaviors—e.g. how to build, deploy or test the module. Providers need to be specified for all the module types used in the project. + +For example, both the `local-kubernetes` and `kubernetes` providers (`kubernetes` is the provider for remote Kubernetes) implement the `container` module type, but they handle deployments differently. `local-kubernetes` deploys to a local cluster, where `kubernetes` deploys to a remote cluster. + +For a comprehensive list of providers available in Garden, check out the [References](../reference/README.md) + #### Service The unit of deployment in Garden. Services are defined in their parent [module](#module)'s `garden.yml`, each exposing [one or more ingress endpoints](./config.md#container). diff --git a/docs/using-garden/README.md b/docs/using-garden/README.md index 65de64760e..18b742b0e8 100644 --- a/docs/using-garden/README.md +++ b/docs/using-garden/README.md @@ -2,20 +2,20 @@ ## [Features and usage](./features-and-usage.md) -In this article we discuss how to start a new project with `garden create`, the basic development workflow, how Garden's providers work, and the basics of testing and dependencies. +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. The difference between project and module configs, some significant specific fields, setting up services, and a primer on tests. +This one is all about Garden's configuration files—an overview of project and module configs, setting up services, and a primer on tests. ## [Remote Clusters](./remote-clusters.md) -Most of the time we want to develop locally, with our project running in Minikube or Docker. If you'd like to use a remote cluster though, check out this guide. +Most of these guides currently focus on local development. If you'd like to use a remote cluster, though, check out this guide. ## [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 your container. +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. ## [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. +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. diff --git a/docs/using-garden/configuration-files.md b/docs/using-garden/configuration-files.md index f893b4b0c0..33d477d3d6 100644 --- a/docs/using-garden/configuration-files.md +++ b/docs/using-garden/configuration-files.md @@ -15,9 +15,7 @@ To decide how to split your project up into modules, it's useful to consider wha step, and what the dependency relationships are between your build steps. For example, each container and each serverless function should be represented by its own module. -Below, we'll be using examples from the -[Hello world](../examples/hello-world.md) example project, which touches -on many of the things you're likely to want to configure in a project. +Below, we'll be using examples from the [Hello world](../examples/hello-world.md) example project. ## Project Configuration @@ -25,22 +23,23 @@ We'll start by looking at the top-level [project configuration file](https://git ```yaml # examples/hello-world/garden.yml -project: - name: hello-world - environmentDefaults: - variables: - my-variable: hello-variable - environments: - - name: local - providers: - - name: local-kubernetes - - name: openfaas +kind: Project +name: hello-world +environmentDefaults: + variables: + my-variable: hello-variable +environments: + - name: local + providers: + - name: local-kubernetes + - name: openfaas ``` The project-wide `garden.yml` defines the project's name, the default configuration used for each [environment](../reference/glossary.md#environment) (via the `environmentDefaults` field), and -environment-specific provider configuration. The above only configures a `local` environment, but you could add -further environments, such as a remote Kubernetes environment. +environment-specific [provider](../reference/glossary.md#provider) configuration. The above only configures a `local` environment, but you could add +further environments, such as a remote Kubernetes environment, where you'd use the `kubernetes` (i.e. remote) +provider instead of `local-kubernetes`. Here, project-wide configuration variables can also be specified (global, and/or environment-specific). These are then available for substitution in any string value in any module's `garden.yml`. @@ -57,17 +56,17 @@ as examples to illustrate some of the primary module-level configuration options The following is a snippet from `hello-container`'s module config: ```yaml -module: - name: hello-container - type: container - description: Hello world container service - ... - build: - dependencies: - - name: hello-npm-package - copy: - - source: "./" - target: libraries/hello-npm-package/ +kind: Module +name: hello-container +type: container +description: Hello world container service +... +build: + dependencies: + - name: hello-npm-package + copy: + - source: "./" + target: libraries/hello-npm-package/ ``` The first lines you'll find in all module configurations, and describe the module at a high level. @@ -87,9 +86,9 @@ modules use the same name. ### type -A [module](../reference/glossary.md#module)'s `type` specifies what kind of module this is, which will control how the -module's code gets built, tested, deployed, etc. The module types are implemented by _providers_. The built-in module types -include `container` and `exec` (which basically provides a way to run commands locally). +A [module](../reference/glossary.md#module)'s `type` determines its schema, and which [provider](../reference/glossary.md#provider) is +used to build, test and deploy (etc.) it. The built-in module types include `container`, `helm` and `exec` +(which basically provides a way to run commands locally). The example above is a `container` module, and the `hello-function` module is an `openfaas` module (which is one of many ways to run functions-as-a-service on Kubernetes). @@ -99,12 +98,12 @@ In this particular project, the `container` module type is implemented by the `l ### build -A module's build configuration is specified via the `build` field, and the implementation of what `build` does varies depending on which provider is responsible for that module. +A module's build configuration is specified via the `build` field, and the implementation of what `build` does varies +depending on which provider is responsible for that module. -Regardless of the implementation, a module's build command is executed -with its working directory set to a copy of the module's top-level directory, located at -`[project-root]/.garden/build/[module-name]`. This internal directory is referred to as the module's -[build directory](../reference/glossary.md#build-directory). +Regardless of the implementation, a module's build process is executed with its working directory set to a copy of the +module's top-level directory, located at `[project-root]/.garden/build/[module-name]`. This internal directory is +referred to as the module's [build directory](../reference/glossary.md#build-directory). The `.garden` directory should not be modified by users, since this may lead to unexpected errors when the Garden CLI tools are used in the project. @@ -122,7 +121,7 @@ into `libraries/hello-npm-package/` in the `hello-container` build directory, _b ## Services -A module may contain zero or more _services_. Services are deployed when running `garden deploy` or `garden dev` as +A module may define zero or more _services_. Services are deployed when running `garden deploy` or `garden dev` as part of your runtime stack. How services are configured will depend on the module type. An `openfaas` module always contains a single service. A diff --git a/docs/using-garden/features-and-usage.md b/docs/using-garden/features-and-usage.md index 541ab70c8a..bb5a3d550f 100644 --- a/docs/using-garden/features-and-usage.md +++ b/docs/using-garden/features-and-usage.md @@ -1,81 +1,97 @@ # Features and Usage -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 what some typical Garden workflows look like. +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. ## Starting a new project -To start a new project, you create a `garden.yml` file in the project's root directory. At it's simplest, the project level `garden.yml` file looks something like this: +To start a new Garden project, you create a `garden.yml` file in the top-level directory of your project's Git repository. +At its simplest, the project level `garden.yml` file looks something like this: ```yaml # examples/simple-project/garden.yml -project: - name: simple-project - environments: - - name: local - providers: - - name: local-kubernetes +kind: Project +name: simple-project +environments: + - name: local + providers: + - name: local-kubernetes ``` -You then add a `garden.yml` file at the root directory of every module in your project. Normally, a module is a single container or a single serverless function. A module level `garden.yml` file looks something like this: +You then add a `garden.yml` file at the root directory of every module in your project. Commonly, a module corresponds to a single container, Helm chart, or serverless function. A module-level `garden.yml` file looks something like this: ```yaml # examples/simple-project/services/go-service/garden.yml -module: - name: go-service - description: Go service container - type: container - services: - - name: go-service - ports: - - name: http - containerPort: 8080 - servicePort: 80 - ingresses: - - path: /hello-go - port: http +kind: Module +name: go-service +description: Go service container +type: container +services: + - name: go-service + ports: + - name: http + containerPort: 8080 + servicePort: 80 + ingresses: + - path: /hello-go + port: http ``` -To learn more about how to configure a Garden project, please take a look at our [Configuration files](./configuration-files.md) document. +To learn more about how to configure a Garden project, please take a look at our [Configuration files](./configuration-files.md) guide. -For a practical example of "gardenifying" an existing project, check out the [Simple project](../examples/simple-project.md) example. +For a practical example of "Gardenifying" an existing project, check out the [Simple Project](../examples/simple-project.md) example. ## The development workflow -Most of the time, the development workflow when using Garden after the configuration files are set is extremely simple: you leave `garden dev` running, and Garden will automatically re-build, re-deploy, and re-test your project as you work on it. +After the configuration files are set, the development workflow when using Garden is usually very simple: you leave `garden dev` running, and Garden will automatically re-build, re-deploy, and re-test your project as you work on it. If we run `garden dev` inside the [Simple Project](../examples/simple-project.md) example, the output should be something like this: -Sometimes though, you might prefer to skip the testing step, in which case you can simply use `garden deploy --watch`. This will watch for changes, then build and deploy them, but it'll skip testing. - -Lastly, when things go wrong you should refer to the error logs. These consist of an `error.log` file in the project root, along with the service logs that you can retrieve from the individual pods in your cluster. +``` +Good evening! Let's get your environment wired up... + +✔ node-service → Getting build status... → Done (took 0.3 sec) +✔ go-service → Getting build status... → Done (took 0.2 sec) +✔ go-service → Deploying version v-9cfd748cd2... → Done (took 4.2 sec) + ℹ go-service → Service deployed + → Ingress: http://simple-project.local.app.garden/hello-go +✔ node-service → Running unit tests → Success (took 3.4 sec) +✔ node-service → Deploying version v-9cfd748cd2... → Done (took 7.3 sec) + ℹ node-service → Service deployed + → Ingress: http://simple-project.local.app.garden/hello-node + → Ingress: http://simple-project.local.app.garden/call-go-service +✔ node-service → Running integ tests → Success (took 4.3 sec) +🌻 Garden dashboard and API server running on http://localhost:59636 + +🕑 Waiting for code changes +``` -For the latter, you can use the `garden logs` command, followed by the name of the service you'd like to query. For example `garden logs go-service` would fetch the logs for the `go-service` service, while `garden logs go-service,node-service` would fetch the logs for both the `go-service` and the `node-service` services. +Now, let's change `services/node-service/app.js` (e.g. by adding a newline somewhere). This should result in something like the following being appended to the log of the `garden dev` command we started above: -The `garden logs` command is functionally equivalent to `kubectl logs`, but simpler to execute. +``` +✔ node-service → Building node-service:v-9cfd748cd2-1553707229... → Done (took 1.4 sec) +✔ node-service → Deploying version v-9cfd748cd2-1553707229... → Done (took 8 sec) + ℹ node-service → Service deployed + → Ingress: http://simple-project.local.app.garden/hello-node + → Ingress: http://simple-project.local.app.garden/call-go-service +✔ node-service → Running unit tests → Success (took 3.5 sec) +✔ node-service → Running integ tests → Success (took 4.4 sec) -## Providers +🕑 Waiting for code changes -Whenever "a module's type" is mentioned in the documentation, what's meant is "which provider will handle this module?" Providers, as [previously discussed](../basics/stack-graph.md), are responsible for implementing different behaviors for say containers and functions, and they need to be specified in a module's configuration files. +```` +As we can see, `node-service` was rebuilt, redeployed, and its unit & integration tests re-run. -For a comprehensive list of providers available in Garden, check out the [References](../reference/README.md) +Sometimes though, you might prefer to skip the testing step, in which case you can simply use `garden deploy --watch`. This will watch for changes, then build and deploy them, but it'll skip testing. -## Testing and dependencies +Lastly, when things go wrong you should refer to the error logs. These consist of an `error.log` file in the project root, along with the service logs that you can retrieve from the individual pods in your cluster. -Both tests and dependencies are specified in Garden's `garden.yml` configuration files. +For the latter, you can use the `garden logs` command, followed by the name of the service you'd like to query. For example `garden logs go-service` would fetch the logs for the `go-service` service, while `garden logs go-service,node-service` would fetch the logs for both the `go-service` and the `node-service` services. -Service dependencies are a field within the services declaration. Here's a snippet, from our [TLS project](../examples/tls-project.md) example: +When using the `kubernetes` or `local-kubernetes` provider, the `garden logs` command is functionally equivalent to `kubectl logs`, but simpler to execute. -```yaml -module: - name: node-service - description: Node service container - type: container - services: - - name: node-service - ... - dependencies: - - go-service -``` +## Testing and dependencies -Tests should be specified the same way, and in the case of integration tests their dependencies should be present as well. Another snippet from the same file: +Tests and their dependencies are specified in their modules' `garden.yml` files. Apart from the `name` and `args` (which is the command +to run the tests inside the container), tests may specify runtime dependencies. These can be names of services or tasks. Here's a snippet from our [TLS project](../examples/tls-project.md) example: ```yaml tests: @@ -89,6 +105,8 @@ tests: Above we're using `npm test` and `npm run integ` for our tests, but they can be anything you'd like. The only constraint is that Garden follows the typical Unix exit codes convention: `0` means success, and any non-zero exit codes represent failure. +Since the `integ` tests depends on `go-service`, Garden will ensure that `go-service` is deployed before running the `integ` tests. Another use case for test dependencies would be to drop and re-populate a test database before the test run by adding a dependency on a Garden task that does just that. + ## Advanced features For Garden's more advanced features, see the following docs: diff --git a/docs/using-garden/hot-reload.md b/docs/using-garden/hot-reload.md index 00c7259d02..0ca3ad61d3 100644 --- a/docs/using-garden/hot-reload.md +++ b/docs/using-garden/hot-reload.md @@ -1,16 +1,16 @@ # Hot Reload -When the `local-kubernetes` provider is used, `container` modules can be configured to hot-reload their running services when the module's sources change (i.e. without redeploying). In essence, hot-reloading copies source files into the appropriate running containers when code is changed by the user. +When the `local-kubernetes` or `kubernetes` provider is used, `container` modules can be configured to hot-reload their running services when the module's sources change (i.e. without redeploying). In essence, hot-reloading copies source files into the appropriate running containers (local or remote) when code is changed by the user. For example, services that can be run with a file system watcher that automatically update the running application process when sources change (e.g. nodemon, Django, Ruby on Rails, and many other web app frameworks) are a natural fit for this feature. # Usage -Currently, modules configured for hot reloading are only deployed with hot reloading enabled when they're deployed via `garden deploy -w` or `garden dev`; and not, for example, when deployed via `garden deploy` without the `-w` flag. +Currently, services are only deployed with hot reloading enabled when their names are passed to the `--hot` option via `garden deploy` or `garden dev` commands (e.g. `garden dev --hot=foo-service,bar-service`). If these services don't belong to a module defining a `hotReload` configuration (see below for an example), an error will be thrown if their names are passed to the `--hot` option. -Subsequently deploying a service belonging to a module configured for hot reloading via `garden deploy` (without the watch flag) results in the service being redeployed in standard configuration. (See [this link](https://github.com/garden-io/garden/pull/291) for a more technical discussion.) +Subsequently deploying a service belonging to a module configured for hot reloading via `garden deploy` (without the watch flag) results in the service being redeployed in standard configuration. -Since hot reloading is triggered via Garden's file system watcher, hot reloading only occurs while a `garden deploy -w`, `garden build -w`, or `garden dev` command is running. +Since hot reloading is triggered via Garden's file system watcher, hot reloading only occurs while a watch-mode Garden command is running. # Quick example @@ -46,4 +46,4 @@ You can configure several such `source`/`target` pairs, but note that the `sourc target: /app/bar ``` -Lastly, `hotReloadArgs` specifies the arguments to use to run the container (when deployed with hot reloading enabled). If no `hotReloadArgs` are specified, `args` is also used in hot reload mode. +Lastly, `hotReloadArgs` specifies the arguments to use to run the container (when deployed with hot reloading enabled). If no `hotReloadArgs` are specified, `args` is also used to run the container when the service is deployed with hot reloading enabled diff --git a/docs/using-garden/remote-clusters.md b/docs/using-garden/remote-clusters.md index f14535026b..0d80538ec5 100644 --- a/docs/using-garden/remote-clusters.md +++ b/docs/using-garden/remote-clusters.md @@ -78,6 +78,8 @@ project: ### Configuring a container registry +> NOTE: Configuring a container registry is not necessary when using Garden Enterprise, which features integrated remote building. + When you deploy to the environment (via `garden deploy` or `garden dev`), containers are first built and then pushed to the configured _deployment registry_, where the K8s cluster will then pull the built images when deploying. This should generally be a _private_ container registry, or at least a private project in a public registry. diff --git a/garden-service/package-lock.json b/garden-service/package-lock.json index 096bd08c2b..21b4d914ac 100644 --- a/garden-service/package-lock.json +++ b/garden-service/package-lock.json @@ -3808,8 +3808,7 @@ "ansi-regex": { "version": "2.1.1", "resolved": false, - "integrity": "sha1-w7M6te42DYbg5ijwRorn7yfWVN8=", - "optional": true + "integrity": "sha1-w7M6te42DYbg5ijwRorn7yfWVN8=" }, "aproba": { "version": "1.2.0", @@ -3830,14 +3829,12 @@ "balanced-match": { "version": "1.0.0", "resolved": false, - "integrity": "sha1-ibTRmasr7kneFk6gK4nORi1xt2c=", - "optional": true + "integrity": "sha1-ibTRmasr7kneFk6gK4nORi1xt2c=" }, "brace-expansion": { "version": "1.1.11", "resolved": false, "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", - "optional": true, "requires": { "balanced-match": "^1.0.0", "concat-map": "0.0.1" @@ -3852,20 +3849,17 @@ "code-point-at": { "version": "1.1.0", "resolved": false, - "integrity": "sha1-DQcLTQQ6W+ozovGkDi7bPZpMz3c=", - "optional": true + "integrity": "sha1-DQcLTQQ6W+ozovGkDi7bPZpMz3c=" }, "concat-map": { "version": "0.0.1", "resolved": false, - "integrity": "sha1-2Klr13/Wjfd5OnMDajug1UBdR3s=", - "optional": true + "integrity": "sha1-2Klr13/Wjfd5OnMDajug1UBdR3s=" }, "console-control-strings": { "version": "1.1.0", "resolved": false, - "integrity": "sha1-PXz0Rk22RG6mRL9LOVB/mFEAjo4=", - "optional": true + "integrity": "sha1-PXz0Rk22RG6mRL9LOVB/mFEAjo4=" }, "core-util-is": { "version": "1.0.2", @@ -3982,8 +3976,7 @@ "inherits": { "version": "2.0.3", "resolved": false, - "integrity": "sha1-Yzwsg+PaQqUC9SRmAiSA9CCCYd4=", - "optional": true + "integrity": "sha1-Yzwsg+PaQqUC9SRmAiSA9CCCYd4=" }, "ini": { "version": "1.3.5", @@ -3995,7 +3988,6 @@ "version": "1.0.0", "resolved": false, "integrity": "sha1-754xOG8DGn8NZDr4L95QxFfvAMs=", - "optional": true, "requires": { "number-is-nan": "^1.0.0" } @@ -4010,7 +4002,6 @@ "version": "3.0.4", "resolved": false, "integrity": "sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA==", - "optional": true, "requires": { "brace-expansion": "^1.1.7" } @@ -4018,14 +4009,12 @@ "minimist": { "version": "0.0.8", "resolved": false, - "integrity": "sha1-hX/Kv8M5fSYluCKCYuhqp6ARsF0=", - "optional": true + "integrity": "sha1-hX/Kv8M5fSYluCKCYuhqp6ARsF0=" }, "minipass": { "version": "2.2.4", "resolved": false, "integrity": "sha512-hzXIWWet/BzWhYs2b+u7dRHlruXhwdgvlTMDKC6Cb1U7ps6Ac6yQlR39xsbjWJE377YTCtKwIXIpJ5oP+j5y8g==", - "optional": true, "requires": { "safe-buffer": "^5.1.1", "yallist": "^3.0.0" @@ -4044,7 +4033,6 @@ "version": "0.5.1", "resolved": false, "integrity": "sha1-MAV0OOrGz3+MR2fzhkjWaX11yQM=", - "optional": true, "requires": { "minimist": "0.0.8" } @@ -4125,8 +4113,7 @@ "number-is-nan": { "version": "1.0.1", "resolved": false, - "integrity": "sha1-CXtgK1NCKlIsGvuHkDGDNpQaAR0=", - "optional": true + "integrity": "sha1-CXtgK1NCKlIsGvuHkDGDNpQaAR0=" }, "object-assign": { "version": "4.1.1", @@ -4138,7 +4125,6 @@ "version": "1.4.0", "resolved": false, "integrity": "sha1-WDsap3WWHUsROsF9nFC6753Xa9E=", - "optional": true, "requires": { "wrappy": "1" } @@ -4224,8 +4210,7 @@ "safe-buffer": { "version": "5.1.1", "resolved": false, - "integrity": "sha512-kKvNJn6Mm93gAczWVJg7wH+wGYWNrDHdWvpUmHyEsgCtIwwo3bqPtV4tR5tuPaUhTOo/kvhVwd8XwwOllGYkbg==", - "optional": true + "integrity": "sha512-kKvNJn6Mm93gAczWVJg7wH+wGYWNrDHdWvpUmHyEsgCtIwwo3bqPtV4tR5tuPaUhTOo/kvhVwd8XwwOllGYkbg==" }, "safer-buffer": { "version": "2.1.2", @@ -4261,7 +4246,6 @@ "version": "1.0.2", "resolved": false, "integrity": "sha1-EYvfW4zcUaKn5w0hHgfisLmxB9M=", - "optional": true, "requires": { "code-point-at": "^1.0.0", "is-fullwidth-code-point": "^1.0.0", @@ -4281,7 +4265,6 @@ "version": "3.0.1", "resolved": false, "integrity": "sha1-ajhfuIU9lS1f8F0Oiq+UJ43GPc8=", - "optional": true, "requires": { "ansi-regex": "^2.0.0" } @@ -4325,14 +4308,12 @@ "wrappy": { "version": "1.0.2", "resolved": false, - "integrity": "sha1-tSQ9jz7BqjXxNkYFvA0QNuMKtp8=", - "optional": true + "integrity": "sha1-tSQ9jz7BqjXxNkYFvA0QNuMKtp8=" }, "yallist": { "version": "3.0.2", "resolved": false, - "integrity": "sha1-hFK0u36Dx8GI2AQcGoN8dz1ti7k=", - "optional": true + "integrity": "sha1-hFK0u36Dx8GI2AQcGoN8dz1ti7k=" } } }, @@ -7519,7 +7500,6 @@ "resolved": "https://registry.npmjs.org/align-text/-/align-text-0.1.4.tgz", "integrity": "sha1-DNkKVhCT810KmSVsIrcGlDP60Rc=", "dev": true, - "optional": true, "requires": { "kind-of": "^3.0.2", "longest": "^1.0.1", @@ -7889,8 +7869,7 @@ "version": "1.1.6", "resolved": "https://registry.npmjs.org/is-buffer/-/is-buffer-1.1.6.tgz", "integrity": "sha512-NcdALwpXkTm5Zvvbk7owOUSvVvBKDgKP5/ewfXEznmQFfs4ZRmanOeKBTjRVjka3QFoN6XJ+9F3USqfHqTaU5w==", - "dev": true, - "optional": true + "dev": true }, "is-builtin-module": { "version": "1.0.0", @@ -7986,7 +7965,6 @@ "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-3.2.2.tgz", "integrity": "sha1-MeohpzS6ubuw8yRm2JOupR5KPGQ=", "dev": true, - "optional": true, "requires": { "is-buffer": "^1.1.5" } @@ -8039,8 +8017,7 @@ "version": "1.0.1", "resolved": "https://registry.npmjs.org/longest/-/longest-1.0.1.tgz", "integrity": "sha1-MKCy2jj3N3DoKUoNIuZiXtd9AJc=", - "dev": true, - "optional": true + "dev": true }, "lru-cache": { "version": "4.1.3", @@ -8343,8 +8320,7 @@ "version": "1.6.1", "resolved": "https://registry.npmjs.org/repeat-string/-/repeat-string-1.6.1.tgz", "integrity": "sha1-jcrkcOHIirwtYA//Sndihtp15jc=", - "dev": true, - "optional": true + "dev": true }, "require-directory": { "version": "2.1.1",