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. Listings are either image listings or stack listings. Image listings have a Launch Instance button. Stack listings have a Launch Stack button. Although Marketplace displays all listings by default, and most paid listings can be deployed by United States-based customers in any data center, some paid listings can only be deployed in United States regions. These listings have a region restriction label that marks them as US-only.

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  you should work in.

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

For administrators, the following policies provide access to Marketplace.

  • The following policy gives the specified group the ability to list, read, and use Marketplace image listings. It does not include the ability to create instances using images from listings. (For that, see the next policy.) Furthermore, to reduce the scope of access to just creating subscriptions in a particular compartment, specify that compartment instead of the tenancy in the third statement.

    Allow group <IAM_group_name> to manage app-catalog-listing in tenancy
    
  • The following policy gives the specified group 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.

    Allow group <IAM_group_name> to manage instance-family in compartment ABC
    
    Allow group <IAM_group_name> to read app-catalog-listing in tenancy
    
    Allow group <IAM_group_name> to use volume-family in compartment ABC
    
    Allow group <IAM_group_name> to use virtual-network-family in compartment XYZ
    
  • The policies described in Policies for Managing Stacks and Jobs 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.

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.

Using the Console

To find a listing
  1. Open the navigation menu. Under the Solutions and Platform group, go to Marketplace.
  2. Click the Search for listings by entering a name, ID, category, or publisher name text box.
  3. 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. Under the Solutions and Platform group, go to Marketplace.
  2. 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. Under the Solutions and Platform group, go to Marketplace.
  2. Click the listing that you're interested in.
  3. 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. Under the Solutions and Platform group, go to Marketplace.
  2. Click the listing that you're interested in.
  3. 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.
  4. Under Version, click the package version of the image that you want to install. By default, the menu displays the latest version.
  5. 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.)
  6. Select the check box to accept the terms of use, and then click Launch Instance.
  7. 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. Under the Solutions and Platform group, go to Marketplace.
  2. Click the listing that you're interested in.
  3. 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.
  4. Under Version, click the package version of the stack that you want to install. By default, the menu displays the latest version.
  5. 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.)
  6. Select the check box to accept the terms of use, and then click Launch Stack.
  7. 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.
    • 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 if you should apply tags, then skip this option (you can apply tags later) or ask your administrator.

    When you are ready, click Next.

  8. 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.
  9. 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. Under the Solutions and Platform group, go to Marketplace.
  2. Click the listing that you're interested in.
  3. Under Version, click the package version of the stack that you want. By default, the menu displays the latest version.
  4. 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.)
  5. Select the check box to accept the terms of use, and then click Download.
  6. 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