Object Storage Service:Access OSS over a private network via PrivateLink

Step 1: Create the endpoint

1. Go to the VPC endpoint page and click Create Endpoint. If this is your first time, follow the on-screen prompts to activate the PrivateLink service.

2. Configure the following parameters. Leave all other settings at their defaults.

   • Region: Select the region where your target OSS bucket resides, for example, China (Hangzhou).

   • Endpoint Name: Enter a descriptive name, for example, privatelink-oss.

   • Endpoint Type: Select Interface Endpoint.

   • Endpoint Service: Select Alibaba Cloud Service, then select the OSS endpoint service from the list (the entry whose name ends with oss).

     Note

     If no OSS endpoint service appears in the list, contact technical supporttechnical support to request activation.

   • VPC: Select the VPC where you want to create the endpoint. If no VPC is available, click Create VPC to create one.

   • Security Groups: Select the security group to bind to the endpoint. If no suitable security group exists, click Create Security Group to create one.

   • Zone and vSwitch: Select the zone and vSwitch for the endpoint. If no vSwitch is available, click Create vSwitch to create one.

3. Click OK. The system creates the endpoint automatically. On the endpoint details page, copy the Domain Name of Endpoint Service — you will use this domain name to access OSS.

   

Step 2: Verify the endpoint

Run a connectivity test and download a file to confirm that the PrivateLink endpoint is correctly configured and fully functional.

• Verify connectivity

  Use ping to test the endpoint domain name and confirm that DNS resolution and the network path are working correctly.

  ping -c 4 ep-bp1i****************.oss.cn-hangzhou.privatelink.aliyuncs.com

• Verify file download

  From an ECS instance in the same region, use ossutil to download a file over the PrivateLink connection and confirm that data transfer works end-to-end.

  1. Install and configure ossutil 2.0.

  2. Use the endpoint domain name (for example, ep-bp1i****************.oss.cn-hangzhou.privatelink.aliyuncs.com) to access OSS. The following example downloads a file named dest.jpg from a bucket named example-bucket:

     ossutil cp oss://example-bucket/dest.jpg /tmp/ -e ep-bp1i****************.oss.cn-hangzhou.privatelink.aliyuncs.com --addressing-style path

     A successful download produces output similar to the following. The file is saved to the /tmp directory.

     Success: Total 1 object, size 134102 B, Download done:(1 files, 134102 B), avg 680.112 KiB/s
     
         0.193189(s) elapsed

Step 1: Set up the SSL-VPN gateway and client

Deploy an SSL-VPN gateway and complete the client configuration to establish an encrypted connection between your local device and the VPC. For detailed steps, see Connect a client to a VPC.

Step 2: Verify PrivateLink access to OSS

Run a connectivity test and download a file to confirm that the PrivateLink connection is working correctly from the local device.

• Verify connectivity

  Use ping to test the endpoint domain name and confirm that DNS resolution and the network path are working correctly.

  ping -c 4 ep-bp1i****************.oss.cn-hangzhou.privatelink.aliyuncs.com

