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:
# examples/simple-project/garden.ymlkind: Projectname: simple-projectenvironments:- name: localproviders:- name: local-kubernetes
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:
# examples/simple-project/services/go-service/garden.ymlkind: Modulename: go-servicedescription: Go service containertype: containerservices:- name: go-serviceports:- name: httpcontainerPort: 8080servicePort: 80ingresses:- path: /hello-goport: http
To learn more about how to configure a Garden project, please take a look at our Configuration files guide.
For a practical example of "Gardenifying" an existing project, check out the Simple Project example.
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 example, the output should be something like this:
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
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:
✔ 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)🕑 Waiting for code changes`
As we can see,
node-service was rebuilt, redeployed, and its unit & integration tests re-run.
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.
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
When using the
local-kubernetes provider, the
garden logs command is functionally equivalent to
kubectl logs, but simpler to execute.
Tests and their dependencies are specified in their modules'
garden.yml files. Apart from the
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 example:
tests:- name: unitargs: [npm, test]- name: integargs: [npm, run, integ]dependencies:- go-service
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.
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.
For Garden's more advanced features, see the following docs: