Cross-project resource access based on packages - MaxCompute

In cross-project or cross-account resource access scenarios, if an account is not added to a project, the account cannot access the resources or objects in the project. MaxCompute provides a package-based access control mechanism. This mechanism allows you to package resources in a project and the permissions on the resources and authorize the owner of another project to install the package. This way, users or roles can access resources across projects. This topic describes the package-based access control mechanism and provides examples on how to implement the package-based access control mechanism.

Background information

In this topic, an Alibaba Cloud account owns multiple MaxCompute projects and needs to share specific tables, resource files, and user-defined functions (UDFs) in Project A with the other projects of this account or other projects within another Alibaba Cloud account. You can share the resources with other projects by using one of the following methods:

Add the users in the other projects to Project A and grant each user the permissions to access the resources. This method is complex. We recommend that you do not use this method in cross-project resource access scenarios. We recommend that you use this method only when fine-grained resource access control is required for a member of your project team. For more information about the syntax for authorization commands, see ACL-based access control.
Use the package-based access control mechanism.
The package-based access control mechanism is used to share data and resources across projects. The owner of Project A packages the resources that other projects need to use and the operation permissions on the resources and authorizes the owners of other projects to install the package. After the package is installed, the owners of the other projects can determine whether to authorize users in their projects to access the resources in the package. The following figure shows how the package-based access control mechanism is implemented.

The preceding figure shows that the package-based access control mechanism involves two entities: package creator and package user. The following table describes the information about the entities and the operations that the entities can perform.

Entity	Description	Executable operation	Entity role	Operation platform
Package creator	The project to which a package creator belongs provides resources to share. The package creator packages the project resources that need to share and the operation permissions on the resources and authorizes package users to install the package and access the resources in the package.	Create a package	The owner of the project to which the resources belong or a user that is assigned the project-level role Super_Administrator of the project to which the resources belong	MaxCompute client MaxCompute Studio DataWorks console
		Add resources to a package
		Remove resources from a package
		Authorize a package to use a package
		Revoke access permissions on a package from a project
		Delete a package
		View packages
		View the details of a package
Package user	The project to which a package user belongs accesses resources in a package. After a package user installs the package that is created by a package creator, the package user can directly access the resources in the package.	Install a package	The owner of the project that uses the resources or a user that is assigned the project-level role Super_Administrator or Admin of the project that uses the resources
		View the details of an installed package
		Authorize a user or role to access a package
		Uninstall a package

Limits

Before you use the package-based access control mechanism, take note of the following limits:

A maximum of 1,000 resources can be added to a package.
A package can be installed for a maximum of 100,000 MaxCompute projects.
A maximum of 100 packages in a MaxCompute project can be installed for another MaxCompute project.
A maximum of 100,000 packages can be created for a MaxCompute project.
A maximum of 100,000 packages can be installed for a MaxCompute project.

Create a package

A package creator creates a package in a MaxCompute project.

Syntax
```
create package <package_name>;
```

Parameters

Parameter

Required

Description

package_name

Yes

The name of the package, which is unique within a project. The name must be 1 to 128 characters in length, and can contain letters, digits, and underscores (_).

You can run the show packages; command on the MaxCompute client to obtain the information about the package that you created.

Examples
In this example, the Alibaba Cloud account Bob@aliyun.com is the owner of the test_project_a project and needs to authorize other projects to access specific resources in the test_project_a project. Create a package. Sample commands:
```
Go to the test_project_a project by using the Alibaba Cloud account Bob@aliyun.com. 
use test_project_a; 
-- Create a package. 
create package datashare;
```

Add resources to a package

A package creator adds the resources that are required by package users to the package that is created.

Syntax

add <object_type> <object_name> to package <package_name> [with privileges <privileges>];

Limits
You cannot add projects to a package.
Precautions
When you add resources to a package, the resources are not packaged as snapshots. If resource data is updated after the resources are added to a package, package users access the latest resource data.

Parameters

