Publishing Guidelines

Customers also expect that solutions deliver as promised, include excellent documentation, and provide a support experience that is effective and low friction. This document describes the minimum bar required of Oracle partners for inclusion in Oracle Cloud Marketplace. You are encouraged to exceed these specifications, wherever possible. Solutions that include exceptions to these standards must be reviewed and approved by Oracle.

Keywords

This document uses key words as defined by IETF RFC 2119. For more information, seehttps://www.ietf.org/rfc/rfc2119.txt.

• Must - This word, or the terms "Required" or "Shall", mean that the definition is an absolute requirement of the specification.
• Must not - This phrase, or the phrase "Shall not", mean that the definition is an absolute prohibition of the specification.
• Should - This word, or the adjective "Recommended", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.
• Should not - This phrase, or the phrase "Not recommended" mean that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.
• May - This word, or the adjective "optional", mean that an item is truly optional. One vendor may choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product while another vendor may omit the same item. An implementation which does not include a particular option must be prepared to interoperate with another implementation which does include the option, though perhaps with reduced functionality. In the same vein an implementation which does include a particular option must be prepared to interoperate with another implementation which does not include the option (except, of course, for the feature the option provides.)

Vulnerability Severity Levels

Where there is any reference to security vulnerability in this section, the reference is to the Common Vulnerability Scoring System (CVSS) v3.0 ratings system. For more information about CVSS v3.0, see https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator.

Security

The Oracle Cloud Infrastructure security overview states that:

We [Oracle] believe that a dynamic security-first culture is vital to building a successful 
security-minded organization. We have cultivated a holistic approach to security culture in which 
all our team members internalize the role that security plays in our business and are
actively engaged in managing and improving our products' security posture. We have also
implemented mechanisms that assist us in creating and maintaining a security-aware culture.

You must read and understand the entire Oracle Cloud Infrastructure approach to security. See Oracle Cloud Infrastructure Security Guide in the Oracle Cloud Infrastructure documentation.

You must maintain a security first culture that understands and values the trust of our mutual customers.

Controls

Mandatory Guidelines

The following guidelines are mandatory for application listings in Oracle Cloud Infrastructure Marketplace. Each guideline must be followed. Before being approved, each application listing is validated against each of these guidelines.

• The App Name must be 80 characters or less. It should be 36 characters or less for optimal viewing.
• The App Name must be clear, concise, and free of spelling and grammar mistakes. It must have no line breaks.
• The Headline must clearly state the application's purpose. It must be described in two lines or less and be free of spelling and grammar mistakes.
• Font/Spacing on the listing must be consistent.
• All text must be free of spelling or grammar errors.
• The Description must be comprehensive and capture the target audience/type of user and present why the Listing is valuable.
• All links must point to the correct locations and open in a new tab or window.
• Text included in icons, banners, screenshots or videos must be legible.
• Images must not be blurred or stretched.
• Related Documents must provide consistent information for users to be able to:
  1. Launch an instance from Marketplace.
  2. Connect to the instance.
  3. Setup or start the application.
• The Support section must contain accurate contact details for customer to engage partner support. These contact details must contain an accurate phone number or email address.
• The System Requirements must contain the list of required Oracle Cloud Infrastructure components including compute shapes, security rules, IAM policies, block volumes, secondary VNICs, etc.
• Terms of Use must be included in your app install package and be free of spelling or grammar errors. Terms of Use name must be in title case. Links in Terms of Use must point to the correct locations and open in a new tab or window.
• The app install package version must match the version specified in any other related image or text for this package.
• The user must be able to launch, connect, and configure the application and related infrastructure using instructions included in the Usage and Related Documents sections.
• Each published solution includes a set of customer facing documentation. This documentation:
  • Must include prominent, detailed instructions for connecting to an instance.
  • Must include usage documentation or a link to the documentation.
  • Must include support details or a link to those details.
  • Must list compatible shapes.
  • Must document all network ports open by default on the instance.
• Acknowledgment: You agree that you shall not publish any paid Publisher listings on the Oracle Cloud Marketplace if the purchase of products and services and/or provision of related services to the customer may be funded in whole or in part by medicare, medicaid, or any other federal or state funded healthcare program.

Recommended Guidelines

The following guidelines can be considered as best practices that should be followed whenever possible.

• The release notes should be specified as bullet points with proper line breaks.
• The related documents should contain information on how to purchase a license if necessary.

General Guidelines

Here are some generic guidelines for listings of all types. For guidelines specific to application listings or image listings, see the relevant section.

