SFTPGo

Overview

SFTPGo is an SFTP server backed by object storage. Clients speak standard SFTP; files land in your bucket, with per-user folder isolation and declarative user management. This template offers a choice between an always-on server and a scale-to-zero mode that suspends the server when idle behind a tiny always-on proxy.

Architecture

SFTPGo — A single-replica stateful workload serving SFTP on port 2022. An embedded bolt database and the SSH host keys persist on a volume set so host keys stay stable across restarts and wakes.
Scale-to-zero proxy (scale_to_zero mode only) — An always-on activator workload that accepts client connections while SFTPGo sleeps, wakes it via the platform API, splices traffic through, and suspends it again after an idle window.

What Gets Created

Stateful SFTPGo Workload — Serves SFTP on port 2022; holds the embedded database and SSH host keys.
Standard Scale-to-Zero Proxy Workload (scale_to_zero mode only) — Always-on TCP activator that fronts SFTPGo and manages suspend/wake.
Volume Set — 10 GiB persistent storage for the embedded database and SSH host keys.
Secrets — A dictionary secret with the admin bootstrap credentials and an opaque secret with the declared-users file.
Identity & Policy — An identity bound to the workloads with reveal access to the secrets, keyless cloud storage access for AWS and GCP backends, and a least-privilege policy letting the proxy’s identity suspend and wake exactly the SFTPGo workload — nothing else.

This template does not create a GVC. You must deploy it into an existing GVC.

Prerequisites

SFTPGo requires an existing bucket in one of the supported backends and the access setup for it. Complete the steps for your chosen backend before installing.

AWS S3 (keyless)
Google Cloud Storage (keyless)
S3-compatible (MinIO, R2, Wasabi)

AWS S3 uses a Control Plane cloud identity — no credentials are stored; the workload’s identity vends temporary credentials at runtime.

Create a bucket

Create an S3 bucket. Set storage.aws.bucket and storage.aws.region to match.

Set up a Cloud Account

If you do not have one, create a Cloud Account for your AWS account. Set storage.aws.cloudAccountName to its name.

Create a bucket-scoped IAM policy

Create an AWS IAM policy with the JSON below (replace YOUR_BUCKET), then set storage.aws.policyName to the policy’s name (bare name, not ARN):

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "s3:ListBucket",
      "s3:GetBucketLocation",
      "s3:GetObject",
      "s3:PutObject",
      "s3:DeleteObject",
      "s3:AbortMultipartUpload"
    ],
    "Resource": [
      "arn:aws:s3:::YOUR_BUCKET",
      "arn:aws:s3:::YOUR_BUCKET/*"
    ]
  }]
}

Google Cloud Storage uses a Control Plane cloud identity — no credentials are stored.

Create a bucket

Create a GCS bucket. Set storage.gcp.bucket to its name.

Set up a Cloud Account

If you do not have one, create a Cloud Account for your GCP project. Set storage.gcp.cloudAccountName to its name.

Confirm bucket access

No policy to author — the template grants the workload identity roles/storage.objectAdmin scoped to the bucket automatically. Ensure your cloud account setup permits its service account to receive that binding.

Any S3-compatible server uses static access credentials, since these cannot federate with a cloud account.

Create a bucket

Create your bucket on the server. Set storage.minio.bucket to its name.

Set the endpoint

Set storage.minio.endpoint to the S3 API address including port. For the minio marketplace template deployed in the same GVC, this is http://WORKLOAD_NAME:9000.

Set credentials

Set storage.minio.accessKey and storage.minio.accessSecret to credentials with access to the bucket. For the MinIO template, these are its admin.username and admin.password.

Once your backend is ready, install the template using your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Choosing a Mode

The mode value selects how SFTPGo runs. scale_to_zero (the default) suspends the server when idle to save cost; always_warm keeps it running for instant connections.

	`scale_to_zero` (default)	`always_warm`
Cost when idle	Proxy (~100m/128Mi) + the dedicated load balancer	Full SFTPGo replica + load balancer
First connect after idle	~30s cold start (occasionally up to ~75s)	Instant
Client requirements	Timeout ≥120s or retry (see below)	None — works unchanged
Best for	Cost-sensitive, periodic transfers, cooperative clients	Strict SLAs, arbitrary third-party clients

Configuration

The default values.yaml for this template:

image: drakkan/sftpgo:v2.7.4-distroless-slim