Parameter	Required	Description
object_type	Yes	The type of the object that you want to add to the package. You can specify only one object type at a time. For more information about object types, see Permissions.
object_name	Yes	The name of the object that you want to remove from the package. You can obtain the object name by using one of the following methods: Table or view name: You can run the `show tables;` command on the MaxCompute client to obtain the table or view name. Resource file name: You can run the `list resources;` command on the MaxCompute client to obtain the resource file name. Function: You can run the `list functions;` command on the MaxCompute client to obtain the function name. Instance name: You can run the `show instances;` command on the MaxCompute client to obtain the instance name. Note When you add resources to a package, you can use an asterisk () to specify the resources that you want to add. For example, you can run the `add table to package package_name;` command to add all tables to a package. When you add resources to a package, do not specify the resource name in the Project name.Resource name format. For example, if you want to add a table named table in Project A to a package, do not specify A.table as the resource name. You must specify table as the resource name.
package_name	Yes	The name of the package. You can run the `show packages;` command on the MaxCompute client to obtain the information about the package that you created.
privileges	No	The operation permissions on resources in the package. If you do not specify this parameter, the Read, Describe, and Select permissions on the resources are added to the package by default. The resources and operation permissions on the resources are inseparable and cannot be updated after you add them to a package. If you want to update the resources or operation permissions on these resources in a package, you must delete the resources in the package and then add the updated resources and operation permissions on the resources to a package again. For more information about operation permissions, see Permissions.

Examples
Add the resource file udtf.jar and the tables sale_detail and bank_data of the test_project_a project to the package that you created. Sample commands:
```
-- Add resources to the package that you created. 
add Resource udtf.jar to package datashare;
add Table sale_detail to package datashare;
```

Remove resources from a package

A package creator removes resources from the package that is created.

Syntax

remove <object_type> <object_name> from package <package_name>;

Parameters

Parameter	Required	Description
object_type	Yes	The type of the object that you want to remove from the package. You can remove only one object at a time. For more information about object types, see Permissions.
object_name	Yes	The name of the object that you want to remove from the package. You can obtain the object name by using one of the following methods: Table or view name: You can run the `show tables;` command on the MaxCompute client to obtain the table or view name. Resource file name: You can run the `list resources;` command on the MaxCompute client to obtain the resource file name. Function: You can run the `list functions;` command on the MaxCompute client to obtain the function name. Instance name: You can run the `show instances;` command on the MaxCompute client to obtain the instance name.
package_name	Yes	The name of the package. You can run the `show packages;` command on the MaxCompute client to obtain the information about the package that you created.

Examples

Remove the sale_detail table from the datashare package. Sample command:

-- Remove the sale_detail table from the datashare package. 
remove Table sale_detail from package datashare;

Authorize a project to use a package

A package creator in a project authorizes other projects to use the package that is created.

Syntax

allow project <project_name> to install package <package_name> [using label <number>];

Parameters

Parameter	Required	Description
project_name	Yes	The name of the MaxCompute project that you want to authorize to use the package. To view the name of a MaxCompute project, log on to the MaxCompute console. In the top navigation bar, select a region. Then, view the name of the MaxCompute project on the Project management tab.
package_name	Yes	The name of the package. You can run the `show packages;` command on the MaxCompute client to obtain the information about the package that you created.
number	No	This parameter is used to add a label-based access control policy. This parameter specifies the sensitivity level of data that a package user can access. The authorized MaxCompute project can access only the package data whose sensitivity level is lower than or equal to the level specified by number. If you do not specify this parameter, the sensitivity level is 0 by default. For more information about label-based access control, see Label-based access control.

Examples

Authorize test_project_b to install the datashare package that is created in the test_project_a project. Sample command:

-- Authorize the test_project_b project to install the datashare package. 
allow project test_project_b to install package datashare;

Revoke access permissions on a package from a project

A package creator revokes access permissions on a package from a project.

Syntax

disallow project <project_name> to install package <package_name>;

Parameters

