In cross-project resource access scenarios, if you are not added to a project, you cannot access the resources (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 other projects. 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.

    Implementation of the package-based access control mechanism
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 Owner of the project to which resources belong
Add resources to a package
Remove resources from a package
Authorize a project 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 Owner 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 in a maximum of 100,000 MaxCompute projects.
  • A maximum of 100 packages that are created in a MaxCompute project can be installed in another MaxCompute project.
  • A maximum of 100,000 packages can be created in a MaxCompute project.
  • A maximum of 100,000 packages can be installed in 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.

  • Usage notes

    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 add 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 add to 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 name: 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 (*) as a regular expression in the command that is used to add the resources. 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 to which you want to add resources.

    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 name: 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 from which you want to remove the resource.

    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.

    You can log on to the MaxCompute console. In the top navigation bar, select a region. On the Project management tab, obtain the name of the MaxCompute project.

    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.

    You can log on to the MaxCompute console. In the top navigation bar, select a region. On the Project management tab, obtain the name of the MaxCompute project.

    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>;
  • Usage notes

    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 whose details you want to view.

    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>;
  • Usage notes

    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.

    You can log on to the MaxCompute console. In the top navigation bar, select a region. On the Project management tab, obtain the name of the MaxCompute project.

    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 commands:

    -- Go to the test_project_b project by using the Alibaba Cloud account Amy@aliyun.com. 
    use test_project_b; 
    -- Install the 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.

    You can log on to the MaxCompute console. In the top navigation bar, select a region. On the Project management tab, obtain the name of the MaxCompute project.

    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 package details. 
    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 with 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>;
  • Usage notes

    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.

    You can log on to the MaxCompute console. In the top navigation bar, select a region. On the Project management tab, obtain the name of the MaxCompute project.

    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.

    You can log on to the MaxCompute console. In the top navigation bar, select a region. On the Project management tab, obtain the name of the MaxCompute project.

    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.

    You can log on to the MaxCompute console. In the top navigation bar, select a region. On the Project management tab, obtain the name of the MaxCompute project.

    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:
  1. 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;
  2. 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;
  3. 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;
  4. 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 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  |
    +--------------+------------------------------------------+------------------+
  5. 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: