Code Synchronization
Garden includes a sync mode that allows you to rapidly synchronize your code (and other files) to and from running containers.
The sync mode uses Mutagen under the hood. Garden automatically takes care of fetching Mutagen, so you don't need to install any dependencies yourself to make use of sync mode.
This feature used to be called dev mode but as of version 0.13 we've opted for more straightforward terminology. The functionality is exactly the same as before.
Please make sure to specify any paths that should not be synced by setting the provider-level default excludes and/or the
exclude field on each configured sync! Otherwise you may end up syncing large directories and even run into application errors.To configure a service for sync mode, add
sync to your Deploy configuration to specify your sync targets:kind: Deploy
name: node-service
type: container
build: node-service-build
spec:
args: [npm, run, serve]
sync:
paths:
- target: /app/src
source: src
mode: two-way
exclude: [node_modules]
...
kind: Deploy
type: kubernetes # this example looks the same for helm modules (i.e. with `type: helm`)
name: node-service
spec:
defaultTarget:
kind: Deployment
name: vote
sync:
paths:
- containerPath: /app/src
sourcePath: /src
mode: two-way
overrides:
- command: [npm, run, dev]
...
To deploy your services with sync enabled, you can use the
deploy command:# Deploy specific services in sync mode:
garden deploy --sync myservice
garden deploy --sync myservice,my-other-service
# Deploy all applicable services with sync enabled:
garden deploy --sync=*
Once your deploys are ready, any changes you make that fall under one of the sync specs you've defined will be automatically synced between your local machine and the running service.
Once you quit/terminate the Garden command, the deploys and syncs will keep running in the background. To stop the syncs you can use the
sync stop command.Garden supports several sync modes, each of which maps onto a Mutagen sync mode.
In brief: It's generally easiest to get started with the
one-way or two-way sync modes, and then graduate to a more fine-grained setup based on one-way-replica and/or one-way-replica-reverse once you're ready to specify exactly which paths to sync and which files/directories to ignore from the sync.- Syncs a local
sourcepath to a remotetargetpath. - When there are conflicts, does not replace/delete files in the remote
targetpath. - Simple to use, especially when there are files/directories inside the remote
targetthat you don't want to override with the contents of the localsource. - On the other hand, if your setup / usage pattern is such that conflicts do sometimes arise for the
source/targetpair in question, you may want to useone-way-replicainstead.
- Syncs a local
sourcepath to a remotetargetpath, such thattargetis always an exact mirror ofsource(with the exception of excluded paths). - When using this mode, there can be no conflicts—the contents of
sourcealways override the contents oftarget. - Since conflicts are impossible here, this mode tends to be a better / more reliable choice long-term than
one-way/one-way-safe. However, you may need to configure more fine-grained/specificsource/targetpairs and their excludes such that you don't have problems with paths in the remotetargetbeing overwritten/deleted when they change in the localsource.
- Same as
one-way, except the direction of the sync is reversed. - Syncs a remote
targetpath to a localsourcepath. - Has the same benefits and drawbacks as
one-way: Simple to configure, but conflicts are possible.
- Same as
one-way-replica, except the direction of the sync is reversed. - Syncs a remote
targetpath to a localsourcepath, such thatsourceis always an exact mirror oftarget(with the exception of excluded paths). - When using this mode, there can be no conflicts—the contents of
targetalways override the contents ofsource.
- Bidirectionally syncs a local
sourceto a remotetargetpath. - Changes made in the local
sourcewill be synced to the remotetarget. - Changes made in the remote
targetwill be synced to the localsource. - When there are conflicts on either side, does not replace/delete the corresponding conflicting paths on the other side.
- Similarly to
one-way, this mode is simple to configure when there are files in eithersourceortargetthat you don't want overridden on the other side when files change or are added/deleted. - Setting up several
one-way-replicaandone-way-replica-reversesyncs instead ofone-wayandtwo-wayis generally the best approach long-term, but may require more fine-grained configuration (more sync specs for specific subpaths and more specific exclusion rules, to make sure things don't get overwritten/deleted in unwanted ways).
Same as
two-way-safe except:- Changes made in the local
sourcewill always win any conflict. This includes cases where alpha’s deletions would overwrite beta’s modifications or creations - No conflicts can occur in this synchronization mode.
Mutagen uses the terminology "alpha" and "beta" for the sync endpoints. In Garden's
one-way, one-way-replica and two-way sync modes, alpha is source and beta is target.For the reverse sync modes (
one-way-reverse and one-way-replica-reverse), alpha is target and beta is source.By design, exclusion rules from ignorefiles (such as
.gardenignore files) are not applied to syncs.This is done to grant you more control over precisely which files and directories you'd like to sync.
For example, you might want to ignore
dist or build directories in general usage, but still be able to sync them from your local machine to the running container (or from the running container to your local machine). This is easy to achieve with the right configuration.Exclusion rules can be specified on individual sync configs:
kind: Deploy
name: node-service
type: container
build: node-service-build
spec:
args: [npm, run, serve]
sync:
paths:
- target: /app/src
source: src
mode: two-way
exclude: [node_modules, tmp, "**/*.log"] # <------ paths matching these patterns won't be synced
...
Project-wide exclusion rules can be set on the
local-kubernetes and kubernetes providers:apiVersion: garden.io/v1
kind: Project
...
providers:
- name: kubernetes
...
# Configure project-wide exclusion rules and default permission/ownership settings
# for synced files/directories.
sync:
defaults:
exclude:
- "/**/node_modules" # <--- with this, we don't have to specify `node_modules` on individual sync specs
This is great to reduce repetition in your excludes.
See the reference documentation for the
kubernetes provider) for a full list of provider-level options for sync when using the kubernetes provider. The same sync options are also available when using local-kubernetes.In certain cases you may need to set a specific owner/group or permission bits on the synced files and directories at the target.
To do this, you can set a few options on each sync:
kind: Deploy
name: node-service
type: container
build: node-service-build
spec:
sync:
paths:
- target: /app/src
source: src
mode: two-way
exclude: [node_modules]
defaultOwner: 1000 # <- set an integer user ID or a string name
defaultGroup: 1000 # <- set an integer group ID or a string name
defaultFileMode: 0666 # <- set the permission bits (as octals) for synced files
defaultDirectoryMode: 0777 # <- set the permission bits (as octals) for synced directories
...
This example demonstrates several of the more advanced options. For more details on the options available, see the sections above.
apiVersion: garden.io/v1
kind: Project
...
providers:
- name: kubernetes
...
# Configure project-wide exclusion rules and default permission/ownership settings
# for synced files/directories.
sync:
defaults:
exclude:
- "/**/node_modules"
owner: 1000 # <- set an integer user ID or a string name
group: 1000 # <- set an integer group ID or a string name
fileMode: 0666 # <- set the permission bits (as octals) for synced files
directoryMode: 0777 # <- set the permission bits (as octals) for synced directories
---
kind: Deploy
name: node-service
type: container
description: |
Here, we sync source code into the remote, and sync back the `test-artifacts` directory
(populated when we run tests) back to the local machine.
build: node-service-build
spec:
args: [npm, start]
sync:
# Overrides the container's default when the service is deployed in sync mode.
command: [npm, run, dev]
# You can use several sync specs for the same service. It's generally a good idea to be specific about
# what you want to sync, and to use `one-way-replica` or `one-way-replica-reverse` when possible to keep
# things simple and avoid sync conflicts.
paths:
- containerPath: /app/src
sourcePath: /app/src
# We don't need to exclude `node_modules` here, since above we added a
# project-wide exclusion rule for that.
# exclude: [node_modules]
mode: one-way-replica
- containerPath: /test-artifacts
sourcePath: /test-artifacts
# This syncs back any files/folders on the remote to the local machine, always
# overriding the local directory's contents with the remote one. See above for a detailed
# description of each available sync mode.
mode: one-way-replica-reverse
...
Every so often something comes up in the underlying Mutagen synchronization process, which may not be visible in the Garden CLI logs. To figure out what the issue may be (say, ahead of reporting a GitHub issue for Garden), it's useful to be able to use the
mutagen CLI directly.Because Garden creates a temporary data directory for Mutagen for every Garden CLI instance, you can't use the
mutagen CLI without additional context. However, to make this easier, a symlink to the temporary directory is automatically created under <project root>/.garden/mutagen/<random ID>, as well as a mutagen.sh helper script within that directory that sets the appropriate context and links to the automatically installed Mutagen CLI. We also create a <project root>/.garden/mutagen/latest symlink for convenience.To, for example, get the current list of active syncs in an active Garden process, you could run the following from the project root directory:
.garden/mutagen/latest/mutagen.sh sync list