Working with Listings

This topic describes how to work with listings in the Oracle Cloud Infrastructure Marketplace catalog. You can do the following:

  • Search for listings to find what you want to deploy
  • Filter listings to refine application results
  • View a listing to learn about the product that it offers
  • Launch an instance from an image listing
  • Launch stack resources from a stack listing
  • Download Terraform configuration files from stack listings to update deployed applications

By default, Marketplace displays all listings in its catalog. However, an individual's ability to see or launch particular listings varies by tenancy, according to what permissions the individual has, and the pricing model for the listing.

Listings are either image listings or stack listings. Image listings have a Launch Instance button. Stack listings have a Launch Stack button.

For information about pricing and how it affects whether you can see a listing, see Pricing for Listings.

Pricing for Listings

Marketplace listings belong to one of several pricing models available to and set by the publisher when the publisher creates the listing. Pricing models include:

  • Free: usage incurs no charge
  • BYOL: usage relies on software licenses that you already own
  • Paid: usage incurs charges based on hourly rates, either according to OCPU hours consumed or according to the number of instances (irrespective of OCPU hours consumed by each)

The listing price does not include any additional fees that you might incur for the use of infrastructure resources.

For a cloud account to access paid listings, it must have a United States mailing address and the form of payment provided when the account was created must support payment in United States dollars. United States-based customers can deploy most paid listings in any commercial region data center, but some paid listings can only be deployed in United States commercial regions. These listings have a region restriction label that marks them as US-only.

Customers in US Government Cloud realms can see all paid listings from Oracle and third-party publishers. Users in United Kingdom government tenancies do not have access to any paid listings.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be granted security access in a policy  by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, verify with your administrator what type of access you have and which compartment  to work in.

If you're new to policies, see Getting Started with Policies and Common Policies.

For administrators, the policies you need to create to provide users with access to Marketplace depend on whether the tenancy is in a commercial region, the United Kingdom Government Cloud region, or the United States Government Cloud realm.

Note

In commercial regions and the United Kingdom Government Cloud region, administrators do not need to write policies to grant users the ability to list or read listings. In these regions, you can see individual listings and lists of listings by default. Furthermore, to reduce the scope of access to a particular compartment, specify the specific compartment instead of the tenancy in the policy statement.

For a Tenancy in a Commercial Region or the United Kingdom Government Cloud

  • The following policy gives the specified example group, MarketplaceUsers, the ability to list accepted terms of use agreements. However, it does not include the ability to accept a terms of use agreement. The terms of use agreement for a given listing must be viewed and accepted prior to launch. For a policy that includes the ability to use listings, see the policy statements later in this section that grant access to the type of listing you want to launch, whether an image listing or a stack listing.

    Allow group MarketplaceUsers to inspect compartments in tenancy
    
    Allow group MarketplaceUsers to read app-catalog-listing in tenancy
  • The following policy gives the specified example group, MarketplaceUsers, the ability to not only list and read, but also use Marketplace listings. It does not include the ability to create instances using images from listings. (For that, see the next set of policy statements.)

    Allow group MarketplaceUsers to inspect compartments in tenancy
    Allow group MarketplaceUsers to manage app-catalog-listing in tenancy
    
  • The following policy gives the specified example group, MarketplaceUsers, general access to managing instances and images, along with the required level of access to attach existing block volumes to the instances. Use this policy in conjunction with the preceding policy for users who need to launch instances from image listings. For users who need to launch stacks from stack listings, use this policy in conjunction with the next set of policy statements.

    Allow group MarketplaceUsers to manage instance-family in compartment ABC
    
    Allow group MarketplaceUsers to read app-catalog-listing in tenancy
    
    Allow group MarketplaceUsers to use volume-family in compartment ABC
    
    Allow group MarketplaceUsers to use virtual-network-family in compartment XYZ
    
  • The policies described in Policies for Managing Resources Used with Resource Manager grant access to stacks and jobs in the tenancy. Use the appropriate policy statements to give a group the ability to list, read, and use Marketplace stack listings. (Users do not need permission to run destroy jobs to launch a stack from a Marketplace listing, but they do need permissions to run plan jobs and apply jobs.)

If you need to write more restrictive policies, see the policy references on which these policies were based, Details for the Core Services and Details for Resource Manager, as needed.

For a Tenancy in the US Government Cloud Realm

Note

