Object Storage Service:Access OSS over a private network by using PrivateLink

Step 1: Create an 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. You can leave the other parameters at their default values.

   • Region: Select the region where the target OSS bucket is located, such as China (Hangzhou).

   • Endpoint Name: Enter a descriptive name for the endpoint, such as privatelink-oss.

   • Endpoint Type: Select Interface Endpoint.

   • Endpoint Service: Select Alibaba Cloud Service, and then select the OSS endpoint service from the service list. The service name ends with oss.

     Note

     If the OSS endpoint service does not appear in the service list, contact technical support to request activation.

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

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

   • Zone and vSwitch: Select the availability zone and corresponding vSwitch where you want to deploy the endpoint. If no vSwitches are available, click Create vSwitch to create one.

3. Click OK. The system creates the endpoint automatically. After the endpoint is created, go to the endpoint details page to view and copy the Domain Name of Endpoint Service, which you will use to access OSS.

   

Step 2: Verify the endpoint

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

• Verify network connectivity

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

  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 from OSS. This verifies the end-to-end functionality of the PrivateLink connection.

  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 resources. 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 command execution returns the following output, indicating that the file is downloaded. You can view the downloaded file in 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: Create SSL-VPN gateway and configure client

Deploy an SSL-VPN gateway and configure the client to establish an encrypted connection between your local device and the VPC. For detailed steps, see Connect a PC or Android client to a VPC by using an SSL-VPN connection.

Step 2: Verify private access to OSS

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

• Verify connectivity

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

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