Parameter

Required

Description

project_name

Yes

The name of the MaxCompute project from which you want to revoke access permissions on the package.

To view the name of a MaxCompute project, log on to the MaxCompute console. In the top navigation bar, select a region. Then, view the name of the MaxCompute project on the Project management tab.

package_name

Yes

The name of the package.

You can run the show packages; command on the MaxCompute client to obtain the information about the package that you created.

Examples

Revoke permissions to install the datashare package of the test_project_a project from the test_project_b project. Sample command:

-- Revoke permissions to install the datashare package from the test_project_b project. 
disallow project test_project_b to install package datashare;

Delete a package

A package creator deletes a package.

Syntax
```
delete|drop package <package_name>;
```
Precautions
If you delete a package, the information about the permissions that are granted by using this package is cleared.

Parameters

Parameter

Required

Description

package_name

Yes

The name of the package that you want to delete.

You can run the show packages; command on the MaxCompute client to obtain the information about the package that you created.

Examples
Delete the datashare package that is created in the test_project_a project. Sample command:
```
-- Delete the datashare package. 
drop package datashare;
```

View packages

A package creator views the packages that are created or installed in a MaxCompute project.

Syntax
```
show packages;
```

Examples

View the information about the packages that are created or installed in the test_project_a project. Sample command:

-- View packages. 
show packages;

The returned result contains the following information:

PackageName: the name of the package that is created or installed.
CreateTime: the time when the package is created.
SourceProject: the name of the MaxCompute project to which the package belongs.
InstallTime: the time when the package is installed.
Status: the status of the package.

+-------------+--------------------------+
| PackageName | CreateTime               |
+-------------+--------------------------+
| datashare   | 2021-12-28T18:10:39+0800 |
+-------------+--------------------------+
+-------------+--------------------+--------------------------+--------+
| PackageName | SourceProject      | InstallTime              | Status |
+-------------+--------------------+--------------------------+--------+
| systables   | information_schema | 2020-11-24T14:11:23+0800 | OK     |
+-------------+--------------------+--------------------------+--------+

View the details of a package

A package creator views the details of a package that is created in a MaxCompute project.

Syntax
```
describe package <package_name>;
```
Parameters
Parameter
Required
Description
package_name
Yes
The name of the package.
You can run the show packages; command on the MaxCompute client to obtain the information about the package that you created.

Examples

View the resources and permissions that are included in the datashare package in the test_project_a project. Sample command:

-- View the details of the datashare package. 
describe package datashare;

The returned result contains the following information:

CreateTime: the time when the package is created.
PackageName: the name of the package.
SourceProject: the name of the MaxCompute project to which the package belongs.
ObjectType: the type of an object in the package.
ObjectName: the name of an object in the package.
ObjectPrivileges: the permissions on an object in the package.
ProjectName: the project that is authorized to install the package.
UserLabel: the user label.

CreateTime:         2021-12-28T18:10:39+0800
PackageName:        datashare
SourceProject:      test_project_a

Object List
+--------------+------------------------------------------+------------------+
| ObjectType   | ObjectName                               | ObjectPrivileges |
+--------------+------------------------------------------+------------------+
| RESOURCE     | udtf.jar                                 | Read             |
+--------------+------------------------------------------+------------------+
| TABLE        | sale_detail                              | Describe,Select  |
+--------------+------------------------------------------+------------------+

Allowed Project List
+-----------------+-----------+
| ProjectName     | UserLabel |
+-----------------+-----------+
| test_project_b  | 0         |
+-----------------+-----------+

Install a package

A package user installs a package in a MaxCompute project.

Syntax

install package <project_name>.<package_name>;

Precautions
After you install packages, you can run the show packages; command to view the packages that are installed, and run the describe package <package_name>; command to view the resources and permissions in a package.

Parameters

Parameter

Required

Description

project_name

Yes

The name of the MaxCompute project to which the package belongs.

package_name

Yes

The name of the package.

