Create an internal SFTP server

This document shows how to create an internal SFTP server by using Cloud FTP. An internal SFTP server can be accessed only within your Virtual Private Cloud (VPC) network by using Private Service Connect. Employees and internal stakeholders who are within your network can use the server to securely transfer files to and from Cloud Storage.

You specify the projects that are allowed to connect to the server. You can optionally specify projects that are rejected from connecting.

For background information about VPC, see VPC overview.

For steps to create an external server, which can be accessed over the internet, see Create an external SFTP server. You can't change whether a server is external or internal after the server has been created.

Before you begin

Console

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud FTP API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud FTP API, if it is not already enabled.

Roles required to enable APIs

Enable the API

Collect the following information about your server's users:
- A list of project IDs or project numbers that are allowed to access the server.
- (Optional) A list of project IDs or project numbers that are rejected from accessing the server.

gcloud

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud FTP API, if it is not already enabled:

Roles required to enable APIs

gcloud services enable ftp.googleapis.com

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud FTP API, if it is not already enabled:

Roles required to enable APIs

gcloud services enable ftp.googleapis.com

Collect the following information about your server's users:
- A list of project IDs or project numbers that are allowed to access the server.
- (Optional) A list of project IDs or project numbers that are rejected from accessing the server.

Required roles

To get the permission that you need to create an SFTP server, ask your administrator to grant you the Cloud FTP Admin (roles/ftp.admin) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the ftp.servers.create permission, which is required to create an SFTP server.

You might also be able to get this permission with custom roles or other predefined roles.

Create an internal server

Console

In the Google Cloud console, go to the Cloud FTP page.
Go to Cloud FTP
Click Create server.
On the Server configuration tab, enter basic details for the server:
1. In the Server ID field, enter a unique ID for the server.
2. In the Region list, select the Google Cloud location for the server.
  
  For the fastest data transfer speeds, create the server in the same location as the Cloud Storage bucket that stores your data. If the bucket's location isn't supported by Cloud FTP, then select the nearest available location.
3. (Optional) Enter a display name for the server.
4. Click Continue.
On the Networking and security tab, configure connectivity for the server:
1. Select Internal (VPC only).
2. In the Accepted projects section, specify the consumer projects that are allowed to connect to the server by using Private Service Connect. Do the following:
  1. In the Project field, enter the project ID or number of a project that is allowed to connect. For example, example-allowed-project.
  2. In the Connection limit field, enter the maximum number of Private Service Connect endpoints that can be created in the consumer project. The value must be from 1 to 250 endpoints.
  3. To add more projects, click Add accepted project, and then repeat the previous steps.
3. (Optional) To prohibit projects from connecting to the server, in the Rejected projects section, click Add rejected project. Enter the project ID or number of a consumer project that is prohibited from connecting to the server.
  
  Projects in this list are rejected from accessing the server even if they are included in the list of allowed projects.
Click Create.

It takes about 10 minutes for the server to be created.

gcloud

To create an internal server, run the gcloud alpha storage ftp servers create command and provide the --access-type=INTERNAL flag.

Before using any of the command data below, make the following replacements:

SERVER_ID: a unique ID for the server. Must start with a lowercase letter, and end with a lowercase letter or number. Can contain lowercase letters, numbers, and hyphens. Maximum length is 30 characters.
LOCATION_ID: the Google Cloud location of the server, such as us-west1.

For the fastest data transfer speeds, create the server in the same location as the Cloud Storage bucket that stores your data. If the bucket's location isn't supported by Cloud FTP, then select the nearest available location.
PROJECT_TO_ALLOW: the project ID or number of a consumer project that is allowed to connect to the server by using Private Service Connect. For example, example-allowed-project. You must specify at least one project.

You can allow a maximum of 500 projects. Provide multiple projects and their respective connection limits in a comma-separated list. For example, --consumer-accept-list=projectA=20,projectB=15.
CONNECTION_LIMIT: the maximum number of Private Service Connect endpoints that can be created in the consumer project. The value must be from 1 to 250 endpoints.
(Optional) PROJECT_TO_REJECT: the project ID or number of a consumer project that is prohibited from connecting to the server. For example, example-rejected-project. Projects in this list are rejected from accessing the server even if they are included in the list of allowed projects.

You can reject a maximum of 64 projects. Provide multiple projects in a comma-separated list.
If you don't want to explicitly reject any projects, then omit the --consumer-reject-list flag.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud alpha storage ftp servers create SERVER_ID --access-type=INTERNAL \
    --location=LOCATION_ID \
    --consumer-accept-list=PROJECT_TO_ALLOW=CONNECTION_LIMIT \
    --consumer-reject-list=PROJECT_TO_REJECT

Windows (PowerShell)

