garden-cli

Welcome! Garden is a full-featured development framework for containers and serverless backends, designed to make it easy to develop and test distributed systems.

Status

The project is in early alpha (or developer preview, if you prefer). This means APIs may well change (not drastically, but still), overall stability will improve and platform support is still limited.

All that said, Garden can already be highly useful if the following applies to you:

• You're deploying to (or transitioning to) Kubernetes.
• You develop on Mac or Linux.
• You work mostly with containers today (but perhaps plan on adopting serverless platforms in the future).
• You really don't want to spend your precious hours building your own developer tooling!

If that sounds right for you, please give it a go and don't hesitate to report issues or come right over to our Gitter for a chat!

Setup

Dependencies

You need to set up the following on your local machine to use garden:

• Node.js >= 8.x
• Docker
• Git
• rsync
• Watchman
• Local installation of Kubernetes

To install Kubernetes, we recommend Docker for Mac/Windows (edge version) on Mac/Windows, and you can use Minikube on any supported platform. You'll just need to configure a kubectl context to point to your local instance.

On Mac, we recommend using Homebrew on Mac to install everything except Docker, but use whatever works for you!

Note that you need to install the edge version of Docker for Mac/Windows in order to enable Kubernetes support. Once installed, you need to open the Docker preferences, go to the Kubernetes section, tick Enable Kubernetes and save. For more information, see here for Mac or here for Windows.

Installation

Once you have the above dependencies set up, simply run

npm install -g garden-cli

Then go on to our getting started guide, or try out the simple hello-world example below to kick things off.

Examples

The examples/ directory contains usage examples for the framework. You might want to start with the hello-world example project, to see an example of basic build, deployment and interaction flows. Take a look around the projects, taking special note of the garden.yml files - it's pretty straightforward, we promise :)

To spin it up, cd to any of the directories under examples/ and run:

garden deploy

Once you've deployed the hello-world project, you can try querying the /hello endpoint:

garden call hello-container/hello

For more details, please head over to our getting started guide.

Contributing

We welcome any and all contributions to Garden! What we're trying to achieve is a big task, and developers have a lot of diverse needs, so we need and appreciate your input, whether it's through code, docs, issues or developing plugins for your needs.

For more detailed guidelines, see CONTRIBUTING.md.

License

Mozilla Public License 2.0 (MPL-2.0)

Changelog

v0.1.0 (2018-05-31)

Bug Fixes