• To ensure the listing content adapts correctly to the Oracle Cloud Marketplace cross platform styling, only basic formatting is allowed in the description sections. If the content is being copied from another rich text source (such as Microsoft Word), ensure any additional styling is removed before submitting the listing for review.
• Pasting content in plain text is recommended to avoid including any hidden styles and formatting. Adhering to these basic formatting options will ensure the listing content displays correctly across multiple devices and platforms.
• The use of the Oracle trademarks within the listing content (such as Oracle product names) must conform to the Third Party Usage Guidelines for Oracle Trademarks.
• The use of the Oracle logos within the listing content (such as infographics and screenshots) must conform to the Third Party Usage Guidelines for Oracle Logos.
• For any images such as logos, icons, or banners:
  • Ensure that the images are sized to match the specified dimensions.
  • Save images in the specified file format with compression.
  • Ensure that the image file size is within the specified file size.
  • Your banner must be 1160 pixels (width) by 200 pixels (height), a maximum of 10 MB, and must be a BMP, GIF, JPEG (JPG), or PNG file.
  • Your company logo must be 115 pixels by 115 pixels, a maximum of 5 MB, and must be a BMP, GIF, JPEG (JPG), or PNG file..
  • Your icon must be 130 pixels by 130 pixels, a maximum of 5 MB, and must be a BMP, GIF, JPEG (JPG), or PNG file.
  • Application icons should be distinctive and unique. Don’t submit multiple applications with the same icon.
  • Don’t use any Oracle logos or trademarks in the application icons. Ensure you have the usage rights to any third party images used.
• The content of the description section should provide a high-level overview of the application. It must describe the value and benefit to the customer of running/hosting the application on the Oracle Cloud.
• A long description must be preceded by a short description. Don’t repeat the short description in the long description section.
• The description should not highlight or refer to “Oracle Validated Integration”. The Oracle Validated Integration (OVI) program is only applicable to on-premises solutions, and does not apply to the Oracle Cloud.
• In the Usage Information field:
  • Include a link to a Getting Started guide that contains complete details required by users to get started.
  • Include links to any technical documentation, data-sheets, user guides, and other related documents (including the ones you specify in the Related Documents section).
  • List the ports that must be opened. Add a link such as "How to configure open ports" which describes the steps to open ports using the Oracle Cloud Infrastructure Console.
• In the Screenshots and Videos field, for screenshots:
  • A minimum of two screenshots is recommended.
  • When taking screenshots, hide any browser tool bars and menus. Use the browser full-screen mode.
  • The recommended dimensions for screenshots is 640 pixels (width) x 480 pixels (height). Other suitable sizes include 1024x768 and 1200x900. Larger images should be cropped or resized.
  • For best results, images should be created with a native 4:3 aspect ratio. For any images that don’t fit the 4:3 aspect ratio, such as screenshots of mobile phone apps, pad the image with an appropriately colored or transparent background to fit the required image size. Use an image editor to add padding.
  • Screenshots must be a maximum of 5 MB, and must be a BMP, GIF, JPEG (JPG), or PNG file.
  • Uploaded images are automatically scaled to 240 x 180 pixels thumbnails on the main listing page.
  • Uploaded images are automatically scaled to fit the 600 x 450 pixels media viewer.
  For videos:
  • Include a demonstration video as the first item in the list in the Screenshots and Videos field.
  • Promotional videos that are hosted on YouTube or Vimeo can be embedded directly in the screenshot list and media viewer.
  • The URL address for the video must start with either http:// or https://
  • The main demo video should be short and to the point, focusing on the main features of the application and the value of the application/integration on the Oracle Cloud.
  • Longer videos and promotional content can be included as additional videos.
• In the Related Documents field:
  • Addition of a data sheet specific to the Oracle Cloud integration is a minimum requirement.
  • Data sheets should be specific to the Oracle Cloud enabled release of the application.
  • Add a "Getting Started with Oracle Cloud Infrastructure" document that provides complete details for customers to configure and setup the software.
• In the System Requirements field:
  • List any Oracle Cloud PaaS services required to install and run the application.
  • List all Oracle Cloud SaaS services that the application is integrated with.
  • List any third party system dependencies.
  • Include browser-specific dependencies or supported mobile platforms in this section.
  • Be specific about any version or edition dependencies, or sizing requirements (if required).

Mandatory Guidelines for Linux Images

The following table lists the mandatory image guidelines and corresponding error code. Each guideline must be followed. Before an image is published to Oracle Cloud Infrastructure Marketplace, each image is validated against each of the following mandatory guidelines.

Mandatory Guidelines for Windows Images

Recommended Guidelines for Linux Images

The following guidelines are recommended for images listed in Oracle Cloud Infrastructure Marketplace. Each guideline is considered a best practice that should be followed if possible.

PasswordAuthentication no
ChallengeResponseAuthentication no
UsePAM no

Mandatory Guidelines

