Access OSS by using PrivateLink - Object Storage Service

PrivateLink is used to establish private, stable, and secure connections between virtual private clouds (VPCs) and other Alibaba Cloud services. PrivateLink simplifies network architectures and prevents risks that may arise from accessing services over the Internet. This topic describes how to use PrivateLink to access Object Storage Service (OSS) resources.

Prerequisites

Your ticket to apply for PrivateLink-based access to OSS is approved. Note: This feature is in invitational preview.
The OSS resources that you want to access by using PrivateLink reside in the China (Hangzhou), China (Shanghai), China (Beijing), China (Ulanqab), China (Shenzhen), China (Hong Kong), Singapore, or Indonesia (Jakarta) region.
A VPC and vSwitch are created in the region in which you want to create the PrivateLink endpoint. For more information, see Create a VPC and a vSwitch.
An Elastic Compute Service (ECS) instance is created in the VPC. For more information, see Create an instance.

Billing rules

You are not charged when you activate PrivateLink. After you activate PrivateLink, you are charged on a pay-as-you-go basis. Bills are generated on an hourly basis. You are charged instance fees and data transfer fees. For more information, see Billing.
The service consumer and service provider can use different Alibaba Cloud accounts. You can specify whether the service consumer or service provider to pay the bills.PrivateLink For more information, see the Payments section of the Billing topic.

Scenarios

Share OSS resources with a VPC

You can use PrivateLink to access OSS resources from a VPC in a region. In this case, you must specify OSS as the service resource of the endpoint service and create an endpoint in the VPC. The following figure shows the process.

Share OSS resources with a local data center

You can use PrivateLink to allow a local data center to access OSS resources. In this case, you must specify OSS as the service resource of the endpoint service, create an endpoint in a VPC to connect the VPC to OSS in a region, and then use a leased line, VPN Gateway, or Smart Access Gateway (SAG) to establish a connection between the local data center and VPC. The following figure shows the process.

Procedure

Create an endpoint.

Log on to the VPC console.
In the left-side navigation pane, click Endpoints.
In the top navigation bar, select a region in which the OSS resources that you want to access by using PrivateLink is located.
On the Interface Endpoint tab of the Endpoints page, click Create Endpoint.

On the Create Endpoint page, configure the parameters. The following table describes the parameters. Retain the default settings for other parameters.

Parameter	Description
Endpoint Name	Specify a name for the endpoint.
Endpoint Type	Select Interface Endpoint to create an interface endpoint for the service consumer to access the service provided.
Endpoints Service	Select Alibaba Cloud Service. Enter `com.aliyuncs.privatelink.cn-hangzhou.oss` in the Endpoint Service Name search box and click the search icon. Select the endpoint service. Note You can associate an endpoint with only one endpoint service.
VPC	Select the VPC for which you want to create an endpoint.
Security Groups	Select the security group that you want to associate with the endpoint elastic network interface (ENI). A security group allows you to manage communication to and from the endpoint ENI.
Zone and vSwitch	Select the zone of the endpoint service and select a vSwitch in the zone. The system automatically creates an endpoint ENI in the vSwitch.

Click OK.
Record the generated PrivateLink endpoint for subsequent access to OSS.

Use the PrivateLink endpoint to access OSS.

Connect to the created ECS instance. For more information, see Connect to an instance.

Specify the PrivateLink endpoint when you use ossutil or OSS SDKs to access OSS.

ossutil

Install ossutil 1.7.17 or later on the ECS instance.
For more information, see Install ossutil.
Specify the PrivateLink endpoint in an ossutil command to access OSS.
Run the following sample command to download the examplefile.txt object from the examplebucket bucket to the local /tmp/ folder: In the sample command, the -e option specifies the PrivateLink endpoint and the --force-path-style option specifies path-style access to OSS.
```
ossutil cp oss://examplebucket/examplefile.txt /tmp/ -e ep-bp1i317e3d65873e****.oss.cn-hangzhou.privatelink.aliyuncs.com --force-path-style
```
ossutil supports PrivateLink endpoints for access to OSS. For a list of common ossutil commands, see Common commands.
The following output is a sample response to the preceding command:
```
Succeed: Total num: 1, size: 11. OK num: 1(download 1 objects).

average speed 0(byte/s)

0.188959(s) elapsed
```

SDK

Only OSS SDKs for the following programming languages support PrivateLink endpoints for access to OSS. The following sample code provides an example on how to download the exampleobject.txt object from the examplebucket bucket to a local path by using a PrivateLink endpoint.

For more information about the OSS SDKs that support PrivateLink endpoint-based access to OSS, see Overview.

Build a Java, Python, Go, or C++ environment on the ECS instance.

Download the object by specifying the PrivateLink endpoint in the code of one of the following OSS SDKs.

Java

