Publishing Guidelines

To create templates, stacks, images, and listings for Oracle Cloud Infrastructure Marketplace, ensure that you comply with all the relevant guidelines.

Topics:

About OCI Marketplace Publisher Guidelines

(OCI) allows Oracle partners to distribute their solutions to OCI customers via Oracle Cloud Marketplace. Oracle customers trust that these solutions are built and maintained in a way that ensures that their security and privacy is the top priority.

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.

Key Words

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

  • You must maintain awareness of security alerts and advisories that have an impact on your solutions. Here are some common sources of security alerts:
    • SecurityFocus maintains recent advisories for many open source and commercial products. https://www.securityfocus.com/
    • The National Vulnerability Database. https://nvd.nist.gov/vuln
    • US-CERT and the Industrial Control Systems CERT (ICS-CERT) publish regularly updated summaries of the most frequent, high-impact security incidents. https://www.us-cert.gov/ics
    • Full Disclosure at SecLists.org, is a high volume, public, vendor-neutral forum for detailed discussion of vulnerabilities and exploitation techniques. https://seclists.org/fulldisclosure/
    • The Computer Emergency Readiness Team Coordination Center (CERT/CC) has up-to-date vulnerability information for the most popular products. https://www.cert.org
  • You should watch for Oracle Cloud Infrastructure platform updates that may have an impact on images that you have published.
  • You must notify OCI within 3 business days of any newly discovered vulnerabilities that impact your solutions with a CVSS rating of 9.0 or higher.
  • You must notify Oracle Cloud Infrastructure within 5 business days of any newly discovered vulnerabilities that impact your solutions with a CVSS rating between 7.0 and 8.9.
  • You must notify OCI within 20 business days of any newly discovered vulnerabilities that impact your solutions with a CVSS rating between 4.0 and 6.9.
  • You must publish updated solutions that mitigate newly discovered vulnerabilities in a timely fashion.
  • You must allow customers to keep their solutions updated to protect against newly discovered vulnerabilities. Some common patterns are:
    • Automatically applying security updates.
    • Allowing a customer to run a command to apply security updates.
    • Providing a process that allows a customer to replace any current deployments with an updated version. This process should be sufficiently low friction so that a customer is not discouraged from performing the work required.
  • You should publish updated solutions with general security updates on a quarterly basis.
  • If you might require the execution of a non-disclosure agreement before disclosing a vulnerability to Oracle, your must have executed an Oracle Confidentiality Agreement (CDA) prior to publication of your first image. Your Oracle Partner team will assist with this process.

Guidelines for Listings

While creating your application listings, ensure that you are familiar with and comply with the relevant guidelines.

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).

Guidelines for Images

When you create an image list in Oracle Cloud Infrastructure Marketplace, ensure that the images you create for the listing comply with the relevant guidelines.

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.

Error Code Description
S01 SSH host keys must be unique to each instance. Use the oci-image-cleanup utility provided by the oci-utils package on GitHub. This will remove all SSH host keys, so that they are regenerated on first boot.
S08 Images must ingest an SSH public key provided by a customer as part of the instance launch process. Ensure the image is cloud-init enabled.
S10 Any authorized_keys files must only contain keys provided by the user when the instance is launched. Use the oci-image-cleanup utility provided by the oci-utils package on GitHub.
S14 Root user login must be disabled. At least 1 of the following 3 conditions must be met:
  • The root user's login shell must be set to /sbin/nologin.
  • The SSH service config /etc/ssh/sshd_config must not permit root login. Manually configure the following setting:
    PermitRootLogin no
  • All entries in the /root/.ssh/authorized_keys file must contain
    no-port-forwarding, no-agent-forwarding,
                            no-X11-forwarding.
    The root user must not have usable entries in the authorized_keys file. Use the oci-image-cleanup utility provided by the oci-utils package on GitHub.

    By default, Oracle Cloud Infrastructure instances that are launched from cloud-init enabled images add the forwarding options and use the command option of the authorized_keys file to effectively disable any user-provided SSH key for the root user. The code below is a sample of the authorized_keys file created by Oracle Cloud Infrastructure using cloud-init:

    no-port-forwarding,
    no-agent-forwarding,
    no-X11-forwarding,
    command="echo 'Please login as the user \"opc\" rather than the user \"root\".';echo;sleep 10"
S16 Images must not have any operating system level users configured with a password and MUST NOT have an empty password.
G01 Image must boot for all compatible shapes. Manually verify by successfully launching instances for each compatible shape.
G03 Image must not have any hard-coded MAC addresses. Empty the /etc/udev/rules.d/70-persistent-net.rules file.
G05 DHCP must be enabled. Ensure it is configured manually. Ensuring you can SSH into an instance of this image confirms that DHCP is enabled.
G08 Ensure that the image does not use Instance Metadata Service v1 (IMDSv1). If the image uses IMDSv1 endpoints, Oracle recommends that you disable IMDSv1 and upgrade to IMDSv2. See Upgrading to the Instance Metadata Service v2 in Oracle Cloud Infrastructure documentation.

Mandatory Guidelines for Windows Images

Error Code Description
W01 Before creating a custom Windows image, you must generalize the Windows instance using Sysprep. See Creating a Generalized Image.
W02 The opc account must not be preserved when running Sysprep generalize. See Creating a Generalized Image.
G08 Ensure that the image does not use Instance Metadata Service v1 (IMDSv1). If the image uses IMDSv1 endpoints, Oracle recommends that you disable IMDSv1 and upgrade to IMDSv2. See Upgrading to the Instance Metadata Service v2 in Oracle Cloud Infrastructure documentation.

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.

Error Code Description
S02 Mandatory Access Control (MAC) should be enabled. See https://www.linux.com/news/securing-linux-mandatory-access-controls.
S03 An Operating System (OS) Firewall should be enabled and configured to block any ports not specifically required as indicated in the listing documentation.
S04 All sensitive data such as passwords and private keys should be removed. This type of data can often be found in log files, source code, or build artifacts. To remove such files, use the oci-image-cleanup utility provided by the oci-utils package on GitHub.
S07 cloud-init packages should be available for use during instance launch.
S11 Configure the SSH service to prevent password-based login. Manually configure the following settings:
PasswordAuthentication no
ChallengeResponseAuthentication no
UsePAM no
S15 Image software should be updated as part of the final packaging process.
S17 Application passwords should not be hard-coded. Any passwords should be uniquely generated the first time the instance launches:
G02 Images should run in paravirtualized mode. Images may run in native mode. Images should not run in emulated mode.
G04 Any network managers should be stopped. See https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux_OpenStack_Platform/3/html/Installation_and_Configuration_Guide/Disabling_Network_Manager.html.
G06 Images should utilize the NTP service provided by Oracle Cloud Infrastructure. See Configuring the Oracle Cloud Infrastructure NTP Service for an Instance.
G07 Images should have iSCSI timeout values set for proper boot volume connectivity. See https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/5/html/Online_Storage_Reconfiguration_Guide/iscsi-modifying-link-loss-behavior-root.html.

Guidelines for Stacks

Oracle recommends that you adopt general Terraform best practices for building your Terraform template. However, there are specific Marketplace stack standards to follow in order to publish a stack.

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.