github.com/GoogleContainerTools/skaffold/v2@v2.13.2/docs-v2/content/en/docs/filesync.md (about)

     1  ---
     2  title: "File Sync"
     3  linkTitle: "File Sync"
     4  weight: 44
     5  featureId: sync
     6  aliases: [/docs/how-tos/filesync, docs/pipeline-stages/filesync]
     7  ---
     8  
     9  Skaffold supports copying changed files to a deployed container so as to avoid the need to rebuild, redeploy, and restart the corresponding pod.
    10  The file copying is enabled by adding a `sync` section with _sync rules_ to the `artifact` in the `skaffold.yaml`.
    11  Under the hood, Skaffold creates a tar file with changed files that match the sync rules.
    12  This tar file is sent to and extracted on the corresponding containers.
    13  
    14  Multiple types of sync are supported by Skaffold:
    15  
    16   + `manual`: The user must specify both the files in their local workspace and the destination in the running container.
    17     This sync mode is supported by every type of artifact.
    18  
    19   + `infer`: The destinations for each changed file is inferred from the builder.
    20     The docker and kaniko builders examine instructions in a Dockerfile.
    21     This inference is also supported for custom artifacts that **explicitly declare a dependency on a Dockerfile.**
    22     The ko builder can sync static content using this sync mode.
    23  
    24  + `auto`: Skaffold automatically configures the sync.  This mode is only supported by Jib and Buildpacks artifacts.
    25     Auto sync mode is enabled by default for Buildpacks artifacts.
    26  
    27  ### Manual sync mode
    28  
    29  A manual sync rule must specify the `src` and `dest` field.
    30  The `src` field is a glob pattern to match files relative to the artifact _context_ directory, which may contain `**` to match nested files.
    31  The `dest` field is the absolute or relative destination path in the container.
    32  If the destination is a relative path, an absolute path will be inferred by prepending the path with the container's `WORKDIR`.
    33  By default, matched files are transplanted with their whole directory hierarchy below the artifact context directory onto the destination.
    34  The optional `strip` field can cut off some levels from the directory hierarchy.
    35  The following example showcases manual filesync:
    36  
    37  {{% readfile file="samples/filesync/filesync-manual.yaml" %}}
    38  
    39  - The first rule synchronizes the file `.filebaserc` to the `/etc` folder in the container.
    40  - The second rule synchronizes all `html` files in the `static-html` folder into the `<WORKDIR>/static` folder in the container.
    41    Note that this pattern does not match files in sub-folders below `static-html` (e.g. `static-html/a.html` but not `static-html/sub/a.html`).
    42  - The third rule synchronizes all `png` files from any sub-folder into the `assets` folder on the container.
    43    For example, `img.png` ↷ `assets/img.png` or `sub/img.png` ↷ `assets/sub/img.png`.
    44  - The last rule synchronizes all `md` files below the `content/en` directory into the `content` folder on the container.
    45    The `strip` directive ensures that only the directory hierarchy below `content/en` is re-created at the destination.
    46    For example, `content/en/index.md` ↷ `content/index.md` or `content/en/sub/index.md` ↷ `content/sub/index.md`.
    47  
    48  ### Inferred sync mode
    49  
    50  For Docker artifacts, Skaffold knows how to infer the desired destination from the artifact's `Dockerfile`
    51  by examining the `ADD` and `COPY` instructions.
    52  
    53  For Ko artifacts, Skaffold infers the destination from the structure of your
    54  codebase.
    55  
    56  To enable syncing, you specify which files are eligible for syncing in the sync rules.
    57  The sync rules for inferred sync mode is a list of glob patterns.
    58  
    59  The following example showcases this filesync mode for Docker artifacts:
    60  
    61  Given this Dockerfile:
    62  
    63  ```Dockerfile
    64  FROM hugo
    65  
    66  ADD .filebaserc /etc/
    67  ADD assets assets/
    68  COPY static-html static/
    69  COPY content/en content/
    70  ```
    71  
    72  And a `skaffold.yaml` with the following sync configuration:
    73  
    74  {{% readfile file="samples/filesync/filesync-infer.yaml" %}}
    75  
    76  - The first rule synchronizes the file `.filebaserc` to `/etc/.filebaserc` in the container.
    77  - The second rule synchronizes all `html` files in the `static-html` folder into the `<WORKDIR>/static` folder in the container.
    78    Note that this pattern does not match files in sub-folders below `static-html` (e.g. `static-html/a.html` but not `static-html/sub/a.html`).
    79  - The third rule synchronizes any `png`. For example if `assest/img.png` ↷ `assets/img.png` or `static-html/imgs/demo.png` ↷ `static/imgs/demo.png`.
    80  - The last rule enables synchronization for all `md` files below the `content/en`.
    81    For example, `content/en/sub/index.md` ↷ `content/sub/index.md` but _not_ `content/en_GB/index.md`.
    82    
    83  For Docker artifacts, inferred sync mode only applies to modified and added
    84  files; file deletion will cause a complete rebuild.
    85  
    86  For multi-stage Dockerfiles, Skaffold only examines the last stage.
    87  Use manual sync rules to sync file copies from other stages.
    88  
    89  [Ko artifacts supports syncing static content]({{<relref "/docs/builders/builder-types/ko#file-sync">}}),
    90  and the sync rules apply to added, modified, and deleted files.
    91  
    92  ### Auto sync mode
    93  
    94  In auto sync mode, Skaffold automatically generates sync rules for known file types. 
    95  Changes to other file types will result in a complete rebuild.
    96  
    97  #### Buildpacks
    98  
    99  Skaffold works with Cloud Native Buildpacks builders to automatically sync and relaunch
   100  applications on changes to certain types of files.
   101  The GCP Buildpacks builder ([gcr.io/buildpacks/builder:v1](https://github.com/GoogleCloudPlatform/buildpacks))
   102  supports syncing the following types of source files:
   103  
   104  - Go: *.go
   105  - Java: *.java, *.kt, *.scala, *.groovy, *.clj
   106  - NodeJS: *.js, *.mjs, *.coffee, *.litcoffee, *.json
   107  
   108  The GCP Buildpacks builder will detect the changed files and
   109  automatically rebuild and relaunch the application. 
   110  Changes to other file types trigger an image rebuild.
   111  
   112  ##### Disable Auto Sync for Buildpacks
   113  
   114  To disable auto sync, set `sync.auto = false`:
   115  
   116  ```
   117  artifacts:
   118  - image: xxx
   119    buildpacks:
   120      builder: gcr.io/buildpacks/builder:v1
   121    sync: 
   122      auto: false   # disable buildpacks auto-sync
   123  ```
   124  
   125  ##### How it works
   126  
   127  Skaffold requires special collaboration from buildpacks for the `auto` sync to work.
   128  
   129  Cloud Native Buildpacks set a `io.buildpacks.build.metadata` label on the images they create.
   130  This labels points to json description of the [Bill-of-Materials, aka BOM](https://github.com/buildpacks/spec/blob/main/buildpack.md#bill-of-materials-toml) of the build.
   131  In the BOM, under the `metadata.devmode.sync` key, Buildpacks that want to collaborate with Skaffold
   132  have to output the sync rules based on their exploration of the source and the build process they had to apply to it.
   133  Those sync rules will then be used by Skaffold without the user having to configure them manually.
   134  
   135  Another thing the Buildpacks have to do is support the `GOOGLE_DEVMODE` environment variable. Skaffold will
   136  set it to `1` when running `skaffold dev` with sync configured to `auto: true`. The Buildpacks can then use that
   137  signal to change the way the application is built so that it reloads the changes or rebuilds the app on each change.
   138  
   139  #### Jib
   140  
   141  Jib integration with Skaffold allows for zero-config `auto` sync. In this mode, Jib will sync your class files, resource files, and Jib's "extra directories" files to a remote container as changes are made. It can only be used with Jib in the default build mode (exploded) for non-WAR applications. It was primarily designed around [Spring Boot Developer Tools](https://docs.spring.io/spring-boot/docs/current/reference/html/using-spring-boot.html#using-boot-devtools), but can work with any embedded server that can reload/restart.
   142  
   143  Check out the [Jib Sync example](https://github.com/GoogleContainerTools/skaffold/tree/main/examples/jib-sync) for more details.
   144  
   145  ## Limitations
   146  
   147  File sync has some limitations:
   148  
   149    - File sync can only update files that can be modified by the container's configured User ID.
   150    - File sync requires the `tar` command to be available in the container.
   151    - Only local source files can be synchronized: files created by the builder will not be copied.
   152    - It is currently not allowed to mix `manual`, `infer` and `auto` sync modes.
   153      If you have a use-case for this, please let us know!