gcloud alpha storage ftp servers create SERVER_ID --access-type=INTERNAL `
    --location=LOCATION_ID `
    --consumer-accept-list=PROJECT_TO_ALLOW=CONNECTION_LIMIT `
    --consumer-reject-list=PROJECT_TO_REJECT

Windows (cmd.exe)

gcloud alpha storage ftp servers create SERVER_ID --access-type=INTERNAL ^
    --location=LOCATION_ID ^
    --consumer-accept-list=PROJECT_TO_ALLOW=CONNECTION_LIMIT ^
    --consumer-reject-list=PROJECT_TO_REJECT

It takes about 10 minutes for the server to be created.

REST

To create an internal server, use the servers.create method and provide an internalConfig access configuration.

Before using any of the request data, make the following replacements:

PROJECT_ID: the Google Cloud project ID of the server.
LOCATION_ID: the Google Cloud location of the server, such as us-west1.

For the fastest data transfer speeds, create the server in the same location as the Cloud Storage bucket that stores your data. If the bucket's location isn't supported by Cloud FTP, then select the nearest available location.
SERVER_ID: a unique ID for the server. Must start with a lowercase letter, and end with a lowercase letter or number. Can contain lowercase letters, numbers, and hyphens. Maximum length is 30 characters.
PROJECT_TO_ALLOW: the project ID or number of a consumer project that is allowed to connect to the server by using Private Service Connect. For example, example-allowed-project. You must specify at least one project.

You can allow a maximum of 500 projects.
CONNECTION_LIMIT: the maximum number of Private Service Connect endpoints that can be created in the consumer project. The value must be from 1 to 250 endpoints.
(Optional) PROJECT_TO_REJECT: the project ID or number of a consumer project that is prohibited from connecting to the server. For example, example-rejected-project. Projects in this list are rejected from accessing the server even if they are included in the list of allowed projects.

You can reject a maximum of 64 projects.

If you don't want to explicitly reject any projects, then omit the consumerRejectList object.

HTTP method and URL:

POST https://ftp.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/servers?serverId=SERVER_ID

Request JSON body:

{
  "accessType": "INTERNAL",
  "internalConfig": {
    "consumerAcceptList": [
      {
        "project": "projects/PROJECT_TO_ALLOW",
        "connectionLimit": CONNECTION_LIMIT
      }
    ],
    "consumerRejectList": [
      {
        "project": "projects/PROJECT_TO_REJECT"
      }
    ]
  }
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://ftp.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/servers?serverId=SERVER_ID"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://ftp.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/servers?serverId=SERVER_ID" | Select-Object -Expand Content

The response identifies a long-running operation.

It takes about 10 minutes for the server to be created.

Client libraries

C#

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP C# API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

using Google.Cloud.Ftp.V1;
using Google.LongRunning;
using System.Threading.Tasks;

public sealed partial class GeneratedCloudFtpClientSnippets
{
    /// <summary>Snippet for CreateServerAsync</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public async Task CreateServerAsync()
    {
        // Create client
        CloudFtpClient cloudFtpClient = await CloudFtpClient.CreateAsync();
        // Initialize request argument(s)
        string parent = "projects/[PROJECT]/locations/[LOCATION]";
        Server server = new Server();
        string serverId = "";
        // Make the request
        Operation<Server, OperationMetadata> response = await cloudFtpClient.CreateServerAsync(parent, server, serverId);

        // Poll until the returned long-running operation is complete
        Operation<Server, OperationMetadata> completedResponse = await response.PollUntilCompletedAsync();
        // Retrieve the operation result
        Server result = completedResponse.Result;

        // Or get the name of the operation
        string operationName = response.Name;
        // This name can be stored, then the long-running operation retrieved later by name
        Operation<Server, OperationMetadata> retrievedResponse = await cloudFtpClient.PollOnceCreateServerAsync(operationName);
        // Check if the retrieved long-running operation has completed
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result
            Server retrievedResult = retrievedResponse.Result;
        }
    }
}

Go

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP Go API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.


//go:build examples

package main

import (
	"context"

	ftp "cloud.google.com/go/ftp/apiv1"
	ftppb "cloud.google.com/go/ftp/apiv1/ftppb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := ftp.NewCloudFtpRESTClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &ftppb.CreateServerRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/ftp/apiv1/ftppb#CreateServerRequest.
	}
	op, err := c.CreateServer(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}

	resp, err := op.Wait(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP Java API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.api.core.ApiFuture;
import com.google.cloud.ftp.v1.CloudFtpClient;
import com.google.cloud.ftp.v1.CreateServerRequest;
import com.google.cloud.ftp.v1.LocationName;
import com.google.cloud.ftp.v1.Server;
import com.google.longrunning.Operation;

public class AsyncCreateServer {

  public static void main(String[] args) throws Exception {
    asyncCreateServer();
  }

  public static void asyncCreateServer() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (CloudFtpClient cloudFtpClient = CloudFtpClient.create()) {
      CreateServerRequest request =
          CreateServerRequest.newBuilder()
              .setParent(LocationName.of("[PROJECT]", "[LOCATION]").toString())
              .setServerId("serverId1379103678")
              .setServer(Server.newBuilder().build())
              .setRequestId("requestId693933066")
              .build();
      ApiFuture<Operation> future = cloudFtpClient.createServerCallable().futureCall(request);
      // Do something.
      Operation response = future.get();
    }
  }
}

Node.js

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP Node.js API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

/**
 * This snippet has been automatically generated and should be regarded as a code template only.
 * It will require modifications to work.
 * It may require correct/in-range values for request initialization.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Required. Value for parent.
 */
// const parent = 'abc123'
/**
 *  Required. A unique ID for the server. Must start with a lowercase letter,
 *  and end with a lowercase letter or number. Can contain lowercase letters,
 *  numbers, and hyphens. Maximum length is 30 characters.
 */
// const serverId = 'abc123'
/**
 *  Required. The resource being created
 */
// const server = {}
/**
 *  Optional. An optional request ID to identify requests. Specify a unique
 *  request ID so that if you must retry your request, the server will know to
 *  ignore the request if it has already been completed. The server will
 *  guarantee that for at least 60 minutes since the first request.
 *  For example, consider a situation where you make an initial request and the
 *  request times out. If you make the request again with the same request
 *  ID, the server can check if original operation with the same request ID
 *  was received, and if so, will ignore the second request. This prevents
 *  clients from accidentally creating duplicate commitments.
 *  The request ID must be a valid UUID with the exception that zero UUID is
 *  not supported (00000000-0000-0000-0000-000000000000).
 */
// const requestId = 'abc123'

// Imports the Ftp library
const {CloudFtpClient} = require('@google-cloud/ftp').v1;

// Instantiates a client
const ftpClient = new CloudFtpClient();

async function callCreateServer() {
  // Construct request
  const request = {
    parent,
    serverId,
    server,
  };

  // Run request
  const [operation] = await ftpClient.createServer(request);
  const [response] = await operation.promise();
  console.log(response);
}

callCreateServer();

PHP

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP PHP API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

use Google\ApiCore\ApiException;
use Google\ApiCore\OperationResponse;
use Google\Cloud\Ftp\V1\Client\CloudFtpClient;
use Google\Cloud\Ftp\V1\CreateServerRequest;
use Google\Cloud\Ftp\V1\Server;
use Google\Cloud\Ftp\V1\Server\AccessType;
use Google\Rpc\Status;

/**
 * Creates a new Server in a given project and location.
 *
 * @param string $formattedParent  Value for parent. Please see
 *                                 {@see CloudFtpClient::locationName()} for help formatting this field.
 * @param string $serverId         A unique ID for the server. Must start with a lowercase letter,
 *                                 and end with a lowercase letter or number. Can contain lowercase letters,
 *                                 numbers, and hyphens. Maximum length is 30 characters.
 * @param int    $serverAccessType The access type of the Server.
 */
function create_server_sample(
    string $formattedParent,
    string $serverId,
    int $serverAccessType
): void {
    // Create a client.
    $cloudFtpClient = new CloudFtpClient();

    // Prepare the request message.
    $server = (new Server())
        ->setAccessType($serverAccessType);
    $request = (new CreateServerRequest())
        ->setParent($formattedParent)
        ->setServerId($serverId)
        ->setServer($server);

    // Call the API and handle any network failures.
    try {
        /** @var OperationResponse $response */
        $response = $cloudFtpClient->createServer($request);
        $response->pollUntilComplete();

        if ($response->operationSucceeded()) {
            /** @var Server $result */
            $result = $response->getResult();
            printf('Operation successful with response data: %s' . PHP_EOL, $result->serializeToJsonString());
        } else {
            /** @var Status $error */
            $error = $response->getError();
            printf('Operation failed with error data: %s' . PHP_EOL, $error->serializeToJsonString());
        }
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $formattedParent = CloudFtpClient::locationName('[PROJECT]', '[LOCATION]');
    $serverId = '[SERVER_ID]';
    $serverAccessType = AccessType::ACCESS_TYPE_UNSPECIFIED;

    create_server_sample($formattedParent, $serverId, $serverAccessType);
}

Python

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP Python API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import ftp_v1


def sample_create_server():
    # Create a client
    client = ftp_v1.CloudFtpClient()

    # Initialize request argument(s)
    server = ftp_v1.Server()
    server.access_type = "INTERNAL"

    request = ftp_v1.CreateServerRequest(
        parent="parent_value",
        server_id="server_id_value",
        server=server,
    )

    # Make the request
    operation = client.create_server(request=request)

    print("Waiting for operation to complete...")

    response = operation.result()

    # Handle the response
    print(response)

Ruby

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP Ruby API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

require "google/cloud/ftp/v1"

##
# Snippet for the create_server call in the CloudFtp service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::Ftp::V1::CloudFtp::Rest::Client#create_server.
#
def create_server
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::Ftp::V1::CloudFtp::Rest::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::Ftp::V1::CreateServerRequest.new

  # Call the create_server method.
  result = client.create_server request

  # The returned object is of type Gapic::Operation. You can use it to
  # check the status of an operation, cancel it, or wait for results.
  # Here is how to wait for a response.
  result.wait_until_done! timeout: 60
  if result.response?
    p result.response
  else
    puts "No response received."
  end
end

Create an internal SFTP server Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Console

gcloud

Required roles

Create an internal server

Console

gcloud

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Client libraries

C#

Go

Java

Node.js

PHP

Python

Ruby

What's next

Create an internal SFTP server