import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.model.GetObjectRequest;
import java.io.File;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Specify the PrivateLink endpoint. 
        String endpoint = "https://ep-bp1i317e3d65873e****.oss.cn-hangzhou.privatelink.aliyuncs.com";
        // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the name of the bucket. Example: examplebucket. 
        String bucketName = "examplebucket";
        // Specify the full path of the object. Do not include the bucket name in the full path. Example: exampleobject.txt. 
        String objectName = "exampleobject.txt";
        String pathName = "D:\\examplefile.txt";

        ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
        // Enable access based on a root domain name. 
        conf.setSLDEnabled(true);
         // Create an OSSClient instance. 
        OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider, conf);


        try {
            // Download the object as a local file in the specified path. If a file that has the same name already exists in the path, the downloaded object overwrites the file. If no file that has the same name exists in the path, the downloaded object is saved in the path. 
            // If you do not specify a local path for the downloaded object, the downloaded object is saved to the path of the project to which the sample program belongs. 
            ossClient.getObject(new GetObjectRequest(bucketName, objectName), new File(pathName));
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            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) {
            System.out.println("Caught an 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 {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Python

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Specify the PrivateLink endpoint. 
# Specify the name of the bucket. Example: examplebucket. 
# Set is_path_style to True to enable access based on a root domain. 
bucket = oss2.Bucket(auth, 'https://ep-bp1i317e3d65873e****.oss.cn-hangzhou.privatelink.aliyuncs.com', 'examplebucket', is_path_style=True)

# Specify the full path of the object. Do not include the bucket name in the full path. Example: exampleobject.txt. 
# Download the object as a local file in the specified path. Example: D:\\examplefile.txt. If a file that has the same name already exists in the path, the downloaded object overwrites the file. If no file that has the same name exists in the path, the downloaded object is saved in the path. 
bucket.get_object_to_file('exampleobject.txt', 'D:\\examplefile.txt')

Go

package main

import (
	"fmt"
	"os"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	// Create an OSSClient instance. 
	// Specify the PrivateLink endpoint. 
	// Set oss.ForcePathStyle to true to enable access based on a root domain. 
	client, err := oss.New("https://ep-bp1i317e3d65873e****.oss.cn-hangzhou.privatelink.aliyuncs.com", "", "", oss.SetCredentialsProvider(&provider),oss.ForcePathStyle(true))
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	// Specify the name of the bucket. Example: examplebucket. 
	bucket, err := client.Bucket("examplebucket")
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	// Download the object as a local file in the specified local path. If a file that has the same name already exists in the path, the downloaded object overwrites the file. If no file that has the same name exists in the path, the downloaded object is saved in the path. 
	// If you do not specify a local path for the downloaded object, the downloaded object is saved to the path of the project to which the sample program belongs. 
	// Specify the full path of the object and the local file. In this example, the full path of the object is exampleobject.txt and the full path of the local file is D:\\examplefile.txt. Do not include the bucket name in the full path. 
	err = bucket.GetObjectToFile("exampleobject.txt", "D:\\examplefile.txt")
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
}

C++

#include <alibabacloud/oss/OssClient.h>
#include <memory>
#include <fstream>
using namespace AlibabaCloud::OSS;

int main(void)
{
    /* Initialize information about the account that is used to access OSS. */
            
    /* Specify the PrivateLink endpoint. */
    std::string Endpoint = "https://ep-bp1i317e3d65873e****.oss.cn-hangzhou.privatelink.aliyuncs.com";
    /* Specify the name of the bucket. Example: examplebucket. */
    std::string BucketName = "examplebucket";
    /* Specify the full path of the object. Do not include the bucket name in the full path. Example: exampleobject.txt. */
    std::string ObjectName = "exampleobject.txt";
    /* Download the object as a local file named examplefile.txt in the specified path. If a file that has the same name already exists in the path, the downloaded object overwrites the file. If no file that has the same name exists in the path, the downloaded object is saved in the path. */
    /* If you do not specify a local path for the downloaded object, the downloaded object is saved to the path of the project to which the sample program belongs. */
    std::string FileNametoSave = "D:\\examplefile.txt";

    /* Initialize resources, such as network resources. */
    InitializeSdk();

    ClientConfiguration conf;	
    /* Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. */    
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    /* Set conf.isPathStyle to true to enable access based on a second-level domain. */
    conf.isPathStyle = true
    OssClient client(Endpoint, credentialsProvider, conf);

    /* Download the object as a local file. */
    GetObjectRequest request(BucketName, ObjectName);
    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); });

    auto outcome = client.GetObject(request);

    if (outcome.isSuccess()) {    
        std::cout << "GetObjectToFile success" << outcome.result().Metadata().ContentLength() << std::endl;
    }
    else {
        /* Handle exceptions. */
        std::cout << "GetObjectToFile fail" <<
        ",code:" << outcome.error().Code() <<
        ",message:" << outcome.error().Message() <<
        ",requestId:" << outcome.error().RequestId() << std::endl;
        return -1;
    }

    /* Release resources, such as network resources. */
    ShutdownSdk();
    return 0;
}