• Verify file download

  ossutil

  Use ossutil to perform a file operation to verify the functionality of the PrivateLink connection.

  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 resources. 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 command execution returns the following output, indicating that the file is downloaded. You can view the downloaded file in 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

  Using an SDK is more representative of production environments because it allows for complex business logic and exception handling.

  Java

  When you access OSS through PrivateLink, call setSLDEnabled(true) to enable path-style access. For public internet access, set this parameter 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 and download a file by using PrivateLink.
   */
  public class Test {
  
      public static void main(String[] args) throws Exception {
          // The PrivateLink endpoint domain.
          String endpoint = "https://ep-bp1i****************.oss.cn-hangzhou.privatelink.aliyuncs.com";
  
          // Specify the region that corresponds to the endpoint. For example, cn-hangzhou.
          String region = "cn-hangzhou";
  
          // Obtain credentials from environment variables.
          // Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
          EnvironmentVariableCredentialsProvider credentialsProvider =
                  CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
  
          // Specify the bucket name. For example, example-bucket.
          String bucketName = "example-bucket";
  
          // Specify the full path of the object. Do not include the bucket name in the full path.
          String objectName = "dest.jpg";
  
          // Specify the local path to save the downloaded file.
          String pathName = "dest.jpg";
  
          // Configure client parameters.
          ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
  
          // Enable path-style access for PrivateLink. Set this parameter to false for public internet access through the bucket's public domain name.
          clientBuilderConfiguration.setSLDEnabled(true);
  
          // Explicitly use Signature Version 4.
          clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
  
          // Create an OSS client instance.
          OSS ossClient = OSSClientBuilder.create()
                  .endpoint(endpoint)
                  .credentialsProvider(credentialsProvider)
                  .clientConfiguration(clientBuilderConfiguration)
                  .region(region)
                  .build();
  
          try {
              // Download the object to a local file.
              // If the specified local file exists, it is overwritten. If it does not exist, it is created.
              // If you do not specify a local path, the file is downloaded to the project's root directory.
              ossClient.getObject(new GetObjectRequest(bucketName, objectName), new File(pathName));
  
          } catch (OSSException oe) {
              // Handle OSS server-side exceptions.
              System.out.println("Caught an OSSException, which means your request made it to the OSS server, but was rejected with an error response.");
              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) {
              // Handle client-side exceptions.
              System.out.println("Caught a ClientException, which means the client encountered a serious internal problem while trying to communicate with OSS, " +
                      "such as not being able to access the network.");
              System.out.println("Error Message: " + ce.getMessage());
  
          } finally {
              // Release resources.
              if (ossClient != null) {
                  ossClient.shutdown();
              }
          }
      }
  }

  Python

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

  # -*- coding: utf-8 -*-
  """
  OSS PrivateLink access example
  This sample shows how to access OSS and download a file to a local path over a PrivateLink connection.
  """
  
  import oss2
  from oss2.credentials import EnvironmentVariableCredentialsProvider
  
  
  def main():
      """Main function: Demonstrates how to access OSS and download a file by using PrivateLink."""
      
      # Configure credentials.
      # An Alibaba Cloud account AccessKey pair has full permissions on all API operations. Using these credentials poses a high security risk.
      # We strongly recommend that you create and use a RAM user to call API operations or perform routine O&M.
      auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
      
      # The PrivateLink endpoint domain.
      endpoint = 'https://ep-bp1i****************.oss.cn-hangzhou.privatelink.aliyuncs.com'
      
      # The bucket name.
      bucket_name = 'example-bucket'
      
      # Create a Bucket object.
      # Set is_path_style=True to enable path-style access, which is required for scenarios like PrivateLink.
      bucket = oss2.Bucket(auth, endpoint, bucket_name, is_path_style=True)
      
      # The path of the OSS object. Do not include the bucket name in the path.
      object_name = 'dest.jpg'
      
      # The local path to save the downloaded file.
      local_file_path = 'dest.jpg'
      
      # Download the object to a local file.
      # If the specified local file exists, it is overwritten. If it does not exist, it is created.
      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 you access 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 (
  	// The PrivateLink endpoint domain.
  	endpoint = "https://ep-bp1i****************.oss.cn-hangzhou.privatelink.aliyuncs.com"
  
  	// The bucket name.
  	bucketName = "example-bucket"
  
  	// The path of the OSS object. Do not include the bucket name in the path.
  	objectName = "dest.jpg"
  
  	// The local path to save the downloaded file.
  	localFilePath = "dest.jpg"
  )
  
  func main() {
  	// Initialize the credentials provider.
  	// Obtain credentials from environment variables.
  	// Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
  	if err != nil {
  		fmt.Printf("Failed to initialize the credentials provider: %v\n", err)
  		os.Exit(-1)
  	}
  
  	// Create an OSS client instance.
  	// Use oss.ForcePathStyle(true) to enable path-style access, which is required for scenarios like PrivateLink.
  	client, err := oss.New(
  		endpoint,
  		"", // The AccessKey ID is obtained from the provider and can be left empty here.
  		"", // The AccessKey secret is obtained from the provider and can be left empty here.
  		oss.SetCredentialsProvider(&provider),
  		oss.ForcePathStyle(true),
  	)
  	if err != nil {
  		fmt.Printf("Failed to create the OSS client: %v\n", err)
  		os.Exit(-1)
  	}
  
  	// Obtain the bucket object.
  	bucket, err := client.Bucket(bucketName)
  	if err != nil {
  		fmt.Printf("Failed to obtain the bucket object: %v\n", err)
  		os.Exit(-1)
  	}
  
  	// Download the object to a local file.
  	// If the specified local file exists, it is overwritten. If it does not exist, it is created.
  	// If you do not specify a local path, the file is downloaded to the project's root directory.
  	err = bucket.GetObjectToFile(objectName, localFilePath)
  	if err != nil {
  		fmt.Printf("Failed to download the file: %v\n", err)
  		os.Exit(-1)
  	}
  
  	fmt.Printf("File downloaded successfully: %s -> %s\n", objectName, localFilePath)
  }
  

  C++

  When you access 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)
  {
      // The PrivateLink endpoint domain.
      std::string Endpoint = "https://ep-bp1i****************.oss.cn-hangzhou.privatelink.aliyuncs.com";
      
      // The bucket name.
      std::string BucketName = "example-bucket";
      
      // The path of the OSS object. Do not include the bucket name in the path.
      std::string ObjectName = "dest.jpg";
      
      // The local path to save the downloaded file.
      // If the specified local file exists, it is overwritten. If it does not exist, it is created.
      // If you do not specify a local path, the file is downloaded to the project's root directory.
      std::string FileNametoSave = "dest.jpg";
  
      // Initialize OSS SDK resources.
      InitializeSdk();
  
      // Configure client parameters.
      ClientConfiguration conf;
      
      // Obtain credentials from environment variables.
      // Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
      auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
      
      // Enable path-style access, which is required for scenarios like PrivateLink.
      conf.isPathStyle = true;
      
      // Create an OSS client instance.
      OssClient client(Endpoint, credentialsProvider, conf);
  
      // Build a request to download the object.
      GetObjectRequest request(BucketName, ObjectName);
      
      // Set a response stream factory to create a local file stream.
      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 operation.
      auto outcome = client.GetObject(request);
  
      // Handle the download 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 {
          // Handle errors.
          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;
  }