You can run the show packages; command on the MaxCompute client to obtain the information about the package that you created.

Examples
Install the datashare package of the test_project_a project in the test_project_b project. In this example, the Alibaba Cloud account Amy@aliyun.com is the owner of the test_project_b project. Sample command:
```
-- Go to the test_project_b project by using the Alibaba Cloud account Amy@aliyun.com. 
use test_project_b; 
-- Install the datashare package. 
install package test_project_a.datashare;
```

View the details of an installed package

A package user views the details of a package that is installed in a MaxCompute project.

Syntax

describe package <project_name>.<package_name>;

Parameters

Parameter

Required

Description

project_name

Yes

The name of the MaxCompute project to which the package belongs.

package_name

Yes

The name of the package.

You can run the show packages; command on the MaxCompute client to obtain the information about the package that you created.

Examples

View the resources and permissions in the datashare package that is installed in the test_project_b project. Sample command:

-- View the details of the datashare package. 
describe package test_project_a.datashare;

The returned result contains the following information:

CreateTime: the time when the package is created.
PackageName: the name of the package.
SourceProject: the name of the MaxCompute project to which the package belongs.
ObjectType: the type of an object in the package.
ObjectName: the name of an object in the package.
ObjectPrivileges: the permissions on an object in the package.

CreateTime:         2021-12-28T18:10:39+0800
PackageName:        datashare
SourceProject:      test_project_a

Object List
+--------------+------------------------------------------+------------------+
| ObjectType   | ObjectName                               | ObjectPrivileges |
+--------------+------------------------------------------+------------------+
| RESOURCE     | udtf.jar                                 | Read             |
+--------------+------------------------------------------+------------------+
| TABLE        | sale_detail                              | Describe,Select  |
+--------------+------------------------------------------+------------------+

Authorize a user or role to access a package

A package user authorizes a user or role to access a package in the MaxCompute project where the package is installed.

The installed package is a type of independent object in MaxCompute. If you want to access resources in a package, you must have the Read permission on the package. If you do not have the Read permission, the project owner and users that are assigned the Super_Administrator or Admin role can grant you the Read permission by using access control lists (ACLs). For more information about ACL-based access control, see ACL-based access control.

Syntax

grant <actions> on package <project_name>.<package_name> to {USER|ROLE} <name>;

Precautions
After the Read permission is granted to a user or role, the user or role can access the resources in the package only in the project where the package is installed. For more information about how to manage the permissions on packages in a fine-grained manner, see Access control for packages.

Parameters

Parameter	Required	Description
actions	Yes	The operation permissions on resources in the package. Set the value to Read.
project_name	Yes	The name of the MaxCompute project to which the package belongs. To view the name of a MaxCompute project, log on to the MaxCompute console. In the top navigation bar, select a region. Then, view the name of the MaxCompute project on the Project management tab.
package_name	Yes	The name of the package. You can run the `show packages;` command on the MaxCompute client to obtain the information about the package that you created.
name	Yes	The name of the user account or role to which you want to grant access permissions. You can specify only one user account or role for a single authorization operation. You can run the `list users;` or `list roles;` command on the MaxCompute client to obtain the name of the user account or role.

Examples
In this example, Bella is a RAM user of the Alibaba Cloud account Amy@aliyun.com. Authorize Bella to access the datashare package. Sample command:
```
-- Authorize Bella to access the datashare package. 
grant Read on package test_project_a.datashare to user RAM$Amy@aliyun.com:Bella;
```

Revoke access permissions on a package from a user or role

A package user revokes the access permissions on a package from a user or role in the MaxCompute project where the package is installed.

Syntax

revoke <actions> on package <project_name>.<package_name> from {USER|ROLE} <name>;

Parameters