• Verify file download

  ossutil

  Use ossutil to perform an actual file operation and verify that data transfer through PrivateLink is fully functional.

  1. Install and configure ossutil 2.0.

  2. Use the endpoint domain name (for example, ep-bp1i****************.oss.cn-hangzhou.privatelink.aliyuncs.com) to access OSS. The following example downloads dest.jpg from example-bucket:

     ossutil cp oss://example-bucket/dest.jpg /tmp/ -e ep-bp1i****************.oss.cn-hangzhou.privatelink.aliyuncs.com --addressing-style path

     A successful download produces output similar to the following. The file is saved to the /tmp directory.

     Success: Total 1 object, size 134102 B, Download done:(1 files, 134102 B), avg 680.112 KiB/s
     
         0.193189(s) elapsed

  SDK

  SDK-based access better represents real production environments and supports complex business logic and exception handling. The following SDKs support accessing OSS through PrivateLink.

  Java

  When accessing OSS through PrivateLink, call setSLDEnabled(true) to enable path-style access. For standard internet access, set it to setSLDEnabled(false).

  import com.aliyun.oss.*;
      import com.aliyun.oss.common.auth.*;
      import com.aliyun.oss.common.comm.SignVersion;
      import com.aliyun.oss.model.GetObjectRequest;
      import java.io.File;
  
      /**
       * OSS PrivateLink access example
       * Demonstrates how to access OSS via PrivateLink and download a file
       */
      public class Test {
  
          public static void main(String[] args) throws Exception {
              // PrivateLink endpoint domain name
              String endpoint = "https://ep-bp1i****************.oss.cn-hangzhou.privatelink.aliyuncs.com";
  
              // Region corresponding to the endpoint, for example cn-hangzhou
              String region = "cn-hangzhou";
  
              // Obtain credentials from environment variables
              // Make sure OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET are set before running this example
              EnvironmentVariableCredentialsProvider credentialsProvider =
                      CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
  
              // Bucket name, for example example-bucket
              String bucketName = "example-bucket";
  
              // Full object path, excluding the bucket name
              String objectName = "dest.jpg";
  
              // Local file path to save the downloaded file
              String pathName = "dest.jpg";
  
              // Configure client parameters
              ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
  
              // Enable path-style access for PrivateLink (set to false for internet access via bucket domain)
              clientBuilderConfiguration.setSLDEnabled(true);
  
              // Use Signature Version 4
              clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
  
              // Create the OSS client
              OSS ossClient = OSSClientBuilder.create()
                      .endpoint(endpoint)
                      .credentialsProvider(credentialsProvider)
                      .clientConfiguration(clientBuilderConfiguration)
                      .region(region)
                      .build();
  
              try {
                  // Download the object to a local file
                  // Overwrites the file if it exists; creates it if it does not
                  // If no path is specified, the file is saved in the project directory
                  ossClient.getObject(new GetObjectRequest(bucketName, objectName), new File(pathName));
  
              } catch (OSSException oe) {
                  // The request reached OSS but was rejected
                  System.out.println("Caught an OSSException: the request reached OSS but was rejected.");
                  System.out.println("Error message: " + oe.getErrorMessage());
                  System.out.println("Error code: " + oe.getErrorCode());
                  System.out.println("Request ID: " + oe.getRequestId());
                  System.out.println("Host ID: " + oe.getHostId());
  
              } catch (ClientException ce) {
                  // The client could not communicate with OSS
                  System.out.println("Caught a ClientException: the client encountered a serious internal problem, " +
                          "such as a network failure.");
                  System.out.println("Error message: " + ce.getMessage());
  
              } finally {
                  // Release resources
                  if (ossClient != null) {
                      ossClient.shutdown();
                  }
              }
          }
      }

  Python

  When accessing OSS through PrivateLink, set is_path_style=True to enable path-style access.

  # -*- coding: utf-8 -*-
      """
      OSS PrivateLink access example
      Downloads a file from OSS through a PrivateLink private network connection
      """
  
      import oss2
      from oss2.credentials import EnvironmentVariableCredentialsProvider
  
      def main():
          """Download a file from OSS via PrivateLink."""
  
          # Configure credentials
          # Note: The Alibaba Cloud account AccessKey has full API access and carries high risk.
          # Use a RAM user for API access and routine operations. Create RAM users in the RAM console.
          auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
  
          # PrivateLink endpoint domain name
          endpoint = 'https://ep-bp1i****************.oss.cn-hangzhou.privatelink.aliyuncs.com'
  
          # Bucket name
          bucket_name = 'example-bucket'
  
          # Create a Bucket object
          # is_path_style=True enables path-style access, required for PrivateLink and similar scenarios
          bucket = oss2.Bucket(auth, endpoint, bucket_name, is_path_style=True)
  
          # Object path in OSS (excluding the bucket name)
          object_name = 'dest.jpg'
  
          # Local file path to save the downloaded file
          local_file_path = 'dest.jpg'
  
          # Download the object to a local file
          # Overwrites the file if it exists; creates it if it does not
          bucket.get_object_to_file(object_name, local_file_path)
  
          print(f"File downloaded successfully: {object_name} -> {local_file_path}")
  
      if __name__ == '__main__':
          main()

  Go

  When accessing OSS through PrivateLink, use ForcePathStyle(true) to enable path-style access.

  package main
  
      import (
      	"fmt"
      	"os"
  
      	"github.com/aliyun/aliyun-oss-go-sdk/oss"
      )
  
      const (
      	// PrivateLink endpoint domain name
      	endpoint = "https://ep-bp1i****************.oss.cn-hangzhou.privatelink.aliyuncs.com"
  
      	// Bucket name
      	bucketName = "example-bucket"
  
      	// Object path in OSS (excluding the bucket name)
      	objectName = "dest.jpg"
  
      	// Local file path to save the downloaded file
      	localFilePath = "dest.jpg"
      )
  
      func main() {
      	// Initialize the credentials provider
      	// Reads credentials from environment variables
      	// Make sure OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET are set before running this example
      	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
      	if err != nil {
      		fmt.Printf("Failed to initialize credentials provider: %v\n", err)
      		os.Exit(-1)
      	}
  
      	// Create the OSS client
      	// oss.ForcePathStyle(true) enables path-style access, required for PrivateLink and similar scenarios
      	client, err := oss.New(
      		endpoint,
      		"", // AccessKeyId is provided by the credentials provider
      		"", // AccessKeySecret is provided by the credentials provider
      		oss.SetCredentialsProvider(&provider),
      		oss.ForcePathStyle(true),
      	)
      	if err != nil {
      		fmt.Printf("Failed to create OSS client: %v\n", err)
      		os.Exit(-1)
      	}
  
      	// Get the bucket
      	bucket, err := client.Bucket(bucketName)
      	if err != nil {
      		fmt.Printf("Failed to get bucket: %v\n", err)
      		os.Exit(-1)
      	}
  
      	// Download the object to a local file
      	// Overwrites the file if it exists; creates it if it does not
      	// If no path is specified, the file is saved in the project directory
      	err = bucket.GetObjectToFile(objectName, localFilePath)
      	if err != nil {
      		fmt.Printf("Failed to download file: %v\n", err)
      		os.Exit(-1)
      	}
  
      	fmt.Printf("File downloaded successfully: %s -> %s\n", objectName, localFilePath)
      }
      

  C++

  When accessing OSS through PrivateLink, set conf.isPathStyle = true to enable path-style access.

  #include <alibabacloud/oss/OssClient.h>
      #include <memory>
      #include <fstream>
      #include <iostream>
  
      using namespace AlibabaCloud::OSS;
  
      int main(void)
      {
          // PrivateLink endpoint domain name
          std::string Endpoint = "https://ep-bp1i****************.oss.cn-hangzhou.privatelink.aliyuncs.com";
  
          // Bucket name
          std::string BucketName = "example-bucket";
  
          // Object path in OSS (excluding the bucket name)
          std::string ObjectName = "dest.jpg";
  
          // Local file path to save the downloaded file
          // Overwrites the file if it exists; creates it if it does not
          // If no path is specified, the file is saved in the project directory
          std::string FileNametoSave = "dest.jpg";
  
          // Initialize OSS SDK resources
          InitializeSdk();
  
          // Configure client parameters
          ClientConfiguration conf;
  
          // Obtain credentials from environment variables
          // Make sure OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET are set before running this example
          auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
  
          // Enable path-style access for PrivateLink and similar scenarios
          conf.isPathStyle = true;
  
          // Create the OSS client
          OssClient client(Endpoint, credentialsProvider, conf);
  
          // Build the download request
          GetObjectRequest request(BucketName, ObjectName);
  
          // Set the response stream factory to write to a local file
          request.setResponseStreamFactory([=]() {
              return std::make_shared<std::fstream>(
                  FileNametoSave,
                  std::ios_base::out | std::ios_base::in | std::ios_base::trunc | std::ios_base::binary
              );
          });
  
          // Execute the download
          auto outcome = client.GetObject(request);
  
          // Handle the result
          if (outcome.isSuccess()) {
              std::cout << "File downloaded successfully. Size: "
                        << outcome.result().Metadata().ContentLength()
                        << " bytes" << std::endl;
              std::cout << "Saved to: " << FileNametoSave << std::endl;
          }
          else {
              // Error handling
              std::cout << "Download failed" << std::endl
                        << "Error code: " << outcome.error().Code() << std::endl
                        << "Error message: " << outcome.error().Message() << std::endl
                        << "Request ID: " << outcome.error().RequestId() << std::endl;
  
              // Release resources and return an error code
              ShutdownSdk();
              return -1;
          }
  
          // Release OSS SDK resources
          ShutdownSdk();
          return 0;
      }