Object Storage Service:Access OSS over PrivateLink

Step 1: Create an endpoint

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

2. Configure the following parameters. Keep the default values for any unlisted parameters.

   • Region: Select the region of the target OSS bucket, 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. In the service list, select the OSS endpoint service. The service name ends with oss.

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

   • Security Group: Select a security group to attach to the endpoint. The security group controls access permissions. If no suitable security group is available, click Create Security Group.

   • Zone And VSwitch: Select the zone where the endpoint will be deployed and the corresponding vSwitch. If no vSwitch is available, click Create VSwitch.

3. Click OK. The system automatically creates the endpoint. After the endpoint is created, go to its details page to view and copy the Endpoint Domain Name. You will use this domain name for subsequent access to OSS.

   

Step 2: Verify the endpoint domain name

You can verify the endpoint configuration by testing network connectivity and downloading a file from OSS. This ensures that the PrivateLink connection is working correctly.

• Verify network connectivity

  You can use the ping command to test the network connectivity of the endpoint domain name. This verifies that DNS resolution and the network path are working.

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

• Verify file download

  You can use the ossutil tool on an ECS instance in the same region to download a file from OSS. This verifies that data can be transferred through the connection.

  1. Install and configure ossutil 2.0.

  2. Use the endpoint domain name, such as ep-bp1i****************.oss.cn-hangzhou.privatelink.aliyuncs.com, to access OSS resources. The following example shows how to download 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 displays the following output, which indicates that the download is complete. You can find 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 an SSL-VPN gateway and configure the client

To establish an encrypted connection between your on-premises device and the VPC, deploy an SSL-VPN Gateway and complete the client configuration. For more information, see Access a VPC from a client over an SSL-VPN connection.

Step 2: Verify PrivateLink access to OSS

To ensure the private access path is working correctly, verify the PrivateLink connection by testing connectivity and downloading a file.

• Verify connectivity

  You can use the ping command to test the network connectivity of the endpoint domain name. This verifies that DNS resolution and the network path are working.

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

