Creating AMI and container product usage instructions for AWS Marketplace - AWS Marketplace
RequirementsWriting the release notesWriting the usage instructionsWriting the upgrade instructionsWriting CloudFormation delivery instructionsMonitoring and assessing application functionsRotating programmatic system credentials and cryptographic keys

Creating AMI and container product usage instructions for AWS Marketplace

As an AWS Marketplace seller, one way of delivering your products to buyers is with Amazon Machine Images (AMIs). An AMI provides the information required to launch an Amazon Elastic Compute Cloud (Amazon EC2) instance. You create a custom AMI for your product, and buyers can use it to create Amazon EC2 instances with your product already installed and ready to use. The following sections provide you with information about writing usage instructions and managing AMIs,

For more information, see AMI-based products in AWS Marketplace.

Requirements

When creating usage instructions for your product, you must include the following information:

  • Location of all sensitive information saved by customers

  • Explain all data encryption configuration

  • Step-by-step instructions for rotating programmatic system credentials and cryptographic keys. The AMI-based product requirements for AWS Marketplace explain the basic requirements for listings that use credentials and cryptographic keys.

  • Provide detailed instructions on how the user interacts with your application to decrypt necessary data if your application makes use of any encryption techniques

  • Step-by-step instructions for how to assess and monitor the health and proper function of the application. For example:

    • Navigate to your Amazon EC2 console and verify that you're in the correct region.

    • Choose Instance and select your launched instance.

    • Select the server to display your metadata page and choose the Status checks tab at the bottom of the page to review if your status checks passed or failed.

Writing the release notes

Each time you update a product, you must provide a description of the changes in the release notes. The release notes should contain specific information to help the user decide whether to install the update. Use clear labels for the update, such as "Critical" for a security update or "Important" or "Optional" for other types of updates.

Writing the usage instructions

Provide usage instructions that help ensure that the buyer can successfully configure and run the software. The usage instructions you provide are shown during the configuration process.

To write effective usage instructions, follow these guidelines:

  • Assume the user is interested but uninformed.

  • Provide the user with all the information needed to launch and use your product, including any configuration settings and special steps.

Example usage instructions:

  1. Launch the product via 1-Click.

  2. Use a web browser to access the application at https://<EC2_Instance_Public_DNS>/index.html.

  3. Sign in using the following credentials:

    • Username: user

    • Password: the instance_id of the instance

Writing the upgrade instructions

Provide details on how buyer can upgrade from an earlier version of the product. Include information on how to preserve data and settings when creating another instance. If there is no upgrade path, edit this field to specifically mention that.

Example upgrade instructions:

  1. Do ****, and then ****.

  2. Check that all plugins used by your project are compatible with version *.*, by doing ***. If they aren't compatible, do ***.

  3. Make a backup of your data, by doing ***.

Writing CloudFormation delivery instructions

When using CloudFormation delivery, you must also include the following:

  • A purpose for each AWS Identity and Access Management (IAM) role and IAM policy created by the AWS CloudFormation template

  • A purpose and location of each key created by the AWS CloudFormation template

  • Network configuration details in deployments involving more than a single element

  • A detailed guide on how your applications are launched and how they're configured to communicate if the deployment includes multiple AWS resources

  • A pricing breakdown that includes the cost of running AWS resources added above the standard limits. Provide prescriptive guidance on managing AWS service limits.

  • All data encryption configuration. For example: Amazon S3 server-side encryption, Amazon Elastic Block Store (Amazon EBS) encryption, Linux Unified Key Setup (LUKS), etc.)

Monitoring and assessing application functions

To monitor and assess application functions

  1. Navigate to your Amazon EC2 console and verify that you're in the correct region.

  2. Choose Instances and select your launched instance.

  3. Select the server to display your metadata page and choose the Status checks tab at the bottom of the page to review if your status checks passed or failed.

Note

If any of the data stores are proprietary, provide step-by-step instructions for configuration, backup, and recovery.

Rotating programmatic system credentials and cryptographic keys

The AMI-based product requirements for AWS Marketplace explain the basic requirements for listings that use credentials and cryptographic keys.

Include the following for rotating programmatic system credentials and cryptographic keys:

  • Prescriptive guidance on managing AWS service quotas. For more information see the AWS General Reference Guide.

  • A pricing breakdown including the cost of running AWS resources added above the standard quota. This can be included in your product usage instructions or linked to documentation containing detailed information about managing and requesting increased service quotas.