Parameter	Required	Description
actions	Yes	The operation permissions on resources in the package. Set the value to Read.
project_name	Yes	The name of the MaxCompute project to which the package belongs. To view the name of a MaxCompute project, log on to the MaxCompute console. In the top navigation bar, select a region. Then, view the name of the MaxCompute project on the Project management tab.
package_name	Yes	The name of the package. You can run the `show packages;` command on the MaxCompute client to obtain the information about the package that you created.
name	Yes	The name of the user account or role from which you want to revoke the access permissions on the package. You can specify only one user account or role for a single revocation operation. You can run the `list users;` or `list roles;` command on the MaxCompute client to obtain the name of the user account or role.

Examples

Revoke the access permissions on the package from Bella. Sample command:

-- Revoke the access permissions on the package from Bella. 
revoke Read on package test_project_a.datashare from user RAM$Amy@aliyun.com:Bella;

Uninstall a package

A package user uninstalls a package that is installed in a MaxCompute project.

Syntax

uninstall package <project_name>.<package_name>;

Parameters

Parameter

Required

Description

project_name

Yes

The name of the MaxCompute project to which the package belongs.

package_name

Yes

The name of the package.

You can run the show packages; command on the MaxCompute client to obtain the information about the package that you created.

Examples
Uninstall the datashare package that is installed in the test_project_b project. Sample command:
```
-- Uninstall the datashare package. 
uninstall package test_project_a.datashare;
```

Usage example

In this example, the Alibaba Cloud account Bob@aliyun.com is the owner of the test_project_a project. The Alibaba Cloud account Amy@aliyun.com is the owner of the test_project_b project. To address business concerns, you want to share the udtf.jar resource file and the sale_detail table in the test_project_a project with the test_project_b. You also want the RAM user Amy@aliyun.com:Bella in the test_project_b project to access the resources. Perform the following steps on the MaxCompute client:

Go to the test_project_a project and create a package by using the Alibaba Cloud account Bob@aliyun.com.

Go to the test_project_a project by using the Alibaba Cloud account Bob@aliyun.com. 
use test_project_a; 
-- Create a package. 
create package datashare;

Use the Alibaba Cloud account Bob@aliyun.com to add resources to the package that is created.

-- Add resources to the package that you created. 
add Resource udtf.jar to package datashare;
add Table sale_detail to package datashare;

Use the Alibaba Cloud account Bob@aliyun.com to authorize the test_project_b project to install the package.

-- Authorize the test_project_b project to install the datashare package. 
allow project test_project_b to install package datashare;

Go to the test_project_b project and install the package by using the Alibaba Cloud account Amy@aliyun.com.

-- Go to the test_project_b project. 
use test_project_b;
-- Install the datashare package. 
install package test_project_a.datashare; 
-- View the resources of the package. 
describe package test_project_a.datashare; 
-- The following result is returned: 
CreateTime:         2021-12-28T18:10:39+0800
PackageName:        datashare
SourceProject:      test_project_a

Object List
+--------------+------------------------------------------+------------------+
| ObjectType   | ObjectName                               | ObjectPrivileges |
+--------------+------------------------------------------+------------------+
| RESOURCE     | udtf.jar                                 | Read             |
+--------------+------------------------------------------+------------------+
| TABLE        | sale_detail                              | Describe,Select  |
+--------------+------------------------------------------+------------------+

Use the Alibaba Cloud account Amy@aliyun.com to authorize Bella to access the package.

-- Authorize Bella to access the package. 
grant Read on package test_project_a.datashare to user RAM$Amy@aliyun.com:Bella;

What to do next

After you create and install a package, you can perform the following operations based on your business requirements:

References

You can use the CLONE TABLE statement to migrate data across MaxCompute projects in the same region. For more information, see Migrate data across MaxCompute projects in the same region by using CLONE TABLE.
You can migrate data across MaxCompute projects in different regions by using cross-project data access. You can use cross-project data access to migrate data across MaxCompute projects within the same Alibaba Cloud account or different Alibaba Cloud accounts. For more information, see Migrate data from MaxCompute projects in different regions by using cross-project data access.
You can use DataWorks to migrate MaxCompute data across projects. For more information, see MaxCompute data sources.