• Verify file download

  ossutil

  On an ECS instance in the same region, use the ossutil tool to perform a file operation in OSS. This verifies the functionality and data transfer stability of the PrivateLink connection.

  1. Install and configure ossutil 2.0.

  2. Use the endpoint domain name, such as ep-bp1i****************.oss.cn-hangzhou.privatelink.aliyuncs.com, to access OSS resources. The following example shows how to download 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 displays the following output, which indicates that the download is complete. You can find 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 more closely simulates a real production environment. This method supports complex business logic integration and exception handling. The following language SDKs support accessing OSS over PrivateLink.

  Java

  When you access OSS over PrivateLink, use setSLDEnabled(true) to enable path-style access. When you access OSS over the public internet, use 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 Demo.
   * This demo shows how to access OSS and download a file over PrivateLink.
   */
  public class Test {
  
      public static void main(String[] args) throws Exception {
          // The PrivateLink endpoint domain name.
          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 access credentials from environment variables.
          // Before you run this code, make sure 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, not including the bucket name.
          String objectName = "dest.jpg";
  
          // The name of the local file to save.
          String pathName = "dest.jpg";
  
          // Configure client parameters.
          ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
  
          // Enable path-style access for PrivateLink. Set this to false when accessing through the bucket's public endpoint.
          clientBuilderConfiguration.setSLDEnabled(true);
  
          // Explicitly declare the use of the V4 signature algorithm.
          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 and save it to the specified local path.
              // If the local file exists, it is overwritten. If it does not exist, it is created.
              // If no local path is specified, the downloaded file is saved to the project's default local path.
              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 over PrivateLink, use is_path_style=True to enable path-style access.

  # -*- coding: utf-8 -*-
  """
  OSS PrivateLink Access Demo
  Access OSS over PrivateLink and download a file to your local machine.
  """
  
  import oss2
  from oss2.credentials import EnvironmentVariableCredentialsProvider
  
  
  def main():
      """Main function: Demonstrates how to access OSS and download a file over PrivateLink."""
      
      # Configure access credentials.
      # Note: The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. This is a high-risk operation.
      # Create and use a RAM user for API access or daily O&M. Log on to the RAM console to create a RAM user.
      auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
      
      # The PrivateLink endpoint domain name.
      endpoint = 'https://ep-bp1i****************.oss.cn-hangzhou.privatelink.aliyuncs.com'
      
      # The bucket name.
      bucket_name = 'example-bucket'
      
      # Create a bucket object.
      # is_path_style=True enables path-style access, which is suitable for specific use cases such as PrivateLink.
      bucket = oss2.Bucket(auth, endpoint, bucket_name, is_path_style=True)
      
      # The OSS object path (full path without the bucket name).
      object_name = 'dest.jpg'
      
      # The local file path to save to.
      local_file_path = 'dest.jpg'
      
      # Download the object to a local file.
      # If the 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 over 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.
  	endpoint = "https://ep-bp1i****************.oss.cn-hangzhou.privatelink.aliyuncs.com"
  
  	// The bucket name.
  	bucketName = "example-bucket"
  
  	// The OSS object path (full path without the bucket name).
  	objectName = "dest.jpg"
  
  	// The local file path to save to.
  	localFilePath = "dest.jpg"
  )
  
  func main() {
  	// Initialize the credentials provider.
  	// Obtain access credentials from environment variables.
  	// Before you run this code, make sure 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 credentials provider: %v\n", err)
  		os.Exit(-1)
  	}
  
  	// Create an OSS client instance.
  	// oss.ForcePathStyle(true) enables path-style access, which is suitable for specific use cases such as PrivateLink.
  	client, err := oss.New(
  		endpoint,
  		"", // AccessKeyId is obtained through the credentials provider.
  		"", // AccessKeySecret is obtained through 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 object.
  	bucket, err := client.Bucket(bucketName)
  	if err != nil {
  		fmt.Printf("Failed to get bucket object: %v\n", err)
  		os.Exit(-1)
  	}
  
  	// Download the object to a local file.
  	// If the local file exists, it is overwritten. If it does not exist, it is created.
  	// If no local path is specified, the downloaded file is saved to the project's default local path.
  	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 you access OSS over PrivateLink, use 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 name.
      std::string Endpoint = "https://ep-bp1i****************.oss.cn-hangzhou.privatelink.aliyuncs.com";
      
      // The bucket name.
      std::string BucketName = "example-bucket";
      
      // The OSS object path (full path without the bucket name).
      std::string ObjectName = "dest.jpg";
      
      // The local file path to save to.
      // If the local file exists, it is overwritten. If it does not exist, it is created.
      // If no local path is specified, the downloaded file is saved to the project's default local path.
      std::string FileNametoSave = "dest.jpg";
  
      // Initialize OSS SDK resources, such as the network.
      InitializeSdk();
  
      // Configure client parameters.
      ClientConfiguration conf;
      
      // Obtain access credentials from environment variables.
      // Before you run this code, make sure 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 suitable for specific use cases such as PrivateLink.
      conf.isPathStyle = true;
      
      // Create an OSS client instance.
      OssClient client(Endpoint, credentialsProvider, conf);
  
      // Build the GetObject request.
      GetObjectRequest request(BucketName, ObjectName);
      
      // Set the 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
          );
      });
  
      // Run the download operation.
      auto outcome = client.GetObject(request);
  
      // Process the download result.
      if (outcome.isSuccess()) {
          std::cout << "File downloaded successfully, size: " 
                    << outcome.result().Metadata().ContentLength() 
                    << " bytes" << std::endl;
          std::cout << "File saved to: " << FileNametoSave << std::endl;
      }
      else {
          // Handle errors.
          std::cout << "File 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, such as the network.
      ShutdownSdk();
      return 0;
  }