• allow empty output from test runs (67a2d956)
• syntax error in .release-it.json (010a138c)
• allow commands to specify logger type (893f9e24)
• add missing license header (f6e11d91)
• #107 & #108 - incl. deps in auto-reload. (d1aaf5e4)
• ensure module build paths have trailing slash (for rsync) (1c555d12)
• fix default log level on header and finish methods (1eb143d5)
• #85 closing gulp watch didn't close tsc process (4b3a7c45)
• partial CircleCI status on PRs (7d0a3ef0)
• regression after splitting up GardenContext (bbb6db5b)
• issue where module scanning would hang with empty projects (ec47c72b)
• bug in CLI when handling errors (f7ae4dd0)
• better and more consistent error handling in CLI commands (36ba7b7c)
• service outputs were not propagated to runtime context (0151593f)
• bad timestamp values could crash log command (4383d75e)
• propagate force flag to deployService action (6ccc9d06)
• wrong function name in local-gcf-container (7a7d5af8)
• error handling in hello-container (f778fe9f)
• issue with gulp watch and static files (dc9cd9f4)
• use built-in ingress controller and dashboard for minikube (879bce21)
• deploy command would deploy all services from each processed module (673630c9)
• Cancel dependants on task error. (68316083)
• temporarily disabling minikube tests in CI (issues with CircleCI) (5e1b4bca)
• better error output when gulp add-version-files fails (0fc4ee4f)
• Cache results to skip superfluous tasks. (0632e367)
• fix destroy env command after kubernetes-client upgrade (200fd018)
• print json/yaml output after cli returns parse results (eeadf160)
• disable ts-node cache in tests to avoid inconsistencies (21f2d44e)
• version is now correctly set for plugin modules (#84) (d9c37572)
• remove .vscode directories in multi-container example (ccd426db)
• add missing copyright-header dependency on CircleCI (ceca5c42)
• add missing dependencies for copyright-header on OSX (d4d639f5)
• k8s plugin now respects configured context (a395b792)
• testModule handlers now receive runtime context (6ea60b01)
• better output rendering for JSON responses in call command (1aecfe07)
• better handling of streams not from logger (42fa17ed)
• linting errors in tests (185eb696)
• better kubectl errors (76fabd64)
• minor logging fixes (bde56fa4)
• Correction to FS watcher subscription logic. (59699144)
• test name was not included in test result keys (3dac1860)
• Added OperationQueue to TaskGraph. (ae797859)
• linting errors (e839e8eb)
• re-implemented local GCF plugin to fix issues (3f2ee336)
• add better error logging for kubectl and rsync (212304ac)
• issue where build dependencies couldn't be copied (d3a44cdb)
• changed how paths are handled when copying build dependencies (d6506daf)
• allow unkown keys in baseModuleSchema (78303dee)
• added missing "Done!" message at end of build command (a05f2c5e)
• build staging no longer copies symlinks (0fc60bd0)
• issues with kubernetes-client after upgrade (f4096a24)
• better logger types (56596fbe)
• package.json & .snyk to reduce vulnerabilities (0766b56b)
• cli: duplicate command checks now accounts for subcommands (b9e22f5f)
• cli: map all Errors to GardenErrors and log accordingly (02b05b39)
• hello-world: npm package is now included in function build (27956534)
• hello-world-example: add missing Dockerfile directives (4acc4cc7)
• logger: more performant update function (4d8c89e6)
• logger: fix basic-terminal-writer superflous newline (bfc0fcf4)

Code Refactoring

• move invalid flags check to command setup function (ee89b74e)
• split up writers into separate modules (e528b35f)
• add processServices alongside processModules helper (48710228)
• major hardening of internal plugin APIs (242d0aad)
• changed YAML spec to use lists instead of maps in most places (f1d2548f)
• remove unusued watchModules command (920eacc1)
• merge autoreload command into dev command (3c78c364)
• remove skipAutoReload option (f96fc5f1)
• replaced build and test scripts with gulpfile (05e3c73d)
• changed build dependency copy specs config format (608f9633)
• k8s garden-system now deployed via sub-Garden (4a79c45a)
• move some logic from commands to plugin context (b7173bea)
• major overhaul to plugin architecture (3b97e088)
• split GardenContext into Garden and PluginContext (04b5417d)
• rename GardenContext to Garden (64bce4fb)
• split Kubernetes plugin into more modules (e6d84e16)

Features

• created local-kubernetes plugin and added config options (1fcf88d8)
• add truncatePrevious option to file-writer (a64fbb0c)
• add force flag to env config command (d5ba05b3)
• template variables can now access provider name and config (51e2f33b)
• support and documentation for Minikube (b2c632c3)
• Detect circular dependencies. (4a352767)
• add scan command to output info about modules in project (075e6c2b)
• add support for .gardenignore file (7ba24b73)
• add global --output flag for CLI (7f256531)
• add run commands for ad-hoc runs of modules, services and tests (3aca6aca)
• pass parent to nested log entries (41cddf06)
• add filter and find methods to logger (814733b6)
• add login and logout commands (00548e2a)
• add loglevel as cli option and remove silent/verbose options (985c1606)
• add watch flag to test and build commands (dd0a4fe7)
• add --watch flag to deploy command (7b11d58a)
• auto-rebuilding modules & FS watching (8191aa82)
• added buildContext param to buildModule handlers (141abe9a)
• plugins can now add modules to a project (26f38c78)
• user no longer needs to run env config command (8cb65120)
• cli: validate option flags (8c249bdd)

Performance Improvements

• made tests run quite a bit faster (1aa69fdc)

BREAKING CHANGE

This includes some changes to the project schema and how it is resolved, as well as how the main Garden class is instantiated. The Garden class is now called with an environment name, which is then fixed for the session. The env configuration is resolved by merging the specific environment configuration with a global configuration specified on the new global key in the project config. The schema for the providers key also different - its keys should now match plugin names, and contain configuration for those plugins.