The following policies assume you already have existing policies for the specified groups to address the ability to inspect anything in the tenancy, including all compartments.
  • The following policy gives the specified example group, MarketplaceUsers, the ability to view all listings in the specified example compartment:

    Allow group MarketplaceUsers to read marketplace-listings in compartment ABC
  • The following policy gives the specified example group, MarketplaceUsers, the ability to work with all listings in the specified example compartment in any way possible. The statements include the ability to accept terms of use agreements, view listings, and create images and stacks from listings:

    Allow group MarketplaceUsers to manage app-catalog-listings in compartment ABC
    Allow group MarketplaceUsers to use marketplace-listings in compartment ABC
    Allow group MarketplaceUsers to manage instance-family in compartment ABC
    Allow group MarketplaceUsers to use volume-family in compartment ABC
    Allow group MarketplaceUsers to manage virtual-network-family in compartment ABC
    Allow group MarketplaceUsers to manage orm-stack in compartment ABC
    Allow group MarketplaceUsers to manage orm-job in compartment ABC
  • The following policy gives the specified example group, MarketplaceUsers, the ability to work with specific listings in the specified example compartment in any way possible. The statements include the ability to list and subscribe to images and the ability to create images and stacks from listings:

    Allow group MarketplaceUsers to manage app-catalog-listings in compartment ABC
    Allow group MarketplaceUsers to use marketplace-listings in compartment ABC where any {listing.id='123456', listing.id='987654'}
    Allow group MarketplaceUsers to manage instance-family in compartment ABC
    Allow group MarketplaceUsers to use volume-family in compartment ABC
    Allow group MarketplaceUsers to manage virtual-network-family in compartment ABC
    Allow group MarketplaceUsers to manage orm-stack in compartment ABC
    Allow group MarketplaceUsers to manage orm-job in compartment ABC
  • The following policy gives the specified example group, AgreementAcceptors, the ability to accept the terms of use agreement for any listing in the specified example compartment. The statements make it possible for anyone with the appropriate permissions to launch an image or stack from a listing without having the permission to accept the terms of use agreement themselves:

    Allow group AgreementAcceptors to read marketplace-listings in compartment ABC
    Allow group AgreementAcceptors to manage app-catalog-listings in compartment ABC

If you need to write more restrictive policies, see the policy reference on which policies for tenancies in the US Government Cloud realm were based, Details for the Marketplace Service.

Using the Console

To find a listing
  1. Open the navigation menu and click Marketplace. Under Marketplace, click All Applications.
  2. Under List Scope, in the Compartment list, click the name of the compartment where you want to look for listings.
  3. Click the Search for listings by entering a name, ID, category, or publisher name text box.
  4. Provide a search string, and then press ENTER. (If you provide a listing ID, it must contain the full, exact listing ID to match. Marketplace supports partial matching for other listing search types.)

Marketplace displays all current listings that contain the search string in either the name, listing ID, application category, or publisher name. To refine the results, you can filter them.

To filter listings
  1. Open the navigation menu and click Marketplace. Under Marketplace, click All Applications.
  2. Under List Scope, in the Compartment list, click the name of the compartment where you want to look for listings.
  3. Under Filters, do one or more of the following:
    • To display listings of a certain deployment type, click Type, and then click either Image or Stack.
    • To display listings from a specific publisher, click Publisher, and then click a publisher name.
    • To display listings from a particular product category, click Category, and then click a category name.
    • To display listings according to price, click Price, and then click a pricing model.

You can combine multiple filters to further narrow down listings. You can also clear filters to expand the list of listings that you see.

To view a listing's details
  1. Open the navigation menu and click Marketplace. Under Marketplace, click All Applications.
  2. Under List Scope, in the Compartment list, click the name of the compartment where you want to view a listing.
  3. Click the listing that you're interested in.
  4. Marketplace displays the listing overview by default. To view other details, do the following:
    • To view information about the publisher, click Provider.
    • To view other listings from the same publisher, click More Apps.
    • To view instructions for using the instance that you create from the listing, click Usage Information.
To launch an instance based on an image
Tip