mode: scale_to_zero # options: scale_to_zero, always_warm

scaleToZero: # only used when mode is scale_to_zero
  idleHold: 5m # suspend after this window with no active connections (e.g. 90s, 5m, 1h)
  proxy:
    image: ghcr.io/controlplane-com/scale-to-zero-proxy:0.1.0
    resources: # all SFTP traffic flows through the proxy
      cpu: 500m
      memory: 256Mi
      minCpu: 100m
      minMemory: 128Mi

resources: # SFTPGo container; CPU governs transfer throughput and wake speed
  cpu: 1000m
  memory: 512Mi
  minCpu: 250m
  minMemory: 256Mi

admin: # SFTPGo administrator (REST API / optional web admin), created on first boot
  username: admin
  password: change-me-sftpgo-admin # change before installing

storage:
  type: aws # options: aws, gcp, minio

  aws: # AWS S3 — keyless via Control Plane cloud identity
    bucket: my-sftp-bucket # bucket must already exist
    region: us-east-1
    keyPrefix: "" # optional bucket-wide folder prefix, e.g. sftp/
    cloudAccountName: my-s3-cloud-account # Control Plane AWS cloud account
    policyName: my-sftp-s3-policy # custom IAM policy granting bucket access (bare name)

  gcp: # Google Cloud Storage — keyless via Control Plane cloud identity
    bucket: my-sftp-bucket # bucket must already exist
    keyPrefix: "" # optional bucket-wide folder prefix, e.g. sftp/
    cloudAccountName: my-gcs-cloud-account # Control Plane GCP cloud account

  minio: # Any S3-compatible server (MinIO, R2, Wasabi, …) — static keys only
    endpoint: http://my-minio-workload:9000 # e.g. an internal MinIO template deployment
    bucket: my-sftp-bucket # bucket must already exist
    region: us-east-1
    keyPrefix: "" # optional bucket-wide folder prefix, e.g. sftp/
    accessKey: my-minio-username
    accessSecret: my-minio-password

users: # Declarative user list, re-applied on every start
  - username: sftpuser
    password: change-me-sftp-user # omit when publicKeys is set
    publicKeys: [] # SSH public keys, e.g. ["ssh-ed25519 AAAA... user@laptop"]
    # keyPrefix: custom/folder/ # optional per-user bucket folder override

volumeset:
  capacity: 10 # GiB (minimum 10) — stores the embedded database and SSH host keys

publicAccess:
  enabled: true # public SFTP endpoint (dedicated NLB) on the client-facing workload

internalAccess: # internal firewall scope of the SFTPGo workload
  type: same-gvc # options: none, same-gvc, same-org, workload-list (scale_to_zero requires non-none)
  workloads: [] # used with workload-list; the scale-to-zero proxy is added automatically

webAdmin:
  enabled: false # declare SFTPGo's web admin/REST API port 8080

Mode

mode — scale_to_zero (default) or always_warm. See Choosing a Mode.
scaleToZero.idleHold — Suspend SFTPGo after this window with no active connections (e.g. 90s, 5m, 1h). Used only in scale_to_zero mode.
scaleToZero.proxy.image / scaleToZero.proxy.resources — Image and resources for the always-on activator proxy. All SFTP traffic flows through the proxy, so provision its CPU accordingly.

image — The SFTPGo container image.
resources — CPU and memory for the SFTPGo container. CPU governs transfer throughput and wake speed.
admin.username / admin.password — The SFTPGo administrator, created on first boot for the REST API and optional web admin. Change the password before installing.
volumeset.capacity — Volume size in GiB (minimum 10) for the embedded database and SSH host keys.
webAdmin.enabled — Declare SFTPGo’s web admin / REST API on port 8080. Reachable via the canonical endpoint in always_warm mode when publicAccess is enabled.

Storage Backend

Set storage.type to aws, gcp, or minio, and configure that block. AWS and GCP use a Control Plane cloud identity — no credentials are stored; the workload’s identity vends temporary credentials at runtime. See Prerequisites for the per-backend setup steps.

Field	Backends	Description
`bucket`	all	Target bucket. Must already exist.
`region`	`aws`, `minio`	Bucket region.
`keyPrefix`	all	Optional bucket-wide folder prefix, e.g. `sftp/`.
`cloudAccountName`	`aws`, `gcp`	Control Plane cloud account for keyless access.
`policyName`	`aws`	Bare name of the custom bucket-scoped IAM policy.
`endpoint`	`minio`	S3 API address including port.
`accessKey` / `accessSecret`	`minio`	Static credentials with access to the bucket.

