Skaffold Filesync

Skaffold File Sync

When to Use This Skill

Overview

File sync copies changed files directly to running containers, avoiding image rebuilds. This dramatically speeds up the development loop for interpreted languages and static assets.

Without sync: Edit → Build Image → Deploy → Restart Pod → Test (~30-60s)
With sync:    Edit → Copy File → Test (~1-2s)

How It Works

1. Skaffold watches for file changes
2. Creates a tar archive of modified files matching sync rules
3. Extracts the archive in the running container
4. Application picks up changes (hot reload, file watch, etc.)

Three Sync Modes

Important: Cannot mix modes - choose one per artifact.

Manual Sync

Explicitly map source files to container destinations.

Basic Configuration

apiVersion: skaffold/v4beta13
kind: Config
build:
  artifacts:
    - image: my-app
      context: .
      docker:
        dockerfile: Dockerfile
      sync:
        manual:
          - src: "src/**/*.js"
            dest: /app/src
          - src: "public/**/*"
            dest: /app/public

With Directory Stripping

Use strip to remove directory levels from the source path:

sync:
  manual:
    # src/components/Button.js → /app/Button.js (strips 'src/components/')
    - src: "src/components/**/*.js"
      dest: /app
      strip: "src/components/"

    # assets/images/logo.png → /var/www/static/logo.png
    - src: "assets/images/**/*"
      dest: /var/www/static
      strip: "assets/images/"

Static Assets Example

sync:
  manual:
    # HTML files to nginx root
    - src: "static/*.html"
      dest: /usr/share/nginx/html

    # CSS with directory structure preserved
    - src: "static/css/**/*.css"
      dest: /usr/share/nginx/html/css
      strip: "static/css/"

    # Images
    - src: "static/images/**/*"
      dest: /usr/share/nginx/html/images
      strip: "static/images/"

Node.js Hot Reload Example

build:
  artifacts:
    - image: node-app
      sync:
        manual:
          - src: "src/**/*.ts"
            dest: /app/src
          - src: "src/**/*.tsx"
            dest: /app/src
          - src: "*.json"
            dest: /app

Pair with nodemon or ts-node-dev in container:

CMD ["npx", "nodemon", "--watch", "/app/src", "src/index.ts"]

Python Hot Reload Example

build:
  artifacts:
    - image: python-app
      sync:
        manual:
          - src: "app/**/*.py"
            dest: /app
          - src: "templates/**/*.html"
            dest: /app/templates
            strip: "templates/"

Pair with Flask debug mode or uvicorn reload:

CMD ["uvicorn", "main:app", "--reload", "--host", "0.0.0.0"]

Inferred Sync

Skaffold automatically determines destinations from Dockerfile COPY/ADD instructions.

Configuration

build:
  artifacts:
    - image: my-app
      docker:
        dockerfile: Dockerfile
      sync:
        infer:
          - "**/*.js"
          - "**/*.css"
          - "**/*.html"

How Inference Works

Given this Dockerfile:

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY src/ ./src/        # Skaffold infers: src/* → /app/src/*
COPY public/ ./public/  # Skaffold infers: public/* → /app/public/*

Skaffold analyzes COPY instructions to determine sync destinations.

Limitations

Auto Sync

Zero-configuration sync for supported builders.

Buildpacks (Cloud Native Buildpacks)

build:
  artifacts:
    - image: my-app
      buildpacks:
        builder: gcr.io/buildpacks/builder:v1
      sync:
        auto: true  # Enabled by default for buildpacks

Supported languages:

• Go: .go files
• Java: .java, .kt, .properties, .xml files
• Node.js: .js, .ts, .json files

Disable auto sync:

sync:
  auto: false

Jib (Java)

build:
  artifacts:
    - image: my-app
      jib: {}
      sync:
        auto: true  # Enabled by default for Jib

Auto-syncs:

• Class files (compiled)
• Resource files
• Extra directory files

Full Configuration Examples

Node.js Development Stack

apiVersion: skaffold/v4beta13
kind: Config
metadata:
  name: node-app

build:
  local:
    push: false
    useBuildkit: true
  artifacts:
    - image: node-app
      context: .
      docker:
        dockerfile: Dockerfile
      sync:
        manual:
          - src: "src/**/*.ts"
            dest: /app/src
          - src: "src/**/*.tsx"
            dest: /app/src
          - src: "public/**/*"
            dest: /app/public

deploy:
  kubeContext: orbstack
  kubectl:
    manifests:
      - k8s/*.yaml

Python FastAPI Stack

apiVersion: skaffold/v4beta13
kind: Config
metadata:
  name: fastapi-app

build:
  local:
    push: false
  artifacts:
    - image: fastapi-app
      sync:
        manual:
          - src: "app/**/*.py"
            dest: /code/app
          - src: "templates/**/*.html"
            dest: /code/templates
            strip: "templates/"
          - src: "static/**/*"
            dest: /code/static
            strip: "static/"

deploy:
  kubeContext: orbstack
  kubectl:
    manifests:
      - k8s/*.yaml

Go with Air (Hot Reload)

apiVersion: skaffold/v4beta13
kind: Config
metadata:
  name: go-app

build:
  artifacts:
    - image: go-app
      sync:
        manual:
          - src: "**/*.go"
            dest: /app
          - src: "go.mod"
            dest: /app
          - src: "go.sum"
            dest: /app

deploy:
  kubeContext: orbstack
  kubectl:
    manifests:
      - k8s/*.yaml

With Air in Dockerfile:

FROM golang:1.22-alpine
RUN go install github.com/cosmtrek/air@latest
WORKDIR /app
COPY . .
CMD ["air", "-c", ".air.toml"]

Static Site with Nginx

apiVersion: skaffold/v4beta13
kind: Config
metadata:
  name: static-site

build:
  artifacts:
    - image: static-site
      sync:
        manual:
          - src: "dist/**/*"
            dest: /usr/share/nginx/html
            strip: "dist/"

deploy:
  kubeContext: orbstack
  kubectl:
    manifests:
      - k8s/*.yaml

Requirements and Limitations

Container Requirements

What Cannot Be Synced

Sync vs Rebuild Decision

Debugging Sync Issues

Verify Sync Is Working

# Watch Skaffold output for sync messages
skaffold dev -v info

# Look for:
# Syncing 1 files for my-app:latest
# Watching for changes...

Check Container Has tar

kubectl exec -it <pod> -- which tar
# Should output: /bin/tar or /usr/bin/tar

Verify File Permissions

kubectl exec -it <pod> -- ls -la /app/src/
# Check files are writable by container user

Test Manual Sync Path

# Verify destination exists in container
kubectl exec -it <pod> -- ls -la /app/

# Check container user
kubectl exec -it <pod> -- whoami

Profiles for Sync vs Rebuild

profiles:
  # Fast iteration - sync enabled
  - name: dev
    build:
      artifacts:
        - image: my-app
          sync:
            manual:
              - src: "src/**/*"
                dest: /app/src

  # CI/Production - no sync, full rebuilds
  - name: ci
    build:
      artifacts:
        - image: my-app
          # No sync configuration

Agentic Optimizations

Quick Reference

Sync Configuration Fields

Sync Modes Comparison

Glob Patterns