When you create an instance, several other resources are involved (for example, an image, a cloud network, or a subnet). Those other resources can be in the same compartment  with the instance or in other compartments. You must have the required level of access to each of the compartments involved in order to launch the instance. This is also true when you attach a volume to an instance; they don't have to be in the same compartment, but if they're not, you need the required level of access to each of the compartments.
  1. Open the navigation menu and click Marketplace. Under Marketplace, click All Applications.
  2. Under List Scope, in the Compartment list, click the name of the compartment where you want to find the listing to launch.
  3. Click the listing that you're interested in.
  4. Review the Usage Instructions tab to ensure you understand what you will need to deploy and to access the instance after you launch it. Both Linux and Windows instances require a cloud network to launch the instance into. For more information, see Networking Overview. Depending on the type of instance, to access it, you might need an SSH key pair or a security list that enables Remote Desktop Protocol. For more information, see Managing Key Pairs on Linux Instances and Creating a Windows Instance.
  5. Under Version, click the package version of the image that you want to install. By default, the menu displays the latest version.
  6. Under Compartment, click the name of the compartment where you want to launch the instance. (If you don't have permissions to launch the instance in the selected compartment, it will be launched in the root compartment instead.)
  7. Select the check box to accept the terms of use, and then click Launch Instance.
  8. To finish launching the instance, follow the instructions in Creating an Instance.

The information you need to connect to an instance after you create it might be in the Usage Information or the Related Documents sections of the listing.

To launch a stack
Tip

When you create a stack, potentially many other resources are involved (for example, an instance, a cloud network, or a subnet), aside from the stacks and jobs resources. You must have the required access to all involved resources to create a stack. Those other resources can be in the same compartment  with the instance or in other compartments. You must have the required level of access to each of the compartments involved in order to launch the instance. This is also true when you attach a volume to an instance; they don't have to be in the same compartment, but if they're not, you need the required level of access to each of the compartments.
  1. Open the navigation menu and click Marketplace. Under Marketplace, click All Applications.
  2. Under List Scope, in the Compartment list, click the name of the compartment where you want to find the listing to launch.
  3. Click the listing that you're interested in.
  4. Review the Usage Instructions tab and ensure you understand what you will need to deploy and to access the instance after the stack finishes deployment.
  5. Under Version, click the package version of the stack that you want to install. By default, the menu displays the latest version.
  6. Under Compartment, click the name of the compartment where you want to launch the instance. (If you don't have permissions to launch the instance in the selected compartment, it will be launched in the root compartment instead.)
  7. Select the check box to accept the terms of use, and then click Launch Stack.
  8. On the Stack Information page, configure the following:
    • Name. Optionally, provide a name by which you can refer to the stack after it's deployed. Avoid entering confidential information.
    • Description. Optionally, provide a description of the stack. For example, you can specify the name of the application that will run on the instance after the stack is deployed.
    • Create in Compartment. This is the compartment where the stack will be created in the tenancy. (Stacks are attached to a specific region. However, where necessary, the resources on a given stack can be deployed across multiple regions.)
    • Tags. If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure whether to apply tags, skip this option (you can apply tags later) or ask your administrator.

    When you are ready, click Next.

  9. On the Configure Variables page, verify that the values for variables extracted from the Terraform configuration file are as you want them. Some variables might be required, but don't have a default value and must be configured before you can proceed. These vary from listing to listing, but often include the following: availability domain and compartment. Optionally, you can change default values, such as any display names automatically given to resources, to help differentiate them. For some stacks, you can customize additional variables by selecting the Additional Customization or WLS Instance Advanced Configuration check box. The variables in these sections otherwise use default values. When you are ready, click Next.
  10. On the Review page, confirm that variables have been configured properly. (Marketplace does not display variables that have default values or variables that you didn't change.) Then, click Create.

Resource Manager runs the plan job and the apply job to create stack resources accordingly. The information you need to connect to the instance created as part of the stack can appear in the Application Information tab or in the Usage Information or Related Documents sections of the listing.

To download a Terraform configuration file
  1. Open the navigation menu and click Marketplace. Under Marketplace, click All Applications.
  2. Under List Scope, in the Compartment list, click the name of the compartment where you want to find the listing to launch.
  3. Click the listing that you're interested in.
  4. Under Version, click the package version of the stack that you want. By default, the menu displays the latest version.
  5. Under Compartment, click the name of any compartment. (You must select a compartment in order to accept the terms of use in the next step.)
  6. Select the check box to accept the terms of use, and then click Download.
  7. Follow the prompts to save the configuration file locally.

For information about how to use the file to edit a stack or create a stack, see Managing Stacks and Jobs.

Using the Command Line Interface (CLI)

For information about using the CLI, see Command Line Interface (CLI). For a complete list of flags and options available for CLI commands, see the Command Line Reference.

To filter listings

Open a command prompt and run oci marketplace listing list to view listings that meet specified filter criteria:

oci marketplace listing list --package-type <package_type> --publisher-id <unique_publisher_ID> --category <product_category> --pricing <pricing_model>

For example, the following command lists only image listings:

oci marketplace listing list --package-type image

The following command lists only listings from the specified publisher:

oci marketplace listing list --publisher-id 29367738

The following command lists only listings from the specified product category:

oci marketplace listing list --category "database management"

The following command lists only listings that have the specified pricing model:

oci marketplace listing list --pricing byol
To view a listing's details

Open a command prompt and run oci marketplace listing get to view detailed information about a listing:

oci marketplace listing get --listing-id <listing_ID>

For example:

oci marketplace listing get --listing-id 29367738
To launch an instance

Open a command prompt and run oci compute instance launch to launch an instance:

oci compute instance launch --availability-domain <availability_domain> --compartment-id <compartment_OCID> --shape <instance_shape> --subnet-id <subnet_OCID> --image-id <image_OCID>

For example:

oci compute instance launch --availability-domain Uocm:PHX-AD-1 --compartment-id ocid1.compartment.oc1..example1example25qrlpo4agcmothkbgqgmuz2zzum45ibplooqtabwk3zz --shape VM.Standard1.2 --subnet-id ocid1.subnet.oc1.phx.exampleahetdvobxd5cvbqfcjmw2ddryahoqrp4ot2fauxvbdeirpa2gpt2a --image-id ocid1.image.oc1.phx.exampleae44ah3b5xyet6tlvli23cvbtetyugfckfwgg6fywrkk3fauxscyq