The platform team operates an SFTP gateway in the target environment. Clients retain their tools and user keys; server host-key trust and data placement need review.
#### Where the gateway runs, per environment When the environment has GKE, AKS or OKE, the gateway runs as a Kubernetes Deployment behind a Service. Without a cluster, it runs on the cloud-specific compute described below. The no-cluster Google Cloud target uses a Managed Instance Group with one VM; OCI uses an Instance Pool with one VM. Azure uses Container Apps with TCP ingress. Each host runs `atmoz/sftp` and provides storage, network access and restart handling.
Use Kubernetes when a cluster exists; otherwise use a Google Managed Instance Group, OCI Instance Pool or Azure Container App.
#### On a Kubernetes cluster A Kubernetes Deployment runs `atmoz/sftp` on port 22. A LoadBalancer Service exposes public endpoints; ClusterIP provides cluster-internal access. Clients elsewhere in the VPC need a private route or suitable internal endpoint rather than assuming ClusterIP is VPC-wide. The pod reads users from a ConfigMap and SSH public keys from a Secret at startup. An object-store CSI driver mounts the mapped bucket below the user's home directory: `gcsfuse.csi` on GKE, `blob.csi` on AKS or the OCI Object Storage CSI driver on OKE. The driver presents object data as files; review its filesystem semantics for the client's upload and rename behavior.
A Deployment serves SFTP behind a Service. ClusterIP is cluster-local; private VPC clients need an appropriate access path.
#### On a no-cluster Google Cloud stack: a Managed Instance Group The Google Cloud target uses a one-instance Managed Instance Group. A `google_compute_instance_template` defines startup of the `atmoz/sftp` container and a `gcsfuse` bucket mount. A network tag selects the firewall rule for port 22. `target_size = 1` provides one gateway instance. A port-22 health check drives autohealing, which replaces an unresponsive instance. The replacement reconnects to the bucket; active SSH sessions are lost. A TCP load balancer with a `google_compute_forwarding_rule` and reserved `google_compute_address` gives clients a stable endpoint during replacement. △ One thing to know about this host * **Object-backed mount behavior:** gcsfuse presents object storage as files. Review listing, rename, write visibility and locking for the selected driver and client workflow; CSI integration alone does not establish stronger filesystem guarantees.
A one-instance Managed Instance Group uses a port-22 health check and a load balancer with a stable endpoint.
#### On a no-cluster OCI stack: an Instance Pool The OCI target uses an Instance Pool with one VM defined by `oci_core_instance_configuration`. Cloud-init starts `atmoz/sftp` and mounts Object Storage through `s3fs` or `rclone` using the S3-compatible endpoint. The pool uses `size = 1` and replacement on failure. A security list or network security group permits port 22. An `oci_network_load_balancer` provides a stable endpoint across instance replacement. An OCI environment with OKE uses the Kubernetes deployment instead.
A one-instance OCI pool runs the gateway and object mount behind a network load balancer.
#### On a no-cluster Azure stack: a Container App Without AKS, the Azure target runs `atmoz/sftp` in the shared Container Apps environment. TCP ingress exposes port 22 publicly or internally as required. SSH public keys use a secret block, and `min_replicas = 1` keeps an instance running. That minimum alone does not enforce one instance; the deployment's maximum replica count and rollout settings must also preserve the single-instance design. The Container App mounts Azure Files over SMB for the user's home data. This differs from the Blob container mounted on AKS. Files uploaded here are not automatically visible to applications reading the mapped Blob container. Plan the data location and any required transfer explicitly.
Azure Container Apps serves TCP port 22 and mounts Azure Files. Configure replica limits to preserve the single-instance design.
#### The bucket as the SFTP home On Kubernetes and the VM hosts, the gateway exposes the mapped object store as files. File uploads become objects, and object contents can be read through SFTP. The Azure Container Apps target instead stores files in Azure Files. That exception matters when another application expects to read the mapped object bucket. Kubernetes uses an object-store CSI driver; Google Cloud VMs use `gcsfuse`; OCI VMs use `s3fs` or `rclone`. Object-backed mounts can differ from POSIX filesystems in locking, rename atomicity and write visibility. Azure Files is an SMB file share and has its own semantics. Test the relevant mount with the client's transfer workflow.
Object-store mounts expose bucket data on Kubernetes and VM hosts. Azure Container Apps uses Azure Files instead.
#### Users and SSH keys The user name, POSIX UID/GID and home path become an `SFTP_USERS` entry, such as `ada::e:1001:1001:/data`. The SSH public key becomes an authorized key. In atmoz syntax, `e` marks an encrypted password field; it is not a key-only switch. The empty password and supplied public key support key-based login. Configure writable subdirectories below the user's chroot home as required by atmoz. Kubernetes uses a ConfigMap and Secret; the VM hosts use startup or cloud-init configuration; Container Apps uses environment variables and secret entries. The uploaded SSH keys are public keys. Object-store credentials are separate from client authentication: use the host's supported workload identity or credential configuration for mounting storage.
User names, numeric identities, home paths and SSH public keys become host-specific gateway configuration.
#### Reachability on :22 Map public endpoints to the host's public Service, forwarding rule, network load balancer or TCP ingress. Private endpoints require the corresponding internal network configuration. On Kubernetes, ClusterIP limits access to the cluster; VPC clients outside it need an additional private access path. Verify reachability from the actual client networks. A public endpoint and a private endpoint require different load-balancer and firewall settings. On VM hosts, the load balancer also preserves the endpoint address while a failed instance is replaced.
Choose public or private endpoints for the client network. Kubernetes ClusterIP alone does not provide VPC-wide reachability.
#### Availability and concurrent transfers The gateway uses a single-instance design to reduce concurrent writes through object-backed mounts. Kubernetes uses `replicas = 1`, the Google group uses `target_size = 1`, and the OCI pool uses `size = 1`. For Container Apps, configure the maximum replica count as well as `min_replicas = 1`. One server can still handle concurrent sessions, so test conflicting uploads and rename behavior; a single instance does not provide filesystem locking. Recovery replaces the gateway and reconnects it to its backing storage. Active SSH sessions are interrupted, and clients must retry or resume transfers as supported. This is not active-active availability. Size the server for peak connections and throughput, and persist host keys if clients must retain the same server fingerprint after replacement.
Recovery restarts a single gateway against its storage and interrupts SSH sessions. Size the gateway for peak load.
#### Limitations Review protocol support, identity-provider limits, storage semantics, private reachability and gateway operation before migration. △ Where AWS Transfer Family and a self-hosted SFTP gateway diverge * **User updates need restart.** Update the `SFTP_USERS` and SSH-key configuration and restart the gateway; there is no Transfer user-management API. * **Unsupported protocols and identity providers.** FTPS, FTP, `AWS_LAMBDA` and `API_GATEWAY` identity providers return build errors. The target supports SFTP with its configured user directory. * **Security and logging are operational responsibilities.** Configure sshd policy and image updates in place of `security_policy_name`. Collect gateway stdout through the target environment's logging in place of `logging_role` and CloudWatch. #### Other considerations Before cutover, transfer bucket data through the backing-store migration, or provision the separate Azure Files share where applicable. Active SFTP sessions do not transfer. Configure persistent server host keys if clients must keep the same fingerprint across gateway restarts. Assign responsibility for gateway updates, capacity, user changes and log collection. Configure backup, versioning and retention on the actual backing store. A restart can preserve completed files without preserving an in-flight upload. [Service Catalog](/service-adapters/catalog).