Users

Declared users are re-applied on every start; each is isolated to the bucket folder {keyPrefix}{username}/ unless overridden per user. Provide a password, one or more publicKeys, or both.

users[].username — Login name.
users[].password — Password. Omit when publicKeys is set.
users[].publicKeys — SSH public keys, e.g. ["ssh-ed25519 AAAA... user@laptop"].
users[].keyPrefix — Optional per-user bucket folder override.

Access

publicAccess.enabled — Expose a public SFTP endpoint on the client-facing workload via a dedicated direct load balancer, required for raw-TCP protocols like SFTP. Set to false for an internal-only endpoint (no load balancer; clients reach SFTPGo over the GVC network).
internalAccess.type — Internal firewall scope of the SFTPGo workload:

Type	Description
`none`	No internal access. Not allowed in `scale_to_zero` mode (the proxy must reach SFTPGo).
`same-gvc`	Allow access from all workloads in the same GVC.
`same-org`	Allow access from all workloads in the same organization.
`workload-list`	Allow access only from workloads listed in `internalAccess.workloads`. The scale-to-zero proxy is added automatically.

Connecting

What	Value
Public SFTP endpoint	`tcp://...cpln.app:2022` — `status.endpoint` of `{release}-sftpgo-proxy` (scale_to_zero) or `{release}-sftpgo` (always_warm)
Connect	`sftp -P 2022 {username}@{endpoint-host}`
In-GVC (internal)	`{release}-sftpgo-proxy:2022` (scale_to_zero) or `{release}-sftpgo:2022` (always_warm)
Web admin (if enabled)	Canonical `*.cpln.app` endpoint of `{release}-sftpgo` (always_warm + publicAccess)
Credentials	`users[]` entries; admin per `admin.*`

Cold Starts and Client Configuration

In scale_to_zero mode, the first connection after an idle period wakes the server (measured ~30s, occasionally up to ~75s — the persistent volume attaches on each wake). The proxy holds the TCP connection so nothing is refused, but clients with short SSH banner timeouts (~15s in several libraries) give up right at the finish line. Configure clients generously:

paramiko — connect(..., banner_timeout=120, timeout=120)
WinSCP — Session → Timeout ≥ 120s
OpenSSH CLI — Tolerant by default; no change needed
Unattended jobs — Retry with backoff. The first (even failed) attempt triggers the wake, and idleHold keeps the server warm so the retry lands instantly.
Right after install — The load balancer needs a few minutes to warm up; the very first cold connect may time out once, then succeed on retry.

For third-party clients you cannot configure, use always_warm.

Important Notes

Change the default admin and user passwords before installing. The admin bootstrap only applies on first boot; changing admin.* later requires the REST API.
Declared users are authoritative — edits made to them via the admin API/UI are overwritten on the next restart or wake. Users created via the API are untouched.
Upgrading while suspended wakes the server; it re-suspends after the next connection comes and goes.
First install: the public endpoint’s DNS takes a few minutes to propagate after the load balancer is created.
Switching modes moves the client-facing endpoint (proxy ↔ SFTPGo) — plan a client cutover if you change modes on a live install.
The dedicated load balancer is the dominant idle cost in scale_to_zero mode, not the proxy’s compute.

External References

SFTPGo Documentation

Official SFTPGo documentation

S3 Storage Backend

SFTPGo S3-compatible storage backend guide

Environment Variables

SFTPGo environment variables reference

Scale-to-Zero Proxy

Source for the always-on TCP activator proxy

SFTPGo Template

View the source files, default values, and chart definition

​Overview

​Architecture

​What Gets Created

​Prerequisites

UI

CLI

Terraform

Pulumi

​Choosing a Mode

​Configuration

​Mode

​SFTPGo

​Storage Backend

​Users

​Access

​Connecting

​Cold Starts and Client Configuration

​Important Notes

​External References

SFTPGo Documentation

S3 Storage Backend

Environment Variables

Scale-to-Zero Proxy

SFTPGo Template

Overview

Architecture

What Gets Created

Prerequisites

Choosing a Mode

Configuration

Mode

SFTPGo

Storage Backend

Users

Access

Connecting

Cold Starts and Client Configuration

Important Notes

External References