The following are mandatory guidelines for stacks listed in Oracle Cloud Infrastructure Marketplace. Each guideline must be followed. Before being published, each stack artifact is validated against each of these guidelines.

1. Stack artifact must be a zip file including the Terraform configuration file(s) and a Schema file.
   • Zip must include at least one configuration file (.tf) in the root folder.
   • Zip must include the Schema file (.yaml) in the root folder.
   • Zip must not include a Terraform state file in the zip file. State files are managed by Oracle Resource Manager (ORM). When customers launch a stack, ORM creates and manages the resources and the state file become available for download only.
   • Zip must not include Terraform runtime configuration folder (.terraform).
2. Terraform configuration must only use instance image(s) that are Approved or Published (Public or Private) Marketplace Image(s). It must have a Marketplace subscription to each of these image(s). It must have hard-coded reference(s) to these Marketplace Image(s). See Sample Terraform Configuration for a Marketplace Image Subscription and Usage for more details.
3. Binaries must not be downloaded from external repositories. All binaries and dependencies must be baked into the published Marketplace Image.
4. The Terraform remote exec provisioner must only be run within the Oracle Cloud Infrastructure domain. It must not download files on a remote server.
5. Third-party code or binaries must not be downloaded using cloud-init.
   1. cloud-init is a commonly used startup configuration utility for cloud compute instances. It accepts configuration via user-data mechanisms specified as part of the metadata definition on oci_core_instance resource.
   2. There are multiple user-data formats supported by cloud-init. See https://cloudinit.readthedocs.io/en/latest/topics/format.html.
   3. Regardless of the user-data format, cloud-init MUST NOT be used for downloading any third-party code or binary. All binaries required during the instance launch process (bootstrap), if not available within the image, should be downloaded by a process (script) baked as part of the image distribution, not injected via cloud-init (for example, leveraging wget).
   4. However, you may have a cloud-init template set up for customers to use in some particular scenarios, for example, to import a license key file, or to import a configuration file. In that case, you should provide a variable in the Terraform template code to enable customers to enter some data into the cloud-init building block, for example, leveraging Terraform template_file data source.
6. The Terraform provider must be Oracle Cloud Infrastructure. Other cloud providers or third-party application providers are not supported.
7. If a Terraform module is used, it must be loaded from local relative paths. It cannot be loaded from a remote repository.
8. The Terraform configuration must use instance principal authentication.

9. You must specify the minimum and maximum supported Terraform versions on which you have tested your stack.

   • Specify the minimum required Terraform version in the format: ~> <major_version>.<minor_version>.<patch_version>.

     Where, the patch_version is always set to 0. When a stack is launched, Resource Manager checks the <major_version>.<minor_version> that you have defined in your code and uses the most recent patch version available. That's why you must use the ~> sign instead of the => sign while specifying the minimum required Terraform version.

     For example, ~> 0.14.0 indicates the supported Terraform versions are 0.14.0 or later.

   • Specify the maximum required Terraform version in the format: < <major_version>.<minor_version>.

     For example, < 0.15 indicates that the supported Terraform versions are earlier than 0.15.

   The following example shows how to specify the minimum and maximum supported Terraform versions when you have tested your stack only on Terraform 0.14.

   terraform 
   { required_version = "~> 0.14.0, < 0.15" }

For more information about Terraform, including the Oracle Cloud Infrastructure provider, instance principal authentication, and the remote exec provisioner, see the Terraform documentation for Provider Configuration. For information about supported versions of Terraform, see Getting Started with the Terraform Providerin Oracle Cloud Infrastructure Documentation.

Coding Guidelines for Terraform Configurations

The following guidelines are recommended for stacks listed in Oracle Cloud Infrastructure Marketplace. Each guideline is considered a best practice that should be followed if possible.

• Stack artifact should enable customers to either create all the infrastructure resources or point to existing ones (network, storage, and so on).
• Naming conventions and formatting should be followed:
  • Casing - Use lower_snake_case for all naming. This applies to variable names, resource names, module names, file names, display names, and so on.
  • Specifying Resource Type - Do not include the resource or data source type in the name. In Terraform, resources and data sources are always referenced by <type>.<name>. As such, there is no need to include the type in the name itself.
  • ID vs OCID - In Oracle Cloud Infrastructure, id generally refers to a field that takes an OCID. As such, variables should use id when referring to OCID values, instead of using ocid.
  • Variable Names - Variable names for Oracle Cloud Infrastructure resources should typically use the same name as used for the Terraform resource.
  • Display Names - Display names for Oracle Cloud Infrastructure resources should typically use the same name as used for the Terraform resource.
  • Naming module variables and outputs - When using a module, the naming of the input (variables) and the outputs should be exposed to the caller.
  • terraform fmt should be applied to all Terraform before checking it in.