# AMI-based products in AWS Marketplace
As an AWS Marketplace seller, you can deliver your products to buyers with [Amazon Machine Images (AMIs)](https://docs.aws.amazon.com/glossary/latest/reference/glos-chap.html#AmazonMachineImage). 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 EC2 instances with your product already installed and ready to use. This topic provides information about using AMIs to deliver your AWS Marketplace product.
When buyers use the AMI that you provide, they're billed for instances that they create, following the pricing and metering options that you create for your product. Buyers can use your product AMI in the same way that they use other AMIs in AWS, including making new custom versions of the AMI. EC2 instances created from the AMI are still billed as your product, based on the AMI product code.
## AMI-based product delivery methods
You can deliver AMI-based products in one of the following ways:
+ **Single AMI** – Buyers select and use the AMI as a template for an EC2 instance. Buyers can find these products using the **Amazon Machine Image** delivery method filter. For more information, see [Creating AMI-based products](ami-single-ami-products.md).
+ **AWS CloudFormation templates** – You create templates that allow buyers to install a system of multiple instances with different roles as a single unit. Buyers can find these products using the **CloudFormation** delivery method filter. For more information, see [Add CloudFormation templates to your product](cloudformation.md).
## Additional resources
For more information about AMI products, see the following topics.
**AWS Marketplace**
+ [Product pricing for AWS Marketplace](pricing.md)
+ [Configuring custom metering for AMI products with AWS Marketplace Metering Service](custom-metering-with-mp-metering-service.md)
**AMI-based products**
+ [Understanding AMI-based products in AWS Marketplace](ami-getting-started.md)
+ [Creating AMI-based products](ami-single-ami-products.md)
+ [Managing AMI-based products as an AWS Marketplace seller](concept-chapter-servicename.md)
+ [Add CloudFormation templates to your product](cloudformation.md)
+ [Best practices for building AMIs for use with AWS Marketplace](best-practices-for-building-your-amis.md)
+ [AMI product pricing for AWS Marketplace](pricing-ami-products.md)
+ [Receiving Amazon SNS notifications for AMI products on AWS Marketplace](ami-notification.md)
+ [AMI product checklist for AWS Marketplace](aws-marketplace-listing-checklist.md)
+ [AMI-based product requirements for AWS Marketplace](product-and-ami-policies.md)
# Understanding AMI-based products in AWS Marketplace
As an AWS Marketplace seller, you can deliver your products to buyers with [Amazon Machine Images (AMIs)](https://docs.aws.amazon.com/glossary/latest/reference/glos-chap.html#AmazonMachineImage). An AMI provides the information required to launch an Amazon Elastic Compute Cloud (Amazon EC2) instance. The following section explains the key concepts for working with AMI-based products.
**Note**
You can only use one AMI in an AMI product, but you can add versions of that AMI to the product.
**Topics**
+ [Product lifecycle](#ami-product-lifecycle)
+ [AMI product codes](#ami-product-codes)
+ [Change requests](#ami-change-requests)
+ [Product Load Forms](#ami-product-load-forms)
+ [Annual agreement amendments](#annual-agreement-amendments)
+ [FPGA Products](#ami-fpga-products)
## Product lifecycle
AMI-based products include one or more versions of the software, plus metadata about the product as a whole. When you create the product, you configure its properties in AWS Marketplace including the product name, description, and pricing. You also determine the appropriate categories for your product and add keywords so your product appears in relevant searches.
You also create the first version of the software. This can be just the AMI, or you can include AWS CloudFormation templates or software packages that buyers can use to create their own AMIs. For more information, see [AMI-based product delivery methods](ami-products.md#ami-product-delivery-methods).
For paid products, buyers are billed for the number of installed instances. To meter on a different dimension that your software tracks, such as the number of product users, integrate your product with the AWS Marketplace Metering Service. For more information, see [Configuring custom metering for AMI products with AWS Marketplace Metering Service](custom-metering-with-mp-metering-service.md).
When you create your product and the first version of your software, it's initially published in a limited scope so that only your account can access it. When you're ready, you can publish it to the AWS Marketplace catalog to allow buyers to subscribe and purchase your product.
You use the [Server product](https://aws.amazon.com/marketplace/management/products/server) page to view the list of your products. Products will have one of the following statuses:
+ **Staging ** – An incomplete product for which you are still adding information. At the first **Save and exit** from the create self-service experience, the successful change request creates an unpublished product with information from the full steps you submitted. From this state, you can continue adding information to the product or change already submitted details through change requests.
+ **Limited** – A product is complete after it is submitted to the system and passes all validation in the system. Then the product is released to a **Limited** state. At this point, the product has a detail page that is only accessible to your account and whoever you have allowlisted. You can test your product through the detail page. If necessary, for more information and help, contact the [https://aws.amazon.com/marketplace/management/contact-us/?#](https://aws.amazon.com/marketplace/management/contact-us/?#).
+ **Public** – When you're ready to publish the product so that buyers can view and subscribe to the product, you use the **Update visibility** change request. This initiates a workflow for the AWS Marketplace Seller Operations team to review and audit your product against our [policies](https://docs.aws.amazon.com/marketplace/latest/userguide/product-and-ami-policies.html). Once the product is approved and the change request is processed, the product is moved from a status of **Limited** to **Public**.
+ **Restricted** – If you want to stop new users from subscribing to your product, you can restrict the product by using the **Update visibility** change request. A **Restricted** status means that existing users can continue to use the product. However, the product will no longer be visible to the public or be available to new users.
The lifecycle of an AMI-based product for AWS Marketplace does not end after you publish the first version. You should keep your product up to date with new versions of your software, and with security patches for the base operating system.
As an example of a complete AMI-based product lifecycle, imagine a seller wants to sell their AMI-based product on AWS Marketplace. Following is how the seller creates and maintains the product over time:
1. **Create a product** – The seller creates the product, and publishes version 1.0.0 to AWS Marketplace. Buyers can create instances of version 1.0.0 and use it.
1. **Add a new version** – Later, the seller adds a new feature to the product, and adds a new version, 1.1.0, that includes the feature. Buyers can still use the original version, 1.0.0, or they can choose the new version, 1.1.0.
**Note**
Unlike new products, new versions are published to full public availability. You can only test them in AWS Marketplace without customers seeing them if the product as a whole is in limited release.
1. **Update product information** – With version 1.1.0 available, the seller lets buyers know about the new feature by updating the product information with new highlight text describing the feature.
1. **Add a minor version** – When the seller fixes a bug in version 1.1.0, they release it by adding a new version 1.1.1. Buyers now have the choice of using version 1.0.0, 1.1.0, or 1.1.1.
1. **Restrict a version** – The seller decides that the bug is serious enough that they don’t want buyers to be able to use version 1.1.0, so they restrict that version. No new customers can then buy 1.1.0 (they can only choose 1.0.0 or 1.1.1), although existing buyers still have access to it.
1. **Update version information** – To help those existing buyers, the seller updates the version information for 1.1.0 with a suggestion to upgrade to version 1.1.1.
1. **Monitor usage** – As buyers purchase and use the product, the seller monitors sales, usage, and other metrics using the AWS Marketplace [Seller reports, data feeds, and dashboards in AWS Marketplace](reports-and-data-feed.md).
1. **Remove the product** – When the product is no longer needed, the seller removes it from AWS Marketplace.
In this example, the seller created three different versions of the AMI in the product, but only two were available to new buyers (prior to removing the product).
To make modifications to versions or the product information, you create [change requests](single-ami-create-change-request.md) in the AWS Marketplace Management Portal.
For detailed instructions on the steps to create and manage your AMI-based product, see [Creating AMI-based products](ami-single-ami-products.md).
## AMI product codes
A unique product code is assigned to your product when you create it in AWS Marketplace. That product code is associated with the AMI for your product and is used to track usage of your product. Product codes are propagated automatically as buyers work with the software. For example, a customer subscribes and launches an AMI, configures it, and produces a new AMI. The new AMI still contains the original product code, so correct usage tracking and permissions remain in place.
**Note**
The product *code* is different than the product *ID* for your product. Each product in AWS Marketplace is assigned a unique product ID. The product ID is used to identify your product in the AWS Marketplace catalog, in customer billing, and in seller reports. The product code is attached to instances created from your AMI as instance metadata. When an AMI with that product code is used to create an instance, the customer will get a bill that shows the associated product ID. After you create your product, find the product code and the product ID in the AWS Marketplace Management Portal page for your product.
As a seller, your software can get the product code for the running Amazon Elastic Compute Cloud (Amazon EC2) instance at runtime from the instance metadata. You can use the product code for extra security, such as validating the product code at product start. You can't make API calls to an AMI's product code until the product has been published into a limited state for testing. For more information about verifying the product code, see [Verifying your software is running on your AWS Marketplace AMI](best-practices-for-building-your-amis.md#verifying-ami-runtime) .
## Change requests
To make changes to a product or version in AWS Marketplace, you submit a **change request** through the AWS Marketplace Management Portal. Change requests are added to a queue and can take from minutes to days to resolve, depending on the type of request. You can see the status of requests in the AWS Marketplace Management Portal.
**Note**
In addition to the AWS Marketplace Management Portal, you can also create change requests by using the [AWS Marketplace Catalog API](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/seller-products.html).
The types of changes you can request for AMI-based products include:
+ Update product information displayed to buyers.
+ Update version information displayed to buyers.
+ Add a new version of your product.
+ Restrict a version so that new buyers can no longer access that version.
+ Update the AWS Regions that a product is available in.
+ Update the pricing and instance types for a product.
+ Remove a product from AWS Marketplace.
**Note**
Some change requests require you to use product load forms to create the request. For more information, see [Product Load Forms](#ami-product-load-forms).
### Update change request
Change requests that start with an update will load the current details. You then make updates, which overwrite the existing details.
### Add or restrict change request
Add and restrict request pairs are specifically for steps and updates that are provisioned after each request succeeds. A request succeeds after you choose **Save and exit** and **Submit** actions in the self-service experience.
For example, if the AMI asset is provisioned to the instances and Regions once added, then they can only be restricted rather than completely removed. This means existing subscribers and users can continue to use the product until their subscription or contract runs out. However, no new subscribers can be added to a product that is in a **Restricted** status.
## Product Load Forms
Typically, you use [AWS Marketplace Management Portal](https://aws.amazon.com/marketplace/management) to create or edit your product. However, a few operations require you to use a *Product Load Form* (PLF).
A PLF is a spreadsheet that contains all the information about a product. To obtain a PLF, you can:
+ Download the PLF for an existing product from the product's details page in the AWS Marketplace Management Portal.
+ Select a menu item for an action that requires a PLF. For example, if you create a new monthly billed server product, the system prompts you to download the appropriate PLF.
If the action is an edit to an existing product, the PLF is pre-populated with the information for that product, so you only need to change the details that you want to update.
+ If you need a new, blank PLF, navigate to the AWS Marketplace Management Portal [File upload](https://aws.amazon.com/marketplace/management/product-load) page. The page contains links to PLFs for the product type you want to create.
After you have completed your PLF, upload it to the AWS Marketplace Management Portal [ File upload](https://aws.amazon.com/marketplace/management/product-load) page. The PLF itself has more detailed instructions in the **Instructions** tab.
## Annual agreement amendments
Hourly annual (annual) plan amendments allow you and your buyers to make the following changes to existing plans:
+ Switch between Amazon EC2 instance type families
+ Switch between Amazon EC2 instance type sizes
+ Add a new instance type
+ Increase the quantity of an existing instance type in the agreement
Buyers can make a change as long as the prorated cost of the change is greater than zero (they can't lower the value of the subscription). The prorated cost of the newly added Amazon EC2 instances is based on the annual cost of the instance type adjusted for the remaining term of the agreement. When switching instance types, the prorated cost of the removed Amazon EC2 instance type is deducted from the prorated cost of the newly added Amazon EC2 instance type.
No additional action is required to enable amendments on AMI annual products. Amendments are supported on all agreements made from public offers and agreements from private offers that don't use installment plans.
You can see the amendments made by your buyers on the following dashboards:
+ [Agreements and renewals dasboard](https://docs.aws.amazon.com/marketplace/latest/userguide/agreements-renewals-dashboard.html) – The list of amended agreements.
+ [Billed revenue dashboard](https://docs.aws.amazon.com/marketplace/latest/userguide/billed-revenue-dashboard.html) – Charges to the customer.
+ [Collections and disbursement dashboard](https://docs.aws.amazon.com/marketplace/latest/userguide/collections-disbursement-dashboard.html) – The disbursement.
## FPGA Products
FPGA (Field Programmable Gate Array) products are specialized AMI products that support F2 instance types with Amazon FPGA Image (AFI) configurations. Unlike standard AMIs, FPGA products include AFI IDs that are dynamically loaded by the AMI for hardware acceleration on supported instance types.
**Key characteristics:**
+ FPGA products support F2 instance types exclusively for FPGA acceleration.
+ Each product version can include one or more AFI IDs, with a maximum of 15 AFI IDs per version.
+ AFIs are loaded on-the-fly rather than launched like AMIs, providing dynamic hardware acceleration capabilities.
+ When you add new regions to your FPGA product, automated regional AFI cloning is performed by AWS Marketplace to ensure your product is available across supported AWS Regions.
+ While FPGA products can be offered on other instance types, the AFIs will only be loaded and provide hardware acceleration on F2 instance types. On other instance types, the AMI functions without the FPGA acceleration capabilities.
FPGA products are ideal for compute-intensive workloads requiring specialized hardware acceleration such as genomics research, financial analytics, real-time video processing, big data analytics, and machine learning inference. The dynamic loading of AFIs enables buyers to leverage FPGA acceleration without managing the underlying FPGA infrastructure.
# Creating AMI-based products
The Amazon Machine Image (AMI) self-service experience guides you as you create your product listing and make change requests. By using the self-service experience, you can update your product listing directly with less time needed for processing by the AWS Marketplace Seller Operations team. Many steps of the self-service experience align with the catalog system in AWS Marketplace, which facilitates direct validation instead of waiting for processing and validation from the AWS Marketplace Seller Operations team. This topic explains how to use the AMI self-service experience to create a product listing for a single AMI. Customers use AMIs to create Amazon EC2 instances with your product already installed and configured.
**Topics**
+ [Prerequisites](#single-ami-prerequisites)
+ [Understand the self-service experience](#understand-ami-self-service-exp)
+ [Create the listing](#ami-create-product)
+ [Additional resources](#ami-single-create-resources)
## Prerequisites
Before you create an AMI product listing, you must complete the following prerequisites:
1. Have access to the AWS Marketplace Management Portal. This is the tool that you use to register as a seller and manage the products that you sell on AWS Marketplace. To learn more about getting access to the AWS Marketplace Management Portal, see [Policies and permissions for AWS Marketplace sellers](detailed-management-portal-permissions.md).
1. Register as a seller and, if you want to charge for your products, submit your tax and banking information. To learn more about becoming a seller, see [Getting started as an AWS Marketplace seller](user-guide-for-sellers.md).
1. Have a product that you want to sell. For AMI-based products, this typically means you have created or modified your server software, and created an AMI for your customers to use. To learn more about preparing an AMI for use in AWS Marketplace, see [Best practices for building AMIs for use with AWS Marketplace](best-practices-for-building-your-amis.md).
## Understand the self-service experience
The self-service experience guides you through creating your product on AWS Marketplace. As you proceed through the steps, you specify product information and AMI deployment settings, such as AWS Region, instance types, and AMI details. You also configure transaction details including the pricing, country availability, EULA, and refund policy. As an option, you can specify an allowlist of AWS account IDs to access and test the product while it is in the **Limited** status.
Before you start, review the following key aspects of the self-service experience:
+ You can only go to the next step after you complete the required fields in the current step. This requirement is because there is page-level validation at the end of each step. You can't save or submit an incomplete step.
+ If you need to end your session before completing all the steps in the process, you can choose **Save and exit** to submit the steps that you completed to the staging area.
+ A step that is incomplete and doesn't pass validation isn't submitted to the system. A partially completed step isn't valid and can't be saved.
+ When you choose **Save and exit**, the **Save and exit** dialog box shows the steps that passed validation checks. You can review and choose to save up to the last completed and validated steps. If there is a validation error or missing details, you can choose **Fix it** to go back to that step.
+ After you **Save and exit**, the request is under review while it's processing. It could take a few minutes or hours to finish processing. You can't continue the steps or make changes until the request has succeeded. For the first **Save and exit**, the request is creating the product in parallel with the steps that you have completed.
+ After the request has **Succeeded**, you have completed the save. To resume changes on the **Product overview** page, choose **Resume product creation** or use **Request changes** to update the details you have previously submitted in the last session. When you resume, notice that the steps you have completed are marked with a green **Succeeded** label. To update a previously submitted step, use **Request changes**. The previous **Save and exit** request must be completed before you can continue this step.
+ When you’ve completed all the steps, you can choose **Next** to see a review. Choose **Submit** which requests that the system perform a final validation. After you receive a **Succeeded** response, the product moves to a **Limited** status. You can see on the detail page that the product is now available to anyone on the allowlist. If the request fails, the product remains in the **Staging** status and requires you to make corrections before resubmitting.
## Create the listing
The steps in this section explain how to create a listing for a single-AMI product.
**Note**
You can only go to the next step when you complete the required fields in the current step. You can't save or submit an incomplete step. If you need to end your session before completing all the steps in the process, choose **Save and exit** to submit the steps that you completed to the staging area. For more information, see [Understand the self-service experience](#understand-ami-self-service-exp).
**To create a single-AMI product**
1. Open the AWS Marketplace Management Portal at [https://aws.amazon.com/marketplace/management/tour/](https://aws.amazon.com/marketplace/management/tour/), and then sign in to your seller account.
1. From the **Products** menu, choose **Server**. Or, you can go directly to the [https://aws.amazon.com/marketplace/management/products/server](https://aws.amazon.com/marketplace/management/products/server) page.
1. From the **Server products** tab, select **Create server product**, select **Amazon Machine Image (AMI)**, and then select one of the licensing types for single-AMI products:
+ **Bring your own license (BYOL)** – A product that the user gets a license from you outside of AWS Marketplace. It can be either a paid or free license.
+ **Free** – A product that is free for your subscribers to use. (They will still pay charges for any associated Amazon Elastic Compute Cloud (Amazon EC2) instance, or other AWS resources.)
+ **Paid hourly or hourly-annual** – A product that the buyer pays for either on an hourly basis or hourly with an annual contract. AWS does the metering based on the product code on the AMI.
+ **Paid monthly** – A product that the buyer is billed for monthly by AWS.
+ **Paid usage** – Software is directly charged for the value you provide, along with one of four usage categories: users, data, bandwidth, or hosts. You can define up to 24 dimensions for the product. All charges are still incurred by the customer.
+ **AMI with contract pricing** – A Single-AMI product or Single-AMI with an CloudFormation stack that the buyer pays an upfront fee for.
1. The self-service experience guides you through the steps to create an AWS Marketplace listing. You must enter product information (metadata), product deployment details (AWS Region, instances, and AMI details), and public offer details (price, EULA, availability by country, EULA, refund). As an option, you can add accounts to the allowlist to test the product. Complete each step to move to the next step in the process.
**Note**
If you need to end your session before completing all steps in the process, you can use the **Save and exit** function to submit the steps you completed to the staging area. This creates a request for the information you provided to be validated. While the request is processing, you can't edit the product. After the request succeeds, you can continue creating your product by choosing **Resume product creation**.
A failed request means no update was made to the product because of a validation error. This will be visible on the request log for your product. You can select the request to view the error, use **Copy to new** under **Actions** to correct the error, and resubmit the request. When you resume the steps, you can continue from the step after the step that you saved in the last session. To update previous steps, go to the product overview page and submit a change request to update steps that you submitted previously.
1. After entering required information for all of the change request steps, choose **Submit**. This submittal creates a request to the AWS Marketplace catalog system to validate the information and release the product to a **Limited** state, if the validation passes. While the request is processing, you can't continue to edit the product. After the request succeeds, the product is moved to a **Limited** state.
+ When your product is initially published, it's only accessible to your AWS account (the one you used to create the product) and the AWS Marketplace Seller Operations team's test account. If you view the product from the **Server products** page, you can choose **View on AWS Marketplace** to view the product details as they will appear in AWS Marketplace for buyers. This detail listing isn't visible to other AWS Marketplace users.
+ This capability allows you to test your product (and even publish multiple versions for testing) before releasing it publicly.
1. Test your product in the **Limited** state and make sure that it follows AWS Marketplace [AMI-based product requirements](https://docs.aws.amazon.com/marketplace/latest/userguide/product-and-ami-policies.html) and the [product checklist](https://docs.aws.amazon.com/marketplace/latest/userguide/aws-marketplace-listing-checklist.html). Then, to request that your product be published to **Public**, choose **Update visibility**. The AWS Marketplace Seller Operations team must review your product before approving it to go **Public**.
**Note**
Product verification and publication is a manual process, which is handled by the AWS Marketplace Seller Operations team. It can take 7–10 business days to publish your initial product version, if there are no errors. For more details about timing, see [Timing and expectations](https://docs.aws.amazon.com/marketplace/latest/userguide/product-submission.html#timing-and-expectations).
For more information about preparing and submitting both your single-AMI product and your product information, see [Additional resources](#ami-single-create-resources).
## Additional resources
For more information about preparing your product information and submitting it for publication, see the following resources:
+ [Preparing your product for AWS Marketplace](product-preparation.md)
+ [Submitting your product for publication on AWS Marketplace](product-submission.md)
For more information about preparing your single-AMI product for submission to AWS Marketplace, see the following resources:
+ [Best practices for building AMIs for use with AWS Marketplace](best-practices-for-building-your-amis.md)
+ [AMI product checklist for AWS Marketplace](aws-marketplace-listing-checklist.md)
+ [AMI-based product requirements for AWS Marketplace](product-and-ami-policies.md)
# Add CloudFormation templates to your product
AWS Marketplace sellers can list AMI-based products that are delivered to AWS Marketplace buyers by using AWS CloudFormation templates. Adding a CloudFormation template to your AMI-based product allows your buyers to deploy your solution without having to manually configure the resources and dependencies. You can use the templates to define a cluster or distributed architecture for the products or to select different AMI combinations or product configurations. Single AMI solutions can contain a maximum of three CloudFormation templates.
The CloudFormation templates can be configured to deliver a single Amazon Machine Image (AMI) with associated configuration files and Lambda functions. Additionally, you must include an architectural diagram for each template.
**Topics**
+ [Preparing your CloudFormation template](#aws-cloudformation-template-preparation)
+ [Architectural diagram](#topology-diagram)
+ [Convert CloudFormation templates of existing products](#convert-cloudformation-templates)
+ [Adding serverless application components](cloudformation-serverless-application.md)
## Preparing your CloudFormation template
To build your CloudFormation templates, you must meet the template prerequisites and provide the required input and security parameters. When submitting your CloudFormation template, use the guidelines in the following sections.
### Template prerequisites
+ Verify that the template is launched successfully through the CloudFormation console **in all AWS Regions enabled for your product**. You can use the [TaskCat tool](https://github.com/aws-quickstart/taskcat) to test your templates.
+ AMIs included in your CloudFormation template must either be the AMI of the product you are publishing or an AWS-managed AMI such as the latest Amazon Linux 2. Don't include any community AMI or AMI owned and shared by you or any other third-party. To use an AWS-managed AMI, use [public parameters in AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-public-parameters.html) instead of hardcoding AMI IDs. For example, within your CloudFormation template where you specify the AMI ID, you use a dynamic reference `ImageId: '{{resolve:ssm:/aws/service/ecs/optimized-ami/amazon-linux-2/recommended/image_id}}'`.
+ Build templates so that they do not depend on the use in a particular Availability Zone (AZ). Not all customers have access to all AZs, and AZs are mapped differently for different accounts.
+ If you're building a clustered solution using an Auto Scaling group, we recommend that you account for a scaling event. The new node should join the running cluster automatically.
+ Even for single-node products, we recommend using an [Auto Scaling group](https://docs.aws.amazon.com/autoscaling/latest/userguide/create-asg-from-instance.html).
+ If your solution involves a cluster of multiple instances, consider using placement groups if you want low network latency, high network throughput, or both among the instances.
+ For ease of review by the AWS Marketplace team and transparency to the customer, we recommend that you add comments in your **UserData** section.
### Requirements for AMI details
**Note**
If you create an **Amazon Machine Image (AMI) or AMI with CloudFormation** on the [server products](https://aws.amazon.com//marketplace/management/products/server) page of the seller portal and are prompted to download the [product load form](https://docs.aws.amazon.com//marketplace/latest/userguide/product-submission.html#aws-cloudformation-launched-product-free-or-paid-or-usage-based-paid-ami-product), see [Requirements for AMI details using the product load form](#ami-requirements-product-load-form) instead.
When specifying the `ImageId` property of resources that deploy your AMI to EC2 instances such as [AWS::EC2::Instance](https://docs.aws.amazon.com//AWSCloudFormation/latest/UserGuide/aws-resource-ec2-instance.html), [AWS::AutoScaling::LaunchConfiguration](https://docs.aws.amazon.com//AWSCloudFormation/latest/UserGuide/aws-resource-autoscaling-launchconfiguration.html), and [AWS::EC2::LaunchTemplate](https://docs.aws.amazon.com//AWSCloudFormation/latest/UserGuide/aws-resource-ec2-launchtemplate.html) resources, you must reference a [template parameter.](https://docs.aws.amazon.com//AWSCloudFormation/latest/UserGuide/parameters-section-structure.html) The parameter type must be either a `AWS::EC2::Image::Id`, `AWS::SSM::Parameter::Value`, or `String`.
You can name this template parameter any valid parameter name. AWS Marketplace copies your template to its own Amazon S3 buckets and replaces the specified parameter with an [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com//systems-manager/latest/userguide/systems-manager-parameter-store.html) parameter. AWS Marketplace also updates the description and constraint text to make the correct value clear to buyers who are deploying the template. When buyers deploy your template, that parameter resolves to the AWS Region-specific AMI ID of your published product.
The following template examples illustrate the `ImageId` property referencing template parameters using the intrinsic function [Ref](https://docs.aws.amazon.com//AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html).
YAML example:
```
Parameters:
ImageId:
Type: AWS::EC2::Image::Id
Default: ami-example1234567890
Resources:
MyInstance:
Type: AWS::EC2::Instance
Properties:
ImageId: !Ref ImageId
```
JSON example:
```
{
"Parameters": {
"ImageId": {
"Type": "AWS::EC2::Image::Id",
"Default": "ami-example1234567890"
}
},
"Resources": {
"MyInstance": {
"Type": "AWS::EC2::Instance",
"Properties": {
"ImageId": {
"Ref": "ImageId"
}
}
}
}
}
```
If you are deploying EC2 instances inside a [nested stack](https://docs.aws.amazon.com//AWSCloudFormation/latest/UserGuide/using-cfn-nested-stacks.html) instead of the root stack, the AMI ID must dynamically inherit its value from the root stack. Edit your root and nested stacks so that in the root stack, setting the value of your template parameter overrides the AMI ID used in this nested stack.
### Requirements for AMI details using the product load form
**Note**
When you create an **Amazon Machine Image (AMI) or AMI with CloudFormation** on the [server products](https://aws.amazon.com//marketplace/management/products/server) page of the seller portal and are not immediately prompted to download the [product load form](https://docs.aws.amazon.com//marketplace/latest/userguide/product-submission.html#aws-cloudformation-launched-product-free-or-paid-or-usage-based-paid-ami-product), see [Requirements for AMI details](#ami-requirements-sse) instead.
AMIs must be in a mapping table for each Region. The AWS Marketplace team updates the AMI IDs after they're cloned. Your source AMI must be in the `us-east-1` Region. The other Regions can use placeholders.
YAML example:
```
Mappings:
RegionMap:
us-east-1:
ImageId: ami-0123456789abcdef0
us-west-1:
ImageId: ami-xxxxxxxxxxxxxxxxx
eu-west-1:
ImageId: ami-xxxxxxxxxxxxxxxxx
ap-southeast-1:
ImageId: ami-xxxxxxxxxxxxxxxxx
Resources:
EC2Instance:
Type: AWS::EC2::Instance
Properties:
ImageId: !FindInMap
- RegionMap
- !Ref AWS::Region
- ImageId
```
### Requirements for nested stack templates
**Note**
This section only applies to pricing models that do not use the [product load form](https://docs.aws.amazon.com//marketplace/latest/userguide/product-submission.html#aws-cloudformation-launched-product-free-or-paid-or-usage-based-paid-ami-product). For pricing models that *do use* the product load form, only a fixed string is allowed for the nested stack `TemplateURL` property.
If your template includes [nested stacks](https://docs.aws.amazon.com//AWSCloudFormation/latest/UserGuide/using-cfn-nested-stacks.html), the `TemplateURL` property of nested stack resources must reference the template parameters for the Amazon S3 bucket name, bucket Region, and Amazon S3 object key prefix. The parameter names for the bucket name must be `MPS3BucketName`, the bucket Region must be `MPS3BucketRegion`, and for the object key prefix must be `MPS3KeyPrefix`.
Set the default values for these parameters to correspond to your Amazon S3 bucket where your nested templates are stored. All nested templates must be publicly accessible. When you submit your template for publishing, AWS Marketplace copies your templates to its own Amazon S3 buckets and modifies the properties of those three parameters to have the default value and allowed value set to correspond with where the copies are stored. AWS Marketplace also updates the description and constraint text to make the correct values clear to buyers who are deploying the template.
If you have multiple levels of nested stacks, all nested stacks that create additional nested stacks must be configured so that the `TemplateURL` property dynamically inherits the values of the Amazon S3 bucket name, Amazon S3 bucket Region, and Amazon S3 object key from the root stack. Edit your root and nested stacks so that in the root stack, setting the value of the template parameter `MPS3BucketName`, `MPS3BucketRegion`, and `MPS3KeyPrefix` overrides their respective values in the URL used in this nested stack to create additional nested stacks.
The following template examples illustrate the `TemplateURL` property referencing template parameters using the intrinsic function [Fn::Sub](https://docs.aws.amazon.com//AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-sub.html).
YAML example:
```
AWSTemplateFormatVersion: '2010-09-09'
Metadata:
AWS::CloudFormation::Interface:
ParameterGroups:
- Label:
default: AWS Marketplace Parameters
Parameters:
- ImageId
- MPS3BucketName
- MPS3BucketRegion
- MPS3KeyPrefix
Parameters:
ImageId:
Type: AWS::EC2::Image::Id
Default: ami-example1234567890
Description: The AMI that will be used to launch EC2 resources.
MPS3BucketName:
Type: String
Default: sellerbucket
Description: Name of the S3 bucket for your copy of the nested templates.
MPS3BucketRegion:
Type: String
Default: us-east-1
Description: AWS Region where the S3 bucket for your copy of the nested templates is hosted.
MPS3KeyPrefix:
Type: String
Default: sellerproductfolder/
Description: S3 key prefix that is used to simulate a folder for your copy of the nested templates.
Resources:
EC2Instance:
Type: AWS::EC2::Instance
Properties:
ImageId: !Ref ImageId
NestedStack:
Type: AWS::CloudFormation::Stack
Properties:
TemplateURL: !Sub https://${MPS3BucketName}.s3.${MPS3BucketRegion}.${AWS::URLSuffix}/${MPS3KeyPrefix}nested-template.yaml
```
JSON example:
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Metadata": {
"AWS::CloudFormation::Interface": {
"ParameterGroups": [
{
"Label": {
"default": "AWS Marketplace Parameters"
},
"Parameters": [
"ImageId",
"MPS3BucketName",
"MPS3BucketRegion",
"MPS3KeyPrefix"
]
}
]
}
},
"Parameters": {
"ImageId": {
"Type": "AWS::EC2::Image::Id",
"Default": "ami-example1234567890",
"Description": "The AMI that will be used to launch EC2 resources."
},
"MPS3BucketName": {
"Type": "String",
"Default": "sellerbucket",
"Description": "Name of the S3 bucket for your copy of the nested templates."
},
"MPS3BucketRegion": {
"Type": "String",
"Default": "us-east-1",
"Description": "AWS Region where the S3 bucket for your copy of the nested templates is hosted."
},
"MPS3KeyPrefix": {
"Type": "String",
"Default": "sellerproductfolder/",
"Description": "S3 key prefix that is used to simulate a folder for your copy of the nested templates."
}
},
"Resources": {
"EC2Instance": {
"Type": "AWS::EC2::Instance",
"Properties": {
"ImageId": {
"Ref": "ImageId"
}
}
},
"NestedStack": {
"Type": "AWS::CloudFormation::Stack",
"Properties": {
"TemplateURL": {
"Fn::Sub": "https://${MPS3BucketName}.s3.${MPS3BucketRegion}.${AWS::URLSuffix}/${MPS3KeyPrefix}nested-template.yaml"
}
}
}
}
}
```
**Note**
[AWS::CloudFormation::Interface](https://docs.aws.amazon.com//AWSCloudFormation/latest/UserGuide/aws-resource-cloudformation-interface.html) is used to define how parameters are grouped and sorted in the AWS CloudFormation console when buyers deploy your template.
### Template input parameters
+ Input parameters to the template must not include the AWS Marketplace customer's AWS credentials (such as passwords, public keys, private keys, or certificates).
+ For sensitive input parameters such as passwords, choose the `NoEcho` property and enable stronger regular expression. For other input parameters, set the most common inputs along with appropriate helper text.
+ Use CloudFormation parameter types for inputs where available.
+ Use `AWS::CloudFormation::Interface` to group and sort input parameters.
+ Don't set any default values for the following input parameters:
**Note**
Customers must provide these as input parameters.
+ Default CIDR ranges that allow ingress into remote access ports from the public internet
+ Default CIDR ranges that allow ingress into database connection ports from the public internet
+ Default passwords for users or databases
### Network and security parameters
+ Ensure that the default SSH port (22) or RDP port (3389) isn't open to 0.0.0.0.
+ Instead of using the default virtual private cloud (VPC), we recommend that you build a VPC with appropriate access control lists (ACLs) and security groups.
+ Your template can't request long-term access keys from users or create them to access AWS resources. If your AMI application requires access to the AWS services in the buyer’s account, it must use [IAM roles for Amazon EC2](/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html).
+ Set IAM roles and policies to [grant the least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege) and enable write access only when absolutely necessary. For example, if your application needs only `S3:GET`, `PUT`, and `DELETE` operations, specify those actions only. We don't recommend the use of `S3:*` in this case.
After your template is received, AWS Marketplace validates the product configuration and information and provides feedback for any required revisions.
## Architectural diagram
You must provide an architectural diagram for each template. To learn more about diagramming, see [What is architecture diagramming?](https://aws.amazon.com/what-is/architecture-diagramming/)
The diagram must meet the following criteria:
+ Illustrate a standard deployment on AWS.
+ Depict logically where resources are deployed. For example, resources like Amazon EC2 instances are in the correct subnet.
+ Use the most current AWS product icons for each AWS service deployed through the CloudFormation template. To download the current set of architecture icons, see [AWS Architecture Icons](https://aws.amazon.com/architecture/icons/).
+ Include metadata for all the services deployed by the CloudFormation template.
+ Include all networks, VPCs, and subnets deployed by the CloudFormation template.
+ Show integration points, including third party assets, APIs and on-premises, hybrid assets.
+ Diagrams must be 1100 x 700 pixels in size. Maintain original diagram proportions without stretching or cropping.
## Convert CloudFormation templates of existing products
**Note**
This section is for sellers with an existing AMI with CloudFormation product that used the [product load form](https://docs.aws.amazon.com/marketplace/latest/userguide/product-submission.html#aws-cloudformation-launched-product-free-or-paid-or-usage-based-paid-ami-product) to publish their templates and now want to update that template without using the product load form. If you are publishing a new product, see [Preparing your CloudFormation templates](https://docs.aws.amazon.com/marketplace/latest/userguide/cloudformation.html#aws-cloudformation-template-preparation).
If you create an **Amazon Machine Image (AMI) or AMI with CloudFormation** on the [server products](https://aws.amazon.com//marketplace/management/products/server) page of the seller portal and are prompted to download the [product load form](https://docs.aws.amazon.com//marketplace/latest/userguide/product-submission.html#aws-cloudformation-launched-product-free-or-paid-or-usage-based-paid-ami-product), see [Requirements for AMI details using the product load form](#ami-requirements-product-load-form).
If you want to use the self-service experience to update an existing product that previously used the [product load form](https://docs.aws.amazon.com/marketplace/latest/userguide/product-submission.html#aws-cloudformation-launched-product-free-or-paid-or-usage-based-paid-ami-product) to publish, you must make changes to your existing CloudFormation template.
The following table describes the difference between using the product load form and the self-service experience:
****
| | Product load form | Self-service experience |
| --- | --- | --- |
| Value of ImageId property for EC2 resources | References a mapping table for your AMI ID. For more information, see [Requirements for AMI details using the product load form](#ami-requirements-product-load-form). | References a template parameter for your AMI ID. For more information, see [Requirements for AMI details](#ami-requirements-sse). |
| Value of TemplateURL property for nested stacks | Must be a fixed string and can't use intrinsic functions. | Can be dynamic by using intrinsic functions. Must reference a set of template parameters. For more information, see [Requirements for nested stack templates](#nested-stack-template-requirements) |
The following example templates illustrate an example of an existing product that used the product load form to publish the template. In this example, the AMI ID is `ami-example123456` and a nested template is in a seller’s S3 bucket at the location `https://sellerbucket.s3.us-east-1.amazonaws.com/sellerproductfolder/nested-template.yaml`.
YAML example published with the product load form:
```
AWSTemplateFormatVersion: '2010-09-09'
Mappings:
RegionMap:
us-east-1:
AMI: ami-example123456
Resources:
EC2Instance:
Type: AWS::EC2::Instance
Properties:
ImageId: !FindInMap
- RegionMap
- !Ref AWS::Region
- AMI
NestedStack:
Type: AWS::CloudFormation::Stack
Properties:
TemplateURL: https://sellerbucket.s3.us-east-1.amazonaws.com/sellerproductfolder/nested-template.yaml
```
JSON example published with the product load form:
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Mappings": {
"RegionMap": {
"us-east-1": {
"AMI": "ami-example123456"
}
}
},
"Resources": {
"EC2Instance": {
"Type": "AWS::EC2::Instance",
"Properties": {
"ImageId": {
"Fn::FindInMap": [
"RegionMap",
{
"Ref": "AWS::Region"
},
"AMI"
]
}
}
},
"NestedStack": {
"Type": "AWS::CloudFormation::Stack",
"Properties": {
"TemplateURL": "https://sellerbucket.s3.us-east-1.amazonaws.com/sellerproductfolder/nested-template.yaml"
}
}
}
}
```
The following template examples illustrate the changes required to use the self-service experience to update the product.
YAML example published with the self-service experience:
```
AWSTemplateFormatVersion: '2010-09-09'
Metadata:
AWS::CloudFormation::Interface:
ParameterGroups:
- Label:
default: AWS Marketplace Parameters
Parameters:
- ImageId
- MPS3BucketName
- MPS3BucketRegion
- MPS3KeyPrefix
Parameters:
ImageId:
Type: AWS::EC2::Image::Id
Default: ami-example123456
Description: The AMI that will be used to launch EC2 resources.
MPS3BucketName:
Type: String
Default: sellerbucket
Description: Name of the S3 bucket for your copy of the nested templates.
MPS3BucketRegion:
Type: String
Default: us-east-1
Description: AWS Region where the S3 bucket for your copy of the nested templates is hosted.
MPS3KeyPrefix:
Type: String
Default: sellerproductfolder/
Description: S3 key prefix that is used to simulate a folder for your copy of the nested templates.
Resources:
EC2Instance:
Type: AWS::EC2::Instance
Properties:
ImageId: !Ref ImageId
NestedStack:
Type: AWS::CloudFormation::Stack
Properties:
TemplateURL: !Sub https://${MPS3BucketName}.s3.${MPS3BucketRegion}.${AWS::URLSuffix}/${MPS3KeyPrefix}nested-template.yaml
```
JSON Example published with the self-service experience:
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Metadata": {
"AWS::CloudFormation::Interface": {
"ParameterGroups": [
{
"Label": {
"default": "AWS Marketplace Parameters"
},
"Parameters": [
"ImageId",
"MPS3BucketName",
"MPS3BucketRegion",
"MPS3KeyPrefix"
]
}
]
}
},
"Parameters": {
"ImageId": {
"Type": "AWS::EC2::Image::Id",
"Default": "ami-example123456",
"Description": "The AMI that will be used to launch EC2 resources."
},
"MPS3BucketName": {
"Type": "String",
"Default": "sellerbucket",
"Description": "Name of the S3 bucket for your copy of the nested templates."
},
"MPS3BucketRegion": {
"Type": "String",
"Default": "us-east-1",
"Description": "AWS Region where the S3 bucket for your copy of the nested templates is hosted."
},
"MPS3KeyPrefix": {
"Type": "String",
"Default": "sellerproductfolder/",
"Description": "S3 key prefix that is used to simulate a folder for your copy of the nested templates."
}
},
"Resources": {
"EC2Instance": {
"Type": "AWS::EC2::Instance",
"Properties": {
"ImageId": {
"Ref": "ImageId"
}
}
},
"NestedStack": {
"Type": "AWS::CloudFormation::Stack",
"Properties": {
"TemplateURL": {
"Fn::Sub": "https://${MPS3BucketName}.s3.${MPS3BucketRegion}.${AWS::URLSuffix}/${MPS3KeyPrefix}nested-template.yaml"
}
}
}
}
}
```
# Adding serverless application components
**Important**
AWS Marketplace no longer supports publishing new products with CloudFormation templates that deploy resources from AWS Serverless Application Repository. Sellers can continue to publish existing products with CloudFormation templates that deploy resources from AWS Serverless Application Repository until a future date to be announced.
You can create a product that includes an Amazon Machine Image (AMI), delivered using a AWS CloudFormation template, with serverless components incorporated into the product. For example, you can create a product with an AMI configured as a controller server and deliver it as a CloudFormation stack. The CloudFormation template used to create the stack can include the definition to set up an AWS Lambda function that is triggered by an event in the server. When you use this approach to design your product, you can simplify the architecture and make it easier for your buyers to launch. This approach can also make it easier for you to update your product. Thes following sections show you how to create and offer this type of product.
For information about creating an AMI for your product, see [AMI-based products in AWS Marketplace](ami-products.md). For information about completing AWS CloudFormation templates for your product, see [Add CloudFormation templates to your product](cloudformation.md).
When you define your serverless application, you use an AWS Serverless Application Model (AWS SAM) template that you store in the AWS Serverless Application Repository. AWS SAM is an open-source framework for building serverless applications. During deployment, AWS SAM transforms and expands the AWS Serverless Application Model syntax into CloudFormation syntax. The AWS Serverless Application Repository is a managed repository for serverless applications. It makes it possible for you to store and share reusable applications so buyers can assemble and deploy serverless architectures.
**Note**
AWS Marketplace reviews and validates your product before your listing is created. If there are issues you must resolve before the offer is listed, we will send you an email message.
As part of fulfilling a subscription, we copy the AMIs, serverless applications, and CloudFormation templates to an AWS Marketplace-owned repository in each AWS Region. When a buyer subscribes to your product, we give them access, and also notify them when you update your software.
**Topics**
+ [Step 1: Create a serverless application](#cloudformation-serverless-application-procedure-step-1)
+ [Step 2: Publish your application to the repository](#cloudformation-serverless-application-procedure-step-2)
+ [Step 3: Create the CloudFormation template](#cloudformation-serverless-application-procedure-step-3)
+ [Step 4: Submit your CloudFormation template and configuration files](#cloudformation-serverless-application-procedure-step-4)
+ [Step 5: Update your AWS Serverless Application Repository application permissions](#cloudformation-serverless-application-procedure-step-5)
+ [Step 6: Share your AMI](#cloudformation-serverless-application-procedure-step-6)
+ [Step 7: Submit your CloudFormation product with AMI and serverless application](#cloudformation-serverless-application-procedure-step-7)
## Step 1: Create a serverless application
Your first step is to package the AWS Lambda functions used to create your serverless application. Your application is a combination of Lambda functions, event sources, and other resources that work together to perform tasks. A serverless application can be as simple as one Lambda function, or it can contain multiple functions with other resources, such as APIs, databases, and event source mappings.
Use the AWS SAM to define a model for your serverless application. For descriptions of property names and types, see [AWS::Serverless::Application](https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#awsserverlessapplication) in AWSLabs on GitHub. The following is an example of an AWS SAM template with a single Lambda function and AWS Identity and Access Management (IAM) role.
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: An example of SAM template with Lambda function and IAM role
Resources:
SampleFunction:
Type: AWS::Serverless::Function
Properties:
Handler: 'com.sampleproject.SampleHandler::handleRequest'
Runtime: java8
CodeUri: 's3://amzn-s3-demo-bucket/2EXAMPLE-1234-4b12-ac37-515EXAMPLEe5-lambda.zip'
Description: Sample Lambda function
Timeout: 120
MemorySize: 1024
Role:
Fn::GetAtt: [SampleFunctionRole, Arn]
# Role to execute the Lambda function
SampleFunctionRole:
Type: "AWS::IAM::Role"
Properties:
AssumeRolePolicyDocument:
Statement:
- Effect: "Allow"
Principal:
Service:
- "lambda.amazonaws.com"
Action: "sts:AssumeRole"
ManagedPolicyArns:
- "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
Policies:
- PolicyName: SFNXDeployWorkflowDefinitionPolicy
PolicyDocument:
Statement:
- Effect: "Allow"
Action:
- "s3:Get*"
Resource: "*"
RoleName: "SampleFunctionRole"
```
## Step 2: Publish your application to the repository
To publish an application, you first upload the application code. Store your code artifacts (for example, Lambda functions, scripts, configuration files) in an Amazon S3 bucket that your account owns. When you upload your application, it's initially set to private, meaning that it's only available to the AWS account that created it. You must create an IAM policy that grants AWS Serverless Application Repository permissions to access the artifacts you uploaded.
**To publish your serverless application to the serverless application repository**
1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).
1. Choose the Amazon S3 bucket that you used to package your application.
1. Choose the **Permissions** tab.
1. Choose **Bucket Policy**.
1. Copy and paste the following example policy statement.
**Note**
The example policy statement will produce an error until values for `aws:SourceAccount` and `Resource` are updated in following steps.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "serverlessrepo.amazonaws.com"
},
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*",
"Condition" : {
"StringEquals": {
"aws:SourceAccount": "123456789012"
}
}
}
]
}
```
------
1. Replace amzn-s3-demo-bucket in the `Resource` property value with the bucket name for your bucket.
1. Replace *123456789012* in the `Condition` element with your AWS account ID. The `Condition` element ensures that the AWS Serverless Application Repository only has permission to access applications from the specified AWS account.
1. Choose **Save**.
1. Open the AWS Serverless Application Repository console at [https://console.aws.amazon.com/serverlessrepo](https://console.aws.amazon.com/serverlessrepo).
1. On the **My Applications** page, choose **Publish application**.
1. Complete the required fields and any optional field, as appropriate. The required fields are:
+ **Application name**
+ **Author**
+ **Description**
+ **Source code URL**
+ **SAM template**
1. Choose **Publish Application**.
**To publish subsequent versions of your application**
1. Open the AWS Serverless Application Repository console at [https://console.aws.amazon.com/serverlessrepo](https://console.aws.amazon.com/serverlessrepo).
1. In the navigation pane, from **My Applications**, choose the application.
1. Choose **Publish new version**.
For more information, see [Publishing serverless Applications Using the AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-template-publishing-applications.html).
## Step 3: Create the CloudFormation template
To build your CloudFormation templates, you must meet the template prerequisites and provide the required input and security parameters. For more information, see [Template anatomy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-anatomy.html) in the *AWS CloudFormation User Guide*.
In your CloudFormation template, you can reference your serverless application and your AMI. You can also use nested CloudFormation templates and reference serverless applications both in the root template and the nested templates. To reference the serverless application, you use the AWS SAM template. You can automatically generate the AWS SAM template for your application from the AWS Serverless Application Repository. The following is an example template.
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: An example root template for a SAR application
Resources:
SampleSARApplication:
Type: AWS::Serverless::Application
Properties:
Location:
ApplicationId: arn:aws:serverlessrepo:us-east-1:1234567890:applications/TestApplication
SemanticVersion: 1.0.0
SampleEC2Instance:
Type: AWS::EC2::Instance
Properties:
ImageId: "ami-79fd7eee"
KeyName: "testkey"
BlockDeviceMappings:
- DeviceName: "/dev/sdm"
Ebs:
VolumeType: "io1"
Iops: "200"
DeleteOnTermination: "false"
VolumeSize: "20"
- DeviceName: "/dev/sdk"
NoDevice: {}
```
The AWS SAM template contains the following elements:
+ `ApplicationID` – Your application's Amazon Resource Name (ARN). This information is located in the **My Applications** section of the AWS Serverless Application Repository.
+ `SemanticVersion` – The version of your serverless application. You can find this from the **My Applications** section of the AWS Serverless Application Repository.
+ `Parameter` (optional) – Application parameters.
**Note**
For `ApplicationID` and `SemanticVersion`, [intrinsic functions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html) aren't supported. You must hardcode those strings. The `ApplicationID` is updated when it's cloned by AWS Marketplace.
If you're planning to reference configuration and script files in your CloudFormation template, use the following format. For nested templates (`AWS::Cloudformation::Stack`), only `TemplateURLs` without intrinsic functions are supported. Note the `Parameters` content in the template.
```
AWSTemplateFormatVersion: '2010-09-09'
Metadata:
Name: Seller test product
Parameters:
CFTRefFilesBucket:
Type: String
Default: "seller-bucket"
CFTRefFilesBucketKeyPrefix:
Type: String
Default: "cftsolutionFolder/additionCFfiles"
Resources:
TestEc2:
Type: AWS::EC2::Instance
Metadata:
AWS::CloudFormation::Init:
addCloudAccount:
files:
/etc/cfn/set-aia-settings.sh:
source:
Fn::Sub:
- https://${CFTRefFilesBucket}.${S3Region}amazonaws.com/${CFTRefFilesBucketKeyPrefix}/sampleScript.sh
- S3Region:
!If
- GovCloudCondition
- s3-us-gov-west-1
- s3
owner: root
mode: '000700'
authentication: Amazon S3AccessCreds
..
..
..
SampleNestedStack:
Type: AWS::CloudFormation::Stack
Properties:
TemplateURL: 'https://sellerbucket.s3.amazon.com/sellerproductfolder/nestedCft.template'
Parameters:
SampleParameter: 'test'
Transform: AWS::Serverless-2016-10-31
```
## Step 4: Submit your CloudFormation template and configuration files
To submit your CloudFormation template and configuration and scripts files, grant AWS Marketplace permissions to read the Amazon S3 bucket where these files are stored. To do so, update your bucket policy to include the following permissions.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "assets.marketplace.amazonaws.com"
},
"Action": ["s3:GetObject", "s3:ListBucket"],
"Resource": ["arn:aws:s3:::amzn-s3-demo-bucket",
"arn:aws:s3:::amzn-s3-demo-bucket/*"]
}
]
}
```
------
## Step 5: Update your AWS Serverless Application Repository application permissions
To submit your AWS Serverless Application Repository application to AWS Marketplace, you must grant AWS Marketplace permissions to read your application. To do that, add permissions to a policy associated with your serverless application. There are two ways to update your application policy:
+ Go to the [AWS Serverless Application Repository](https://console.aws.amazon.com/serverlessrepo/home). Choose your serverless application from the list. Select the **Sharing** tab, and choose **Create Statement**. On the **Statement configuration** page, enter the following service principal, **assets.marketplace.amazonaws.com**, in the **Account Ids** field. Then choose **Save**.
+ Use the following AWS CLI command to update your application policy.
```
aws serverlessrepo put-application-policy \
--region region \
--application-id application-arn \
--statements Principals=assets.marketplace.amazonaws.com,Actions=Deploy
```
## Step 6: Share your AMI
All AMIs built and submitted to AWS Marketplace must adhere to all product policies. Self-service AMI scanning is available in the AWS Marketplace Management Portal. With this feature, you can initiate scans of your AMIs. You receive scanning results quickly (typically, in less than an hour) with clear feedback in a single location. After your AMI has been successfully scanned, submit the AMI for processing by the AWS Marketplace Seller Operations team by uploading your product load form.
## Step 7: Submit your CloudFormation product with AMI and serverless application
Keep the following in mind before you submit your product:
+ You must provide an architectural diagram for each template. The diagram must use the AWS product icons for each AWS service deployed through the CloudFormation template. Also, the diagram must include metadata for the services. To download our official AWS architecture icons, see [AWS Architecture Icons](https://aws.amazon.com/architecture/icons).
+ The infrastructure cost estimate for each template displayed to buyers is based on an estimate that you provide by using the [AWS Pricing Calculator](https://calculator.s3.amazonaws.com/index.html). In the estimate, include the list of services to be deployed as part of the template, along with the default values for a typical deployment.
+ Complete the product load form. You can find the product load form from the AWS Marketplace Management Portal. A different product load form is required for single AMI products and multiple AMI products. In the product load form, you will provide a public URL to your CloudFormation template. CloudFormation templates must be submitted in the form of a public URL.
+ Use the AWS Marketplace Management Portal to submit your listing. From **Assets**, choose **File upload**, attach your file, and then choose **Upload**. After we receive your template and metadata, AWS starts processing your request.
After you submit your listing, AWS Marketplace reviews and validates the product load form. Additionally, AWS Marketplace regionalizes AMIs and serverless applications, and updates the regional mapping for your CloudFormation template on your behalf. If any issues occur, the AWS Marketplace Seller Operations team will contact you by email.
# Managing AMI-based products as an AWS Marketplace seller
As an AWS Marketplace seller, you can manage and update your single [Amazon Machine Images (AMIs)](https://docs.aws.amazon.com/glossary/latest/reference/glos-chap.html#AmazonMachineImage) products. AMI-based products include a set of one or more versions of the software and metadata about the product as a whole. When you create the product, you configure its properties in AWS Marketplace, including your product name, description, and pricing. You also determine the appropriate categories for your product and add keywords so your product appears in relevant searches. After you create, your single-AMI product, you can submit change requests to make changes to your product or version.
The types of changes you can request for AMI-based products include:
+ Update product information displayed to buyers.
+ Update version information displayed to buyers.
+ Add a new version of your product.
+ Restrict a version so that new buyers can no longer access that version.
+ Update the AWS Regions that a product is available in.
+ Update the pricing and instance types for a product.
+ Remove a product from AWS Marketplace.
The following topics show to manage and update a single AMI product.
**Topics**
+ [Creating a change request for an AMI-based product in AWS Marketplace](single-ami-create-change-request.md)
+ [Updating AMI-based product visibility](ami-update-visibility.md)
+ [Adding and restricting AMI instances for AWS Marketplace](single-ami-instance-types.md)
+ [Managing versions for AMI-based products on AWS Marketplace](single-ami-versions.md)
+ [Updating AMI-based product information on AWS Marketplace](single-ami-updating-product.md)
+ [Managing AMI-based product availability by AWS Region and country](single-ami-regions.md)
+ [Updating end user license agreement (EULA) for your AMI-based AWS Marketplace product](single-ami-update-eula.md)
+ [Updating the refund policy for your AMI-based product on AWS Marketplace](single-ami-update-refund-policy.md)
+ [Giving AWS Marketplace access to your AMI](single-ami-marketplace-ami-access.md)
+ [Removing a product from AWS Marketplace](removing-products-from-aws-marketplace.md)
+ [Troubleshooting common errors for change requests on AWS Marketplace](request-errors-and-issues.md)
# Creating a change request for an AMI-based product in AWS Marketplace
To make changes to a product or version in AWS Marketplace, you submit a **change request** through the AWS Marketplace Management Portal. Change requests are added to a queue and can take from minutes to days to resolve, depending on the type of request. You can see the status of requests in the AWS Marketplace Management Portal. This topic provides the procedures that you can use to create a change request for a single-AMI product in AWS Marketplace, including the option to use the self-service experience.
You can create a change request for the following situations:
+ You saved your in-progress steps, but didn't complete the entire process, while using the self-service experience to create a single-AMI product listing. To complete the remaining steps, you create a change request.
+ You want to make modifications to the product information for your product that is in either a **Limited** or **Public** state. To update the information, you create a change request. For more information about the types of changes that you can request for AMI-based products, see [Create a change request](#single-ami-creating-change-request).
**Note**
In addition to the AWS Marketplace Management Portal, you can also create change requests by using the [AWS Marketplace Catalog API](https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/seller-products.html).
**Topics**
+ [Create a change request by using self-service](#ami-self-service-change-req)
+ [Create a change request](#single-ami-creating-change-request)
+ [Get the status of a change request](#single-ami-getting-change-request-status)
+ [Additional resources](#ami-single-change-req-resources)
## Create a change request by using self-service
To make modifications to versions or the product information, you create a *change request* in the AWS Marketplace Management Portal. Change requests are the building blocks of a self-service listing that you use to make changes to your product. Each time you select **Save and exit** from the steps or select **Submit** for any update, you are making a change request. You can find your requests on the AWS Marketplace Management Portal [Request ](https://aws.amazon.com/marketplace/management/requests) tab.
**To create a change request using self-service**
1. Open the AWS Marketplace Management Portal at [https://aws.amazon.com/marketplace/management/tour/](https://aws.amazon.com/marketplace/management/tour/), and sign in to your seller account, then go to the [https://aws.amazon.com/marketplace/management/products/server](https://aws.amazon.com/marketplace/management/products/server) page.
1. On the **Server products** tab, select the product that you want to modify.
1. Choose an option from the **Request changes** dropdown.
1. After you make a change request, there is a wait time for the system to process your request, reflected **Under Review**. When the request completes, it will result in either **Succeeded** or **Failed**.
+ After the request is submitted, it begins processing through these statuses: **Under review**, **Preparing changes**, and **Applying changes**.
+ **Succeeded** means that the requested change has been processed and changes reflect in the system.
+ **Failed** means that something went wrong with the request, so the changes were not processed. If the status is **Failed**, you can select the request to find error codes that provide recommendations on how to correct the error. At this point, you can troubleshoot the errors and create a new request for the change. To make the process faster, you can choose **Copy to new request ** to copy the details of the failed request. Then, you can make the adjustment and resubmit the request.
## Create a change request
**Important**
On June 15, 2023, AWS Marketplace will discontinue the following procedure. After June 15, 2023, use the [Create a change request by using self-service](#ami-self-service-change-req) procedure.
To make modifications to versions or the product information, you create a *change request* in the AWS Marketplace Management Portal.
**To create a change request**
1. Open the AWS Marketplace Management Portal at [https://aws.amazon.com/marketplace/management/tour/](https://aws.amazon.com/marketplace/management/tour/), and sign in to your seller account, then go to the [https://aws.amazon.com/marketplace/management/products/server](https://aws.amazon.com/marketplace/management/products/server) page.
1. On the **Server products** tab, select the product that you want to modify.
1. Choose an option from the **Request changes** dropdown list.
For most change requests, you simply fill out the form in the user interface and submit it. However, for certain changes, you must download, complete, and then upload a Product Load Form (PLF). This is a spreadsheet that contains a form for you to fill out with the required information. When you choose one of these change requests, you are prompted to download the correct PLF for the request you are attempting to create. The PLF is pre-populated with information from your existing product details. You can upload your completed PLF to the AWS Marketplace Management Portal [ File upload](https://aws.amazon.com/marketplace/management/product-load) page.
**Note**
We strongly recommend that you download and use the most recent PLF. The form is regularly updated with new information, including instance types and AWS Regions as they become available. You can find the latest PLF for a product from the **Server products** page, by selecting the product and then choosing **Download Product Load Form**.
For more information about the status of a change request, see [Get the status of a change request](#single-ami-getting-change-request-status). For insight into potential issues with change requests, see [Troubleshooting common errors for change requests on AWS Marketplace](request-errors-and-issues.md).
## Get the status of a change request
**Important**
On June 15, 2023, AWS Marketplace will discontinue the following procedure. This procedure is no longer needed for the self-service experience.
After you submit a change request, you can see the status of your request from the **Requests** tab of the [https://aws.amazon.com/marketplace/management/products/server](https://aws.amazon.com/marketplace/management/products/server) page of the AWS Marketplace Management Portal. The status could be any of the following:
+ **Under review** means that your request is being reviewed. Some requests require manual review by the AWS Marketplace team but most are reviewed automatically in the system.
+ **Succeeded** means that your request is complete. Your product or version has been updated as you requested.
+ **Action required** means that you need to update your request to fix an issue or answer a question about the request. Select the request to see the details, including any issues.
+ **Failed** means that something went wrong with the request, and you should create a new request for the change, with the same data.
## Additional resources
For more details about change requests for specific types of updates, see the following resources:
+ [Updating AMI-based product information on AWS Marketplace](single-ami-updating-product.md)
+ [Update version information](single-ami-versions.md#single-ami-updating-version)
+ [Add a new version](single-ami-versions.md#single-ami-adding-version)
+ [Restrict a version](single-ami-versions.md#single-ami-restricting-version)
# Updating AMI-based product visibility
As an AWS Marketplace seller, you can update your product visibility to change which buyers can view your single AMI product in AWS Marketplace. If the visibility status is set to **Public**, your product is visible to all AWS Marketplace buyers. If your product visibility is set to **Limited**, your product is visible only to the AWS account IDs that you allowlist. You can also manage and update this allowlist of AWS account IDs that can see your product. The following sections show you how to update your product visibility and **Limited** visibility allowlist.
**Topics**
+ [Update product visibility](#ami-update-self-service-visibility)
+ [Update the allowlist (preview accounts)](#single-ami-updating-allowlist)
## Update product visibility
To change which buyers can view your product in AWS Marketplace, you can use **Update visibility**.
**To update visibility**
1. Open the AWS Marketplace Management Portal at [https://aws.amazon.com/marketplace/management/tour/](https://aws.amazon.com/marketplace/management/tour/), and then sign in to your seller account.
1. Go to the [https://aws.amazon.com/marketplace/management/products/server](https://aws.amazon.com/marketplace/management/products/server) page, on the **Current server product** tab, select the product that you want to modify.
1. From the **Request changes** dropdown, choose **Update visibility**.
**Note**
You can request that the product be moved from a **Limited** status to a **Public** status by using this change request. However, the change request must go through an AWS Marketplace Seller Operations team approval process to be moved to **Public**.
1. Choose **Submit change request** to submit your request for review.
1. Verify that the **Requests** tab shows the **Request status** as **Under review**. When the request completes, the status becomes **Succeeded**.
## Update the allowlist (preview accounts)
To change the list of AWS account IDs that can see your product in a **Limited** state, use **Update allowlist**.
**To update the allowlist**
1. Open the AWS Marketplace Management Portal at [https://aws.amazon.com/marketplace/management/tour/](https://aws.amazon.com/marketplace/management/tour/), and then sign in to your seller account.
1. Go to the [https://aws.amazon.com/marketplace/management/products/server](https://aws.amazon.com/marketplace/management/products/server) page, and on the **Current server product** tab, select the product that you want to modify.
1. From the **Request changes** dropdown, choose **Update allowlist**. The current list is provided with the list of accounts that are currently allowlisted.
1. Add the AWS account IDs that are preferred for visibility and separate the IDs with commas.
1. Choose **Submit change request** to submit your request for review.
1. Verify that the **Requests** tab shows the **Request status** as **Under review**. When the request completes, the status becomes **Succeeded**.
# Adding and restricting AMI instances for AWS Marketplace
As an AWS Marketplace seller, you can manage which instances buyers can use for your single Amazon Machine Imagine (AMI) product. You can add a new instance for your single AMI product that buyers can use. Similarly, if you want to prevent new buyers from using your single AMI product from a specific instance, you can restrict the instance.
For more information about the Amazon EC2 instance types, see [Available instance types](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html#AvailableInstanceTypes) in the *Amazon EC2 User Guide*.
The following sections explain how to add and restrict instances.
**Topics**
+ [Adding an instance](#single-ami-adding-instance-types)
+ [Restricting an instance](#single-ami-restricting-instance-types)
## Adding an instance
You can add a new instance which buyers can use as a single-AMI.
**To add an instance**
1. Open the AWS Marketplace Management Portal at [https://aws.amazon.com/marketplace/management/tour/](https://aws.amazon.com/marketplace/management/tour/), and then sign in to your seller account.
1. Go to the [https://aws.amazon.com/marketplace/management/products/server](https://aws.amazon.com/marketplace/management/products/server) page, and on the **Current server product** tab, select the product that you want to modify.
1. From the **Request changes** dropdown, choose **Add instance**.
1. Select an instance architecture.
1. Select the instance types that you want to add from the list of available instances.
1. Choose **Submit request** to submit your request for review.
1. Verify that the **Requests** tab shows the **Request status** as **Under review**. When the request completes, the status becomes **Succeeded**.
**Note**
If your current pricing model is not free or uses a Bring Your Own License (BYOL) model, you must also add prices.
If you created an **Add instance** with a price for the new instance or **Update pricing** to increase a price, you can’t use self-service to **Add instance** in the 90 days starting from the day you made the change. To make these changes, contact the [AWS Marketplace Seller Operations team](https://aws.amazon.com/marketplace/management/contact-us/).
When you add support for a new instance type, customers already subscribed to private offers for your product won't be able to launch the newly added instance automatically. You must create another private offer with the instance you want customers to access. After accepting the new offer, customers can launch the newly added instance. Customers who subscribe to your product at a future date can also launch the instance, as long as the instance is included in the private offer. For more information about how to create a new private offer, see [Amending agreements in AWS Marketplace](private-offers-upgrades-and-renewals.md) later in this guide.
**Note**
**FPGA Instance Type Support**
Products with AFI IDs support F2 instance types only. You can offer your AMI on other instance types, however, the AFIs will not be loaded on other instance types. When buyers launch your product on non-F2 instances, the AMI will function without the FPGA acceleration capabilities provided by the AFI IDs.
## Restricting an instance
To prevent new buyers from using an instance of an AMI product, you can restrict the instance. You can add the instance back at a later time, if needed. Existing users of the single AMI on the restricted instance can continue to use the product from the Region for the length of their subscriptions.
**To restrict an instance**
1. Open the AWS Marketplace Management Portal at [https://aws.amazon.com/marketplace/management/tour/](https://aws.amazon.com/marketplace/management/tour/), and then sign in to your seller account.
1. Go to the [https://aws.amazon.com/marketplace/management/products/server](https://aws.amazon.com/marketplace/management/products/server) page, and on the **Current server product** tab, select the product that you want to modify.
1. From the **Request changes** dropdown, choose **Restrict instance**.
1. Select the instances that you want to restrict, and choose **Restrict**.
1. Choose **Submit change request** to submit your request for review.
1. Verify that the **Requests** tab shows the **Request status** as **Under review**. When the request completes, the status becomes **Succeeded**.
**Note**
If the check box is shaded, this means the instance is associated with one to several versions as a recommended instance type. To restrict such instances, use **Update versions** to choose a different recommended instance type. After the change requests complete and the instance you want to restrict is no longer a recommended instance type, you can return to **Restrict instance** to restrict your chosen instance.
# Managing versions for AMI-based products on AWS Marketplace
When you create an Amazon Machine Image (AMI) based product on AWS Marketplace, you include a specific version of your software. The lifecycle of an AMI-based product for AWS Marketplace doesn't end after you publish the first version. You should keep your product up-to-date with new versions of your software. The following sections show you how to manage your versions, which includes updating version information (such as descriptions and dates), adding new versions, and restricting access to previous versions.
**Topics**
+ [Update version information](#single-ami-updating-version)
+ [Add a new version](#single-ami-adding-version)
+ [Restrict a version](#single-ami-restricting-version)
## Update version information
After a version is created, it can be helpful to provide updated information to your buyers by modifying the information associated with the version. For example, if you plan to restrict version 1.0 after version 1.1 is released, you can update the description of version 1.0 to direct buyers to version 1.1, with the date that the version will be restricted. You update the version information from the AWS Marketplace Management Portal.
**To update version information**
1. Open the AWS Marketplace Management Portal at [https://aws.amazon.com/marketplace/management/tour/](https://aws.amazon.com/marketplace/management/tour/), and then sign in to your seller account.
1. Go to the [https://aws.amazon.com/marketplace/management/products/server](https://aws.amazon.com/marketplace/management/products/server) page, on the **Server products** tab, then select the product that you want to modify.
1. From the **Request changes** dropdown, choose **Update version information**.
1. On the **Update version** page, select the version that you want to update.
1. Update any of the following information that you need to modify:
+ **Release notes**
+ **Usage instructions**
+ **64-bit (x86) Amazon Machine Image (AMI)** – Details on usage and security group
1. Select **Submit**.
1. Verify that the request appears on the **Requests** tab with the **Under review** status.
**Note**
You can't use this procedure to update the version title, or the AMI associated with the version. Instead, [create a new version](#single-ami-adding-version) and [restrict the previous version](#single-ami-restricting-version).
You can check the status of your request at any time from the **Requests** tab of the [ Server Products](https://aws.amazon.com/marketplace/management/products/server) page. For more information, see [Get the status of a change request](single-ami-create-change-request.md#single-ami-getting-change-request-status).
## Add a new version
You can add a new version of your product when you make changes to the product, the base image, or any other time you need to modify the AMI for the product. Add a new version of your product from the AWS Marketplace Management Portal.
**Note**
For information about creating an AMI for AWS Marketplace, see [Best practices for building AMIs for use with AWS Marketplace](best-practices-for-building-your-amis.md).
**To add a new version**
1. Open the AWS Marketplace Management Portal at [https://aws.amazon.com/marketplace/management/tour/](https://aws.amazon.com/marketplace/management/tour/), and then sign in to your seller account.
1. Go to the [https://aws.amazon.com/marketplace/management/products/server](https://aws.amazon.com/marketplace/management/products/server) page, on the **Current server product** tab, then select the product that you want to modify.
1. From the **Request changes** dropdown, choose **Add new version**. The **Add a new version** form appears, populated with the information from your most recent version.
**Note**
You can also choose **Test 'Add version'** to scan your AMI and CloudFormation template(s) without adding a new version. For more information, refer to [ Scanning your AMI for publishing requirements ](https://docs.aws.amazon.com/marketplace/latest/userguide/best-practices-for-building-your-amis.html#self-service-scanning) .
1. In the **Version information** section, provide the following information:
+ **Version title** – Enter a valid string (for example *1.1* or *Version 2.0*). It must be unique across the product.
+ **Release notes** – Enter text to describe details about this version.
1. In the **Delivery options** section, select how the buyer can deploy the solution, either AMI (standalone), AMI with CloudFormation, or both. You can choose up to three AMI with CloudFormation delivery options.
**Note**
New delivery options can't be added to an existing version. All delivery options for a single version must be submitted in the same request.
1. In the **Amazon Machine Image (AMI)** section, provide the following information:
+ **Amazon Machine Image ID** – Enter the AMI ID for the AMI that you want to use for this version. You can find the AMI ID from the [ list of AMIs in the console](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#Images:sort=name). The AMI must exist in the US East (N. Virginia) Region, and in your AWS Marketplace Seller account. The snapshot associated with this AMI can't be encrypted.
+ **IAM access role ARN** – Enter the Amazon Resource Name (ARN) for an AWS Identity and Access Management (IAM) role that allows AWS Marketplace to gain access to your AMI. For instructions on how to create the IAM role, see [Giving AWS Marketplace access to your AMI](single-ami-marketplace-ami-access.md). Use the standard format for an IAM ARN, for example: *arn:aws:iam::123456789012:role/RoleName*. The ARN must exist in your AWS Marketplace Seller account.
+ **Operating system (OS)** – Enter the base operating system for your AMI.
+ **OS version** – Enter which version of the operating system that your AMI is using.
+ **OS user name** – For Linux-based AMIs, enter the name of a user that can be used to sign into the instance. We recommend using *ec2-user*.
+ **Scanning port** – Enter the port number that can be used to log into the operating system: the SSH port for a Linux AMI or the RDP port for a Windows AMI.
+ **Amazon FPGA Image (AFI) IDs ** (Optional) – Enter the AFI IDs to associate with your AMI. AFIs only support F2 instance types. You can offer your AMI on other instance types, however, the AFIs will not be loaded in those cases. You can add up to 15 AFI IDs using the **Add AFI ID** button. This option is not available when using CloudFormation templates. All AFI IDs you provide must originate from the US East (N. Virginia) region, reside within your AWS Marketplace seller account, and the provided IAM access role should have permissions to share this AFI with AWS Marketplace.For more details on the required permissions, see [Giving AWS Marketplace access to your FPGA images](https://docs.aws.amazon.com/marketplace/latest/userguide/single-ami-marketplace-ami-access.html#single-ami-marketplace-afi-access).
1. Provide the following configurations for the **AMI delivery option** section, if applicable:
+ **Recommended instance type**– Choose the instance type that buyers get by default.
+ **Usage instructions** – Enter instructions for using the AMI or a link to more information about using the AMI. For example: *To get started with the product, navigate to https://example.com/usage.htm.*
+ **Endpoint URL** – Provide information about how the buyer can access the software after they create an instance. Enter the **Protocol** (*https* or *http*), the **Relative URL** (for example, */index.html*), and the **Port** (for example, *443*) that buyers can use to access your product. (The host name depends on the EC2 instance, so you only need to provide the relative path).
+ **Security group recommendations** – Enter the information for one or more recommendations, including the protocol (*TCP* or *UDP*), range of ports to allow, and list of IPv4 CIDR IPs (in the form *xxx.xxx.xxx.xxx/nn*, for example, *192.0.2.0/24*).
1. Provide the following configuration settings for the **AMI with CloudFormation delivery option**, if applicable:
+ **Delivery option title** – This is a unique name to identify this Single AMI CloudFormation template delivery option.
+ **Short Description** – A brief description of the CloudFormation template.
+ **Long Description** – A detailed description of the CloudFormation template.
+ **Recommended Instance type** – The instance type, buyers get by default.
+ **Usage instructions** – Instructions for using the solution or a link to more information about using the solution.
+ **CloudFormation template link** – The URL to the location of your CloudFormation template in Amazon S3. For nested stacks or templates, provide the entry point, or parent, template. The Amazon S3 bucket that your file resides must be publicly accessible. For more information, see [Add CloudFormation templates to your product](https://docs.aws.amazon.com//marketplace/latest/userguide/cloudformation.html).
+ **AMI parameter name** – Add the name of the parameter in the CloudFormation template that the EC2 instance resources in your template are referencing for their `ImageId` property value. AWS Marketplace replaces the specified parameter with an [AWS Systems Manager Parameter Store ](https://docs.aws.amazon.com//systems-manager/latest/userguide/systems-manager-parameter-store.html)parameter. When buyers deploy your template, that parameter resolves to the AWS Region-specific AMI ID of your published product. For more information, see [Requirements for AMI details](https://docs.aws.amazon.com//marketplace/latest/userguide/cloudformation.html#ami-requirements-sse).
+ **Architecture diagram link** – The URL to the location of your architectural diagram in Amazon S3. The max image file must be 1560x878 or 1560x3120 pixels in size with a 16:9 or 1:2 ratio. The Amazon S3 bucket that your image file resides must be publicly accessible. For diagram requirements, see [Architectural diagram](https://docs.aws.amazon.com//marketplace/latest/userguide/cloudformation.html#topology-diagram).
1. Select **Submit** to submit the request to add your new version.
**Note**
Adding a new version results in a scanning of the AMI. For more information, refer to [ Scanning your AMI for publishing requirements](https://docs.aws.amazon.com/marketplace/latest/userguide/best-practices-for-building-your-amis.html#self-service-scanning).
**Note**
**AFI ID Support in New Versions**
When adding new AMI versions, AFI IDs can be configured if you select the AMI (standalone) delivery method. The same validation rules that apply during product creation also apply when adding new versions, including character restrictions, uniqueness requirements, regional constraints, and account ownership verification. Once a version is created with AFI IDs, those AFI IDs become immutable and cannot be edited later. If you need to modify AFI IDs, you must create a new version with the updated configuration. New versions with AFI IDs can coexist alongside existing versions that also have AFI IDs, allowing you to maintain multiple FPGA configurations across different product versions. During version preparation, AWS Marketplace creates regional AFI clones to ensure your product is available across supported AWS Regions, streamlining the deployment process for your buyers. This process is handled by the AWS Marketplace Seller Operations team and can take longer than other AMI Add Version requests. During this time, your the request will be 'Under Review'.
1. Verify that the request appears on the **Requests** tab with the **Under review** status. If there are errors to fix, the page displays the errors in a table at the top of the page, and the specific fields that need to be updated display in red.
You can check the status of your request at any time from the **Requests** tab of the [https://aws.amazon.com/marketplace/management/products/server](https://aws.amazon.com/marketplace/management/products/server) page. The new version will be reviewed and, if successful, published as a new public version of your product. If there is an issue, the status might be **Action required**. Select the request to see details, including any issues.
If your request is successful, your existing users receive the following email message. The message notifies them that the new version is available, links to the version's release notes, and suggests that they upgrade to the latest version. As the AWS account root user, you also receive a copy of the email message in the email account that's associated with your AWS account.
```
Greetings from AWS Marketplace,
Thank you for subscribing to
We are writing to inform you that has added a new version to on AWS Marketplace.
As an existing customer, your subscription to the product, any running instances and access to previous versions
are unaffected. However, does recommend you to update to the latest version, /
by visiting .
For additional questions or upgrade information, please contact directly. Click here
to visit the seller’s profile page on AWS Marketplace.
Release notes for /:
Thank you,
The AWS Marketplace Team
https://aws.amazon.com/marketplace
AWS, Inc. is a subsidiary of Amazon.com, Inc. Amazon.com is a registered trademark of Amazon.com, Inc.
This message was produced and distributed by AWS Inc., 410 Terry Ave. North, Seattle, WA 98109-5210
```
## Restrict a version
If you want to prevent buyers from accessing a specific version of your public product, you can restrict that version.
**Note**
All subscribers can use the current version regardless of the restriction status. AWS Marketplace guidelines require that you continue to offer support to existing buyers for 90 days after restricting the version. Your AMI will be marked as deprecated after the version is restricted. For more information, see [Deprecate an AMI](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ami-deprecate.html) in the *Amazon Elastic Compute Cloud User Guide for Windows Instances*.
**To restrict a version**
1. Open the AWS Marketplace Management Portal at [https://aws.amazon.com/marketplace/management/tour/](https://aws.amazon.com/marketplace/management/tour/), and then sign in to your seller account.
1. Go to the [https://aws.amazon.com/marketplace/management/products/server](https://aws.amazon.com/marketplace/management/products/server) page, on the **Current server product** tab, then select the product that you want to modify.
1. From the **Request changes** dropdown, choose **Restrict version**.
1. On the **Restrict version** page, select the version (or versions) that you want to restrict.
1. Select **Submit** to submit your request for review.
1. Verify that the **Requests** tab shows the **Request status** as **Under review**. When the request completes, the status is **Succeeded**.
**Note**
You can't restrict all versions of a product. If you try to restrict the last remaining public version of a product, you will receive an error. To completely remove a product, see [Removing a product from AWS Marketplace](removing-products-from-aws-marketplace.md).
You can check the status of your request at any time from the **Requests** tab of the [https://aws.amazon.com/marketplace/management/products/server](https://aws.amazon.com/marketplace/management/products/server) page. For more information, see [Get the status of a change request](single-ami-create-change-request.md#single-ami-getting-change-request-status).
**Note**
Restricting a version can take up to 3 days to complete.
If your request is successful, your existing users receive the following email message that notifies them of the version restriction and suggests they use the most recent version available. As the AWS account root user, you also receive a copy of the email message in the email account that's associated with your AWS account.
```
Greetings from AWS Marketplace,
Thank you for subscribing to .
We are writing to inform you that, as of , will no longer offer version(s) "" to new subscribers. Your use and subscription is unaffected for this version(s), however it is recommended that users upgrade to the latest version on AWS Marketplace.
For additional questions or upgrade information, please contact directly. Click here to visit the seller’s profile page on AWS Marketplace.
Thank you,
The AWS Marketplace Team
https://aws.amazon.com/marketplace
AWS, Inc. is a subsidiary of Amazon.com, Inc. Amazon.com is a registered trademark of Amazon.com, Inc. This message was produced and distributed by AWS Inc., 410 Terry Ave. North, Seattle, WA 98109-5210
```
# Updating AMI-based product information on AWS Marketplace
After you create your single Amazon Machine Image (AMI) product, you can change some of the information associated with it in AWS Marketplace. For example, if a new version modifies the description or highlights of the product, you can edit the product information with the new data. You can also update other product information, including product title, SKU description, categories, keywords, and others. For more information, see the following procedure.
**To update product information**
1. Open the AWS Marketplace Management Portal at [https://aws.amazon.com/marketplace/management/tour/](https://aws.amazon.com/marketplace/management/tour/), and then sign in to your seller account.
1. Go to the [https://aws.amazon.com/marketplace/management/products/server](https://aws.amazon.com/marketplace/management/products/server) page, and on the **Server products** tab, select the product that you want to modify.
1. From the **Request changes** dropdown, choose **Update product information**.
1. Update any of the following fields that you need to change:
+ **Product title**
+ **SKU**
+ **Short description**
+ **Long description**
+ **Product logo image URL**
+ **Highlights**
+ **Product categories**
+ **Keywords**
+ **Product video URL**
+ **Resources**
+ **Support information**
**Note**
For details about the logo format, see [Company and product logo requirements](product-submission.md#seller-and-product-logos).
1. Select **Submit**.
1. Verify that the request appears on the **Requests** tab with the **Under review** status. You might need to refresh the page to see the request on the list.
You can check the status of your request at any time from the **Requests** tab of the [ Server Products](https://aws.amazon.com/marketplace/management/products/server) page. For more information, see [Get the status of a change request](single-ami-create-change-request.md#single-ami-getting-change-request-status).
# Managing AMI-based product availability by AWS Region and country
When you create a product in AWS Marketplace, you choose the AWS Regions where it is available. You also choose the countries where buyers can purchase your product from. These two properties are similar, but they are not the same. For example, a buyer might be located in, and purchasing from, the United States, but they might be planning to install your product in the Europe (Frankfurt) Region. In order for this buyer to purchase your product, you must include both the United States in your list of countries, and the Europe (Frankfurt) Region in your list of Regions. You can use the following sections to update your product availability by Region and country.
**Topics**
+ [Add an AWS Region](#single-ami-adding-regions)
+ [Restrict an AWS Region](#single-ami-restricting-regions)
+ [Update support for future AWS Regions](#single-ami-updating-future-region-support)
+ [Update availability by country](#single-ami-update-availability-by-country)
## Add an AWS Region
You can add a Region where buyers can use your product.
**To add a Region**
1. Open the AWS Marketplace Management Portal at [https://aws.amazon.com/marketplace/management/tour/](https://aws.amazon.com/marketplace/management/tour/), and then sign in to your seller account.
1. Go to the [https://aws.amazon.com/marketplace/management/products/server](https://aws.amazon.com/marketplace/management/products/server) page, and on the **Current server product** tab, select the product that you want to modify.
1. From the **Request changes** dropdown, choose **Add Region**.
1. Select the Region that you want to add from the list of available Regions.
1. Choose **Submit request** to submit your request for review.
1. Verify that the **Requests** tab shows the **Request status** as **Under review**. When the request completes, the status becomes **Succeeded**.
**Note**
When you add support for a new AWS Region, customers already subscribed to private offers for your product won't be able to access the newly added Region automatically. You must create another private offer with the Region you want customers to access. After accepting the new offer, customers can access the newly added Region. Customers who subscribe to your product at a future date can also access the Region, as long as the Region is included in the private offer. For more information about how to create a new private offer, see [Private offer upgrades, renewals, and amendments](https://docs.aws.amazon.com/marketplace/latest/userguide/private-offers-upgrades-and-renewals.html).
**Note**
**FPGA Regional Requirements**
When adding regions to FPGA products, regional AFI clones are automatically created by AWS Marketplace to ensure your product is available across supported AWS Regions. This process ensures that buyers can deploy your FPGA-accelerated product in their preferred Region without requiring manual AFI replication. The automatic cloning process maintains consistency across all regions where your product is available.
## Restrict an AWS Region
To prevent new buyers from using your product in a specific AWS Region, you can restrict the Region. You can add the Region back at a later time. Existing subscribers of the product in the Region can continue using the product from the Region as long as they're subscribed.
**To restrict a Region**
1. Open the AWS Marketplace Management Portal at [https://aws.amazon.com/marketplace/management/tour/](https://aws.amazon.com/marketplace/management/tour/), and then sign in to your seller account.
1. Go to the [https://aws.amazon.com/marketplace/management/products/server](https://aws.amazon.com/marketplace/management/products/server) page, and on the **Current server product** tab, select the product that you want to modify.
1. From the **Request changes** dropdown, choose **Restrict Region**.
1. Select the dropdown menu to view the list of Regions in which your product is currently available.
1. Select the Regions that you want to restrict.
1. The Regions you have selected appear as tokens. Review the list of Regions that you're restricting, and enter X for Regions that you don't want to restrict.
1. Choose **Submit change request** to submit your request for review.
1. Verify that the **Requests** tab shows the **Request status** as **Under review**. When the request completes, the status becomes **Succeeded**.
If your request is successful, your existing users receive the following email message notifying them of the Region to be restricted. They can continue using your product as long as they remain subscribed, but they can’t re-subscribe if they cancel the subscription.
```
Greetings from AWS Marketplace,
This message is a notification detailing a recent change for .
{{{sellerName}}} has opted to restrict the product in beginning .
This impacts you in the following ways:
1. As long as you're subscribed to the product, you can continue using the software product in the restricted Region.
2. You can't begin new instances of the software product in the restricted Region.
3. You can continue using the software product in all available AWS Regions.
Regards,
The AWS Marketplace Team
AWS, Inc. is a subsidiary of Amazon.com, Inc. Amazon.com (http://amazon.com/) is a registered
trademark of Amazon.com, Inc. This message was produced and distributed by Amazon Web
Services Inc., 410 Terry Ave. North, Seattle, WA 98109-5210.
```
## Update support for future AWS Regions
If you want your product to be onboarded to newly launched AWS Regions, you can use **Update future Region support**.
**To update future Region support**
1. Open the AWS Marketplace Management Portal at [https://aws.amazon.com/marketplace/management/tour/](https://aws.amazon.com/marketplace/management/tour/), and then sign in to your seller account.
1. Go to the [https://aws.amazon.com/marketplace/management/products/server](https://aws.amazon.com/marketplace/management/products/server) page, and on the **Current server product** tab, select the product that you want to modify.
1. From the **Request changes** dropdown, choose **Update future Region support**.
1. You can choose to activate future Region support to allow AWS Marketplace to onboard your product to newly launched AWS Regions on your behalf.
1. After activating the feature, you can choose between all future Regions or limit to US Regions only.
1. Choose **Submit change request** to submit your request for review.
1. Verify that the **Requests** tab shows the **Request status** as** Under review**. When the request completes, the status becomes **Succeeded**.
## Update availability by country
If you want to change the countries in which your product can be subscribed to and offered, you can use **Update availability**.
**To update availability by country**
1. Open the AWS Marketplace Management Portal at [https://aws.amazon.com/marketplace/management/tour/](https://aws.amazon.com/marketplace/management/tour/), and then sign in to your seller account.
1. Go to the [https://aws.amazon.com/marketplace/management/products/server](https://aws.amazon.com/marketplace/management/products/server) page, on the **Current server product** tab, then select the product that you want to modify.
1. From the **Request changes** dropdown, choose **Update availability**.
1. Choose one of the following options:
1. **All countries** – Available in all supported countries.
1. **All countries with exclusions** – Available in all supported countries except in selected countries.
1. **Custom list** – Specific list of countries where the product is available.
1. Choose **Submit change request** to submit your request for review.
1. Verify that the **Requests** tab shows the **Request status** as **Under review**. When the request completes, the status becomes **Succeeded**.
# Updating end user license agreement (EULA) for your AMI-based AWS Marketplace product
As an AWS Marketplace seller, you can update the end user license agreement (EULA) that will govern the use of your single Amazon Machine Image (AMI) product. Your EULA is located on the product listing page for public software listings on AWS Marketplace. You can either apply your own EULA or use the [Standard Contract for AWS Marketplace (SCMP)](standardized-license-terms.md). The following procedure shows you how to update the EULA for your single-AMI product.
For more information about the EULA, see [Using standardized contracts in AWS Marketplace](standardized-license-terms.md).
**To update a EULA**
1. Open the AWS Marketplace Management Portal at [https://aws.amazon.com/marketplace/management/tour/](https://aws.amazon.com/marketplace/management/tour/), and then sign in to your seller account.
1. Choose the [https://aws.amazon.com/marketplace/management/products/server](https://aws.amazon.com/marketplace/management/products/server) tab, on the **Current server product** tab, select the product that you want to modify.
1. From the **Request changes** dropdown, choose **Update end-user license agreement**.
1. You can select the [Standard Contract for AWS Marketplace (SCMP) ](https://docs.aws.amazon.com/marketplace/latest/userguide/standardized-license-terms.html) or submit your own custom EULA. For a custom EULA, you must provide the URL for your custom contract from an Amazon S3 bucket.
**Note**
Public accessibility must be enabled on your Amazon S3 bucket.
1. Choose **Submit change request** to submit your request for review.
1. Verify that the **Requests** tab shows the **Request status** as **Under review**. When the request completes, the status becomes **Succeeded**.
# Updating the refund policy for your AMI-based product on AWS Marketplace
As an AWS Marketplace seller, you can set the refund policy for your single Amazon Machine Image (AMI) product. If you want to change the refund policy for your product, you can use **Update refund policy**. The following procedure shows you how to update your refund policy.
**To update the refund policy**
1. Open the AWS Marketplace Management Portal at [https://aws.amazon.com/marketplace/management/tour/](https://aws.amazon.com/marketplace/management/tour/), and then sign in to your seller account.
1. Go to the [https://aws.amazon.com/marketplace/management/products/server](https://aws.amazon.com/marketplace/management/products/server) page, on the **Current server product** tab, then select the product that you want to modify.
1. From the **Request changes** dropdown, choose **Update refund policy**.
1. The current refund policy details are provided in the text box for you to edit. Submitting the request overwrites the current refund policy.
1. Choose **Submit change request** to submit your request for review.
1. Verify that the **Requests** tab shows the **Request status** as **Under review**. When the request completes, the status becomes **Succeeded**.
# Giving AWS Marketplace access to your AMI
When you create a request that includes adding a new Amazon Machine Image (AMI) to AWS Marketplace, the AMI must be copied into the AWS Marketplace system and then scanned for security issues. You must give AWS Marketplace access to the AMI by creating an AWS Identity and Access Management (IAM) role with permissions to perform actions on your AMI and a trust policy that allows AWS Marketplace to assume the role. You only need to create the IAM role once. The following procedure shows you how to create a role for AWS Marketplace assets ingestion that gives AWS Marketplace access to your AMI.
**To create a role for AWS Marketplace AMI assets ingestion**
1. Sign in to the AWS Management Console, open the IAM console and go to the [Roles page](https://console.aws.amazon.com/iam/home?region=us-east-1#/roles).
1. Select **Create role**.
1. On the **Create role** page, make the following selections:
+ **Select type of trusted entity** – Choose **AWS Service**.
+ **Choose a use case** – Choose **AWS Marketplace**.
+ **Select your use case** – Choose **Marketplace – AMI Assets Ingestion**.
+ To move to the next page, select **Next: Permissions**.
1. Select the **AWSMarketplaceAmiIngestion** policy. Add a permissions boundary if required, and then select **Next: Tags** to continue.
**Note**
You can use permissions boundaries to limit the access that you give AWS Marketplace with this role. For more information, see [Permissions boundaries for IAM entities](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) in the *AWS Identity and Access Management User Guide*.
1. To continue, select **Next: Review**.
1. Provide a name for the role, and select **Create role**.
1. You should see "The role *rolename* has been created" at the top of the page, and the role should appear in the list of roles.
On this page, when you select the role that you just created, you can see its ARN in the form *arn:aws:iam::123456789012:role/exampleRole*. Use the ARN for the **IAM access role ARN** when you create change requests, for example, when [adding a new version](single-ami-versions.md#single-ami-adding-version) to your product.
## Giving AWS Marketplace access to your FPGA images
If your AMI includes FPGA images (AFIs), you must also grant AWS Marketplace additional permissions to access and manage these FPGA images. In addition to the **AWSMarketplaceAmiIngestion** policy, you need to create an inline policy that allows AWS Marketplace to perform actions on your FPGA images.
**To add FPGA image permissions to your AWS Marketplace AMI assets ingestion role**
1. Sign in to the AWS Management Console, open the IAM console and go to the [Roles page](https://console.aws.amazon.com/iam/home?region=us-east-1#/roles).
1. Select the role that you created for AWS Marketplace AMI assets ingestion.
1. On the role details page, select the **Permissions** tab, and then select **Add inline policy**.
1. Select the **JSON** tab and enter the following policy:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ec2:DescribeFpgaImages",
"ec2:DescribeFpgaImageAttribute",
"ec2:CopyFpgaImage",
"ec2:ModifyFpgaImageAttribute"
],
"Resource":"*"
}
]
}
```
------
1. Select **Review policy**.
1. Provide a name for the policy, such as **AWSMarketplaceAfiIngestion**, and then select **Create policy**.
After you add this inline policy, AWS Marketplace will have the necessary permissions to access and manage your FPGA images during the ingestion and scanning process.
# Removing a product from AWS Marketplace
After you publish your product, you can remove it from AWS Marketplace. This is also referred to as *sunsetting*. To remove a product, identify the product and submit a request to remove it, along with a reason for removal and a contact email address for you. You can also provide a replacement product ID if you're replacing the current product with a new one.
After you request product removal, new customers can't subscribe to the product. You must support any existing customers for a minimum of 90 days.
**Note**
You can't delete restricted products from the AWS Marketplace Management Portal. The portal retains them as part of the account's publication history.
We process requests for product removal from AWS Marketplace with the following conditions:
+ The product is removed from AWS Marketplace search, browse, and other discovery tools. Any **Subscribe** button or functionality is disabled, and messaging on the page clearly indicates the product is no longer available. The product detail page is still accessible using the URL and might be indexed in public search engines.
+ A reason for removal must be specified (for example, end of support, end of product updates, or replacement product). For the requirements for continuing support for removed products, see [ Terms and Conditions for AWS Marketplace Sellers](https://aws.amazon.com/marketplace/management/terms).
+ AWS Marketplace contacts current buyers through an email message informing them of the product removal, reasons for the removal, and to provide seller contact information.
+ Current buyers *do* retain access to the software until they cancel their subscription. They aren't affected in any way by the product's removal.
**To remove a product created using the AWS Marketplace Management Portal**
1. Open the AWS Marketplace Management Portal at [https://aws.amazon.com/marketplace/management/tour/](https://aws.amazon.com/marketplace/management/tour/), and then sign in to your seller account.
1. Choose the **Products** tab, and then choose **Server**.
1. On your product page, under **Server products**, locate the product that you want to remove. From the **Request changes** dropdown list, choose **Update product visibility**.
1. On the **Update product visibility** page, select **Restricted**.
1. (Optional) Provide a **Replacement Product ID**, if there is another product that will take the place of the product you are removing.
1. Review the information for accuracy, and then choose **Submit**.
A **What’s next** informational page displays after you submit the product removal request. The AWS Marketplace Seller Operations reviews and processes your request. Check the status of your submission by viewing **Requests**.
After your product is removed, the product appears in the **Current Products** list in the AWS Marketplace Management Portal. In **Current Products**, the only action that you can perform is downloading the spreadsheet for the product. You can't edit or submit another sunset request.
If you have questions about product removals, contact the [AWS Marketplace Seller Operations](https://aws.amazon.com/marketplace/management/contact-us/) team.
# Troubleshooting common errors for change requests on AWS Marketplace
When you make changes to your product's information on AWS Marketplace, you might run into errors. This topic explains some common errors and provides suggestions for how to fix them.
+ **Scanning your AMI** – Several issues could happen when scanning your AMI:
+ You have not granted AWS Marketplace permissions to scan your AMI. Grant AWS Marketplace permissions to access it. Or you have granted permissions, but the permissions boundary is too restrictive. For more information, see [Giving AWS Marketplace access to your AMI](single-ami-marketplace-ami-access.md).
+ If scanning finds security issues or Common Vulnerabilities and Exposures (CVEs) in your AMI, make sure you're using the latest patches for the operating system in your image. For more information, see [AMI-based product requirements for AWS Marketplace](product-and-ami-policies.md).
For general guidelines about building an AMI, see [Best practices for building AMIs for use with AWS Marketplace](best-practices-for-building-your-amis.md).
+ **AWS Marketplace Management Portal fields** – Some fields in the AWS Marketplace Management Portal require very specific information:
+ If you are unsure about what the field is requesting, try checking the details in the console. Most fields have text descriptions above the field, and formatting requirements below the field.
+ If you try to submit a form with one or more invalid fields, a list of issues is shown. A recommended action is provided to help you fix the issue.
+ If you're asked to provide an ARN, you will typically find it elsewhere in the console. For example, the ARN for the IAM role that you created to give AWS Marketplace access to your AMI is found on the [ Roles page](https://console.aws.amazon.com/iam/home?region=us-east-1#/roles) in the IAM console. ARNs all have a similar format. For example, an IAM role ARN is in the form *arn:aws:iam::123456789012:role/exampleRole*.
+ Your logos and videos must be provided as a URL directly to the content. For more information about logo formats, see [Company and product logo requirements](product-submission.md#seller-and-product-logos).
For more information about submitting products and version change requests, see [Submitting your product for publication on AWS Marketplace](product-submission.md).
+ **Product Load Form (PLF) issues** – PLFs contain instructions that are included in the spreadsheet. Overall instructions are provided in the Instructions table. Each field has instructions for how to fill it out—select the field to reveal the instructions.
+ **Request in Progress** – Some requests can't happen in parallel. You can only have one request to update specific information in progress for a product at a time. You can see all of your requests still under review on the **Requests** tab of the **Server products** page in AWS Marketplace Management Portal. If you have a pending request that you did not intend, you can cancel it and then submit a new request with the change that you want to make.
+ You can't update version information when an update (to add or restrict) a version is ongoing.
+ If there is a request pending from the AWS Marketplace Seller Operations team, you can't submit any new changes.
+ **Unexplained error** – If your submission fails with no explanation, try again. Occasionally, server load causes a submission to fail.
If you're still having problems with a change request, contact the [AWS Marketplace Seller Operations](https://aws.amazon.com/marketplace/management/contact-us/) team.
# Best practices for building AMIs for use with AWS Marketplace
This topic provides best practices and references to help you build Amazon Machine Images (AMIs) for use with AWS Marketplace. AMIs built and submitted to AWS Marketplace must adhere to all AWS Marketplace product policies. For more information, see the following sections.
**Topics**
+ [Securing resell rights](#rights)
+ [Building an AMI](#building-an-ami)
+ [Preparing and securing your AMI for AWS Marketplace](#securing-an-ami)
+ [Scanning your AMI for publishing requirements](#self-service-scanning)
+ [Verifying your software is running on your AWS Marketplace AMI](#verifying-ami-runtime)
## Securing resell rights
For non-free Linux distributions, you are responsible for securing resell rights for them with the exception of AWS-provided Amazon Linux, RHEL and SUSE. You don’t need to secure resell rights for Windows AMIs.
## Building an AMI
Use the following guidelines for building AMIs:
+ Ensure that your AMI meets all[AWS Marketplace policies](https://docs.aws.amazon.com/marketplace/latest/userguide/product-and-ami-policies.html).
+ Create your AMI in the US East (N. Virginia) Region.
+ Create products from existing, well-maintained AMIs backed by Amazon Elastic Block Store (Amazon EBS) with a clearly defined lifecycle provided by trusted, reputable sources such as AWS Marketplace.
+ Build AMIs using the most up-to-date operating systems, packages, and software.
+ Ensure that your AMI is based on a public Amazon EC2 AMI, that uses hardware virtual machine (HVM) virtualization and 64-bit architecture.
+ Develop a repeatable process for building, updating, and republishing AMIs.
+ Use a consistent operating system (OS) user name across all versions and products. The recommended default user names are `ec2-user` for Linux and other Unix-like systems, and `Administrator` for Windows.
+ Before submitting a final AMI to AWS Marketplace publishing, launch and test an instance from your AMI to verify the intended end-user experience. Test all installation methods, features, and performance on this instance.
+ Check port settings as follows:
+ As a [best practice security configuration](https://aws.amazon.com/blogs/security/defense-in-depth-open-firewalls-reverse-proxies-ssrf-vulnerabilities-ec2-instance-metadata-service/) against open firewalls, reverse proxies, and SSRF vulnerabilities, the **IMDS support** option must be set to **IMDSv2** only. The following CLI can be used when registering a new AMI at the final build phase:
+ `aws ec2 register-image --name my-image --root-device-name /dev/xvda --block-device-mappings DeviceName=/dev/xvda,Ebs={SnapshotId=snap-0123456789example} --architecture x86_64 --imds-support v2.0`
For more information about creating an AMI, see the following resources:
+ [Create an Amazon EBS-backed AMI](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/creating-an-ami-ebs.html) in the *Amazon EC2 User Guide*
+ [Create an Amazon EC2 AMI using Windows Sysprep](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ami-create-win-sysprep.html) in the *Amazon EC2 User Guide*
+ [How do I create an Amazon Machine Image (AMI) from an EBS-backed instance?](https://aws.amazon.com/premiumsupport/knowledge-center/create-ami-ebs-backed/)
+ [Amazon Linux AMI](https://aws.amazon.com/amazon-linux-ami/)
+ [Amazon EC2 Instance Types](http://aws.amazon.com/ec2/instance-types/) and [Instance Types](http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/instance-types.html?r=2153)
+ [Configuring an AMI for IMDS V2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-IMDS-new-instances.html#configure-IMDS-new-instances-ami-configuration) use by default
## Preparing and securing your AMI for AWS Marketplace
We recommend the following guidelines for creating secure AMIs:
+ Use the [Guidelines for Shared Linux AMIs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/building-shared-amis.html) in the *Amazon EC2 User Guide*
+ Architect your AMI to deploy as a minimum installation to reduce the attack surface. Disable or remove unnecessary services and programs.
+ Whenever possible, use end-to-end encryption for network traffic. For example, use Secure Sockets Layer (SSL) to secure HTTP sessions between you and your buyers. Ensure that your service uses only valid and up-to-date certificates.
+ When documenting your AMI product, provide security group recommendations for buyers to control inbound traffic access to their instances. Your recommendations should specify the following:
+ The minimum set of ports required for your services to function.
+ The recommended ports and source IP address ranges for administrative access.
These security group recommendations help buyers implement proper access controls. For more information about how to add a new version to your AMI product, see [Add a new version](single-ami-versions.md#single-ami-adding-version).
+ Consider performing a penetration test against your AWS computing environment at regular intervals, or consider employing a third party to conduct such tests on your behalf. For more information, including a penetration testing request form, see [AWS Penetration Testing](http://aws.amazon.com/security/penetration-testing/).
+ Be aware of the top 10 vulnerabilities for web applications, and build your applications accordingly. To learn more, see [Open Web Application Security Project (OWASP) - Top 10 Web Application Security Risks](https://owasp.org/www-project-top-ten/). When new internet vulnerabilities are discovered, promptly update any web applications that ship in your AMI. Examples of resources that include this information are [SecurityFocus](http://www.securityfocus.com/vulnerabilities) and the [NIST National Vulnerability Database](http://nvd.nist.gov/).
For more information related to security, see the following resources:
+ [AWS Cloud Security](http://aws.amazon.com/security/)
+ [The Center for Internet Security (CIS): Security Benchmarks](http://benchmarks.cisecurity.org/downloads/benchmarks/)
+ [The Open Web Application Security Project (OWASP): Secure Coding Practices - Quick Reference Guide](https://owasp.org/www-project-secure-coding-practices-quick-reference-guide/)
+ [OWASP Top 10 Web Application Security Risks](https://owasp.org/www-project-top-ten/)
+ [SANS (SysAdmin, Audit, Networking, and Security) Common Weakness Enumeration (CWE) Top 25 Most Dangerous Software Errors](http://www.sans.org/top25-software-errors/)
+ [Security Focus](http://www.securityfocus.com/vulnerabilities)
+ [NIST National Vulnerability Database](http://nvd.nist.gov/)
## Scanning your AMI for publishing requirements
To publish your AMI on the AWS Marketplace Catalog, you must complete AMI scanning. AMI scanning checks for unpatched common vulnerabilities and exposures (CVEs) and verifies that your AMI follows security best practices. For more information, refer to [Preparing and securing your AMI for AWS Marketplace](https://docs.aws.amazon.com/marketplace/latest/userguide/best-practices-for-building-your-amis.html#securing-an-ami)
To perform AMI scanning, choose one of the following options:
**Option 1: Assets menu**
This method allows for scanning AMIs outside of the product creation flow. It’s also useful for SaaS sellers using SAAS Quick Launch who need to scan assets without creating an AMI product.
1. From the [AWS Marketplace Management Portal](https://aws.amazon.com/marketplace/management/homepage), navigate to the **Assets** menu and choose **Amazon Machine Image**.
1. To start the scanning process, choose **Add AMI**.
1. You can view the AMIs scan status by returning to this page.
**Option 2: Request changes menu**
This option is available for sellers who have already created an AMI product. Learn more at [Creating AMI-based products](ami-single-ami-products.md)
1. From the [AWS Marketplace Management Portal](https://aws.amazon.com/marketplace/management/homepage), navigate to the **Products** menu and choose **Server**.
1. Select your product from **Server products**. This must be an AMI-based product. The product can be in any state and does not need to be in the **Public** published state for next steps.
1. Navigate to the **Request changes** menu and select **Update versions**.
1. Select **Test ‘Add version’**. Follow the prompts to submit a request with your AMI details. If the request succeeds, this indicates that the AMI has passed scanning successfully. Unlike the **Add new version** option, **Test 'add version'** does not add a new version to the AMI-based product if the scan is successful.
**Note**
To learn about giving AWS Marketplace access to your AMI, see [Giving AWS Marketplace access to your AMI](single-ami-marketplace-ami-access.md).
## Verifying your software is running on your AWS Marketplace AMI
We strongly recommend that your software verify at runtime that it is running on an Amazon EC2 instance created from your AMI product.
To verify the Amazon EC2 instance is created from your AMI product, use the instance metadata service built into Amazon EC2. The following steps take you through this validation. For more information about using the metadata service, see [Instance metadata and user data](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) in the *Amazon Elastic Compute Cloud User Guide*.
1. *Obtain the instance identity document*
Each running instance has an identity document accessible from the instance that provides data about the instance itself. The following example shows using curl from the instance to retrieve the instance identity document.
IMDSv2: (Recommended)
```
TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/dynamic/instance-identity/document
{
"accountId" : "0123456789",
"architecture" : "x86_64",
"availabilityZone" : "us-east-1e",
"billingProducts" : null,
"devpayProductCodes" : null,
"marketplaceProductCodes" : [ "0vg0000000000000000000000" ],
"imageId" : "ami-0123456789abcdef1",
"instanceId" : "i-0123456789abcdef0",
"instanceType" : "t2.medium",
"kernelId" : null,
"pendingTime" : "2020-02-25T20:23:14Z",
"privateIp" : "10.0.0.2",
"ramdiskId" : null,
"region" : "us-east-1",
"version" : "2017-09-30"
}
```
IMDSv1:
```
curl http://169.254.169.254/latest/dynamic/instance-identity/document{
"accountId" : "0123456789",
"architecture" : "x86_64",
"availabilityZone" : "us-east-1e",
"billingProducts" : null,
"devpayProductCodes" : null,
"marketplaceProductCodes" : [ "0vg0000000000000000000000" ],
"imageId" : "ami-0123456789abcdef1",
"instanceId" : "i-0123456789abcdef0",
"instanceType" : "t2.medium",
"kernelId" : null,
"pendingTime" : "2020-02-25T20:23:14Z",
"privateIp" : "10.0.0.2",
"ramdiskId" : null,
"region" : "us-east-1",
"version" : "2017-09-30"
}
```
1. *Verify the instance identity document*
You can verify that the instance identity is correct using the signature. For details about this process, see [ Instance identity documents](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html) in the *Amazon Elastic Compute Cloud User guide*.
1. *Verify the product code*
When you initially submit your AMI product for publishing, your product is assigned a [product code](https://docs.aws.amazon.com/marketplace/latest/userguide/ami-getting-started.html#ami-product-codes) by AWS Marketplace. You can verify the product code by checking the `marketplaceProductCodes` field in the instance identity document, or you can get it directly from the metadata service:
IMDSv2:
```
TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/product-codes
```
If the product code matches the one for your AMI product, then the instance was created from your product.
# AMI product pricing for AWS Marketplace
AWS Marketplace has multiple pricing models for Amazon Machine Image (AMI) products. With seller private offers, there are options available for multi-year and custom duration contracts. For more information about multi-year and custom duration contracts, see [Preparing a private offer for your AWS Marketplace product](private-offers-overview.md) and [Private offer installment plans](installment-plans.md). The following sections provide information about pricing models for AMI-based products.
**Note**
You must be able to provide a W-9 tax form (for US based entities) or a W-8 form (for EU-based entities) as described in [Registering as a seller on AWS Marketplace](seller-account-registering.md).
**Topics**
+ [AMI pricing models](#pricing-models-for-ami-products)
+ [AWS charges and software charges](#aws-charges-vs-software-charges)
+ [Custom metering pricing for AMI products with AWS Marketplace Metering Service](custom-metering-pricing-ami-products.md)
+ [Contract pricing for AMI products on AWS Marketplace](ami-contracts.md)
+ [Associating licenses with AMI-based products using AWS License Manager](ami-license-manager-integration.md)
## AMI pricing models
The following table provides general information about pricing models for AMI-based products.
| Pricing model | Description |
| --- | --- |
| Free | Customers can run as many instances as Amazon Elastic Compute Cloud (Amazon EC2) supports with no additional software charges incurred. Free Trial and Annual pricing can't be combined with Monthly pricing. |
| Bring your own license (BYOL) | AWS Marketplace doesn't charge customers for usage of the software, but customers must supply a license key to activate the product. This key is purchased outside of AWS Marketplace. The entitlement and licensing enforcement, in addition to all pricing and billing, are handled by you. |
| Paid hourly or hourly-annual | **Hourly** – Software is charged by the hour. Each instance type can be priced differently (but it isn't required to be), and usage is rounded up to the nearest whole hour. **Hourly with Free Trial** – Customers are limited to running exactly one instance of the software without incurring a charge. You define the duration, between 5 and 30 days. The free trial applies to the most expensive instance type that is running, and any concurrent usage outside the 1 instance is billed at the hourly rate. NOTE: This is a different model than the AWS Free Tier for Amazon EC2 usage whereby customers are given 750 hours of free usage each month. **Hourly and Monthly** – Both hourly and monthly charges are applied independently. The monthly fee is charged every month regardless of usage, and the hourly fee is applied based on hourly usage only. **Hourly with Annual** – Customers have the option to purchase a year’s worth of usage upfront for one Amazon EC2 instance of one instance type. You set the pricing for each instance type and can offer net savings over the hourly price. Any customer usage above the number of annual subscriptions purchased is billed at the hourly rate you set for that instance type. **Hourly with Multi-Annual and Custom Duration** – This type of offer is only available through seller private offers. Using seller private offers, you specify a custom contract duration, up to 3 years. You can specify upfront payment, or include a flexible payment schedule. You set the pricing for each instance type. If there is a flexible payment schedule in the offer, you also set the invoice dates, payment amounts, and number of instances for each instance type included in the offer. For an active seller private offer with a flexible payment schedule, after the customer launches the specified number of instances, any additional instances launched are charged at the hourly rate specified in the seller private offer. For more information about multi-year and custom duration contracts, see [Preparing a private offer for your AWS Marketplace product](private-offers-overview.md) and [Private offer installment plans](installment-plans.md). **Hourly with Annual (includes Free Trial)** – This is identical to the Hourly model with an Annual option, except it includes a Free Trial allowing a customer to run one instance of any instance type for free for a set number of days that you determine. Annual subscriptions can be purchased at any time, and they are combined with the Free Trial subscription. **Annual with Hourly** – Same as the Hourly with Annual pricing model. Customers have the option to purchase a year’s worth of usage upfront for one Amazon EC2 instance of one instance type. You set the pricing for each instance type and can offer net savings over the hourly price, but offering savings isn't required. Any customer usage above the number of annual subscriptions purchased is billed at the hourly rate you set for that instance type. **Multi-Annual and Custom Duration with Hourly** – This is only available through [Preparing a private offer for your AWS Marketplace product](private-offers-overview.md). Using seller private offers, you can specify a custom duration contract of up to three years. You can require upfront payment, or you can offer a flexible payment schedule to the customer. You set the pricing for each instance type for the duration of the contract, and the hourly pricing for additional instances launched. If you offer a flexible payment schedule, you also set the invoice dates, payment amounts, and number of instances for each instance type included in the offer. For an active private offer with a flexible payment schedule, after the specified number of instances have been launched, any additional instances the customer launches are charged at the hourly rate specified in the private offer. For more information about multi-year and custom duration contracts, see [Preparing a private offer for your AWS Marketplace product](private-offers-overview.md) and [Private offer installment plans](installment-plans.md). Free Trial and Annual pricing can't be combined with Monthly pricing. |
| Paid monthly | **Monthly** – Software is paid for on a fixed monthly basis, regardless of the number of instances the customer runs. Monthly charges are pro-rated at sign-up and upon cancellation. Example: A customer who subscribes for 1 day of the month will be charged for 1/30th of the month. **Monthly with Hourly** – Both Hourly and Monthly charges are applied independently. The monthly fee is charged every month regardless of usage, and the hourly fee is applied based on hourly usage only. Free Trial and Annual pricing can't be combined with Monthly pricing. |
| Paid usage pricing | Software is directly charged for the value you provide along with one of four usage categories: users, data, bandwidth, or hosts. You can define up to 24 dimensions for the product. All charges are still incurred hourly by the customer. All usage is calculated monthly and billed monthly using the same mechanism as existing AWS Marketplace software. Usage pricing is also referred to as AWS Marketplace Metering Service. |
| Contract pricing model | **AMI with contract pricing** – A Single-AMI product or Single-AMI with AWS CloudFormation stack that the buyer pays an upfront fee for. |
## AWS charges and software charges
Amazon Machine Image (AMI)-based product charges fall into two categories:
+ **Infrastructure Pricing Details** – All AMI-based products incur associated AWS infrastructure charges depending on the services and infrastructure used. These rates and fees are defined and controlled by AWS, and can vary between AWS Regions. For more information, see [Amazon EC2 Pricing](https://aws.amazon.com/ec2/pricing/).
+ **Software Pricing Details** – For Paid products, the seller defines the charges for using the software.
These two product charge categories are displayed separately on the AWS Marketplace detail pages to help buyers understand the potential cost of using the products.
### Free trial for AMI hourly products
AMI hourly products are eligible for the optional Free trial program. In a Free trial, a customer can subscribe to the product and use a single instance for up to 31 days without paying software charges on the product. Applicable AWS infrastructure charges still apply. Free trials will automatically convert to a paid subscription upon expiration. Customers will be charged for additional usage above the free units provided. To offer an hourly product free trial, define the duration of the trial period and notify the [AWS Marketplace Seller Operations](https://aws.amazon.com/marketplace/management/contact-us/) team. The trial period can be 5–31 days.
When customers subscribe to a Free trial product, they receive a welcome email message that includes the term of the Free trial, a calculated expiration date, and details on unsubscribing. A reminder email message is sent three days before the expiration date.
If you offer a Free trial product in AWS Marketplace, you agree to the specific refund policies described under **Refund Policy**.
### Additional resources
For more information about AMI product pricing, see the following topics:
+ [Custom metering pricing for AMI products with AWS Marketplace Metering Service](custom-metering-pricing-ami-products.md)
+ [Contract pricing for AMI products on AWS Marketplace](ami-contracts.md)
For more information bout billing, metering, and licensing integrations for AMI-based products, see the following topics:
about AMI product pricing, see the following topics:
+ [Configuring custom metering for AMI products with AWS Marketplace Metering Service](custom-metering-with-mp-metering-service.md)
+ [Associating licenses with AMI-based products using AWS License Manager](ami-license-manager-integration.md)
# Custom metering pricing for AMI products with AWS Marketplace Metering Service
With the AWS Marketplace Metering Service, you can modify your software to send metering records to an endpoint to capture usage. You can select a usage category and define up to 24 dimensions for that one category. These dimensions are metered once per hour, aggregated, and charged against a price plan that you define. As a seller, you must determine which dimension you want to use. After the AMI is published, you will not be able to change it. The following sections provide information about AWS Marketplace Metering Service.
**Topics**
+ [Metering service concepts](#metering-service-concepts)
+ [Pricing your software](#pricing-your-software)
+ [Adding your product to AWS Marketplace](#listing-your-product-on-aws-marketplace)
+ [Modifying your software to use the Metering Service](#modifying-your-software-to-use-the-metering-service)
+ [Vendor-metered tagging (Optional)](#ami-vendor-metered-tagging)
+ [Configuring custom metering](#configure-custom-metering)
+ [Configuring custom metering for AMI products with AWS Marketplace Metering Service](custom-metering-with-mp-metering-service.md)
## Metering service concepts
Before you use the AWS Marketplace Metering Service, note the following important service concepts:
+ **Usage Category** – Any software product priced through the use of the Metering Service is categorized according to one usage category, which determines the appropriate way to charge customers. Usage categories include but aren't limited to:
+ **Users** – A defined set of permissions associated with a single identifier. This category is appropriate for software in which a customer’s users connect to the software directly (for example, for customer-relationship management or business intelligence reporting).
+ **Hosts** – Any server, node, instance, endpoint, or other part of a computing system. This category is appropriate for software that monitors or scans many customer-owned instances (for example, performance or security monitoring).
+ **Data** – Storage or information, measured in MB, GB, or TB. This category is appropriate for software that manages stored data or processes data in batches.
+ **Bandwidth** – Measured in Mbps or Gbps. This category is appropriate for software that allows customers to specify an amount of bandwidth to provision.
+ **Unit** – Unit of measurement; see the examples described next.
+ **Usage Unit** – A software product's specific usage unit corresponds to the selected usage category. This usage unit describes the unit your software will charge on. Examples include:
+ **NodesHrs** (corresponding to the Hosts category)
+ **UserHrs** (corresponding to the User category)
+ **GBStored** (corresponding to the Data category)
+ **Consumption** – Software products priced through the use of the Metering Service charge for consumption in one of three ways:
+ Provisioned – The software allows customers to configure a specific amount of resources for use (for example, number of users or a fixed amount of bandwidth). Each hour, customers pay for what they have provisioned.
+ Concurrent – The software allows any number of distinct hosts or users to connect to the software. Each hour, customers pay based on the number of hosts or users who accessed the software.
+ Accumulated – The software allows customers to use any amount of data, either processed or stored. Each hour, customers pay for the aggregated amount.
+ **Pricing** – Software products priced through the use of the Metering Service must specify either a single price or define up to 24 dimensions, each with their own price. Details about the pricing options include:
+ Single dimension – This is the simplest pricing option. Customers pay a single price per resource unit per hour, regardless of size or volume (for example, \$10.014 per user per hour, or \$10.070 per host per hour).
+ Multiple dimensions – This pricing option is appropriate when the selected usage category varies along multiple axes. For example, for host monitoring, a different price could be set depending on the size of the host. Or, for user-based pricing, a different price could be set based on the type of user (for example, admin, power user, and read-only user).
+ **Metering** – All usage is recorded as a metering event, once each hour. Your software must be configured to send the appropriate dimension and usage amount to the AWS Marketplace Metering Service.
+ Allocations – Optionally, you may distribute the usage into allocations by properties that you track. These allocations are represented as tags to the buyer. The tags allow the buyer to view their costs split into usage by tag. For example, if you charge by the user, and users have a "Department" property, you could create usage allocations with tags that have a key of "Department", and one allocation per value. This approach doesn't change the price, dimensions, or the total usage that you report. However, it allows your customer to view their costs by categories appropriate to your product.
## Pricing your software
When pricing your software with the AWS Marketplace Metering Service, you must first decide on a usage category and how it will be consumed. The service supports six distinct pricing scenarios. You must select only one of these for your product:
+ Provisioned user (per hour)
+ Concurrent user (per hour)
+ Provisioned host (per hour)
+ Concurrent host (per hour)
+ Provisioned bandwidth (per hour)
+ Accumulated data (per hour)
Next, you must decide how to price the selected usage category:
+ Single price
+ Multiple dimensions (up to 24)
[Adding your product to AWS Marketplace](#listing-your-product-on-aws-marketplace) describes how to provide a customer-friendly description of your dimension and pricing.
### Example: Provisioned bandwidth with nonlinear pricing
Imagine you offer network appliance software. You choose to bill by provisioned bandwidth. For your usage category, select **Bandwidth**. In addition to charging by bandwidth, you want to charge a different price as buyers scale up. You can define multiple dimensions within the bandwidth category. You can define a distinct price for 25 Mbps, 100 Mbps, and 1 Gbps.
### Example: Concurrent hosts with multiple dimensions
Imagine you offer software that monitors other Amazon EC2 instances. You choose to bill by the number of hosts that are being monitored. For your usage category, select **Host**. In addition to charging by host, you want to charge for the extra value for monitoring larger hosts. You can use multiple dimensions within the host category. You can define a distinct price for micro, small, medium, large, x-large, 2XL, 4XL, and 8XL instances. Your software is responsible for mapping each particular host to one of your defined dimensions. Your software is responsible for sending a separate metering record for each dimension of your usage category if applicable.
## Adding your product to AWS Marketplace
To take advantage of the Metering Service, you must create a new product for AWS Marketplace to list. If your product is already on the AWS Marketplace, you will need to decide whether the new AWS Marketplace Metering Service product will be made available in addition to your current product, or if it will replace your current product as the only version available to new users. If you choose replacement, the existing product will be removed from the AWS Marketplace so that it is no longer available for new buyers. Existing customers will continue to have access to their old product and instances, but they can migrate to the new product at their convenience. The new product must meter usage to the AWS Marketplace Metering Service, as described in [Modifying your software to use the Metering Service](#modifying-your-software-to-use-the-metering-service).
After you have your AMI, follow the standard process to share and scan your AMI using the self-service tool. In addition to using the template available on the management portal, fill out the product load form and upload it to start the ingestion process.
Use the following definitions to complete the fields of the Product Load Form for the AWS Marketplace Metering Service. On the Product Load Form, these fields are labeled as **Flexible Consumption Pricing (FCP)** to differentiate them from hourly and monthly priced products.
+ **Title** – If you already have a product on AWS Marketplace and you're adding the same product with the AWS Marketplace Metering Service, include the FCP category and dimension in parentheses to differentiate them (for example, “PRODUCT TITLE (Data)”).
+ **Pricing Model** –From the dropdown list, choose **Usage**.
+ **FCP Category** – The category in which customers are charged for paid products with a **Usage** pricing component. From the dropdown list, choose **Users**, **Hosts**, **Data**, or **Bandwidth**.
+ **FCP Unit** –The unit of measurement on which customers are charged for paid products with a **Usage** pricing component. Options will appear in the dropdown list based on the FCP category you selected. The following table lists the valid units for each category.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/marketplace/latest/userguide/custom-metering-pricing-ami-products.html)
+ **FCP Dimension Name** – The name used when sending metering records by calling the `MeterUsage` operation. It is visible in billing reports. However, because it isn't external-facing, the name doesn't need to be user-friendly. The name can be no more than 15 characters and can only include alphanumeric and underscore characters. After you set the name and make the product public, you can't change it. Changing the name requires a new AMI.
+ **FCP Dimension Description** – The customer-facing statement that describes the dimension for the product. The description (can be no more than 70 characters and should be user-friendly. Examples of descriptions include: Administrators per hour and Per Mbps bandwidth provisioned. After the product is published, you can't change this description.
+ **FCP Rate** – The software charge per unit for this product. This field supports eight decimal places.
**Notes:**
You don't need to fill out hourly and annual pricing fields.
Free trial and annual pricing aren't compatible.
Products that use an AMI, and the Clusters, and AWS Resources feature, can't use the AWS Marketplace Metering Service.
Price, instance type, or AWS Region change will follow the same process as other AWS Marketplace products.
Products with the AWS Marketplace Metering Service can't be converted to other pricing models such as hourly, monthly, or Bring Your Own License (BYOL).
AWS Marketplace recommends adding IAM policy information in your usage instructions or document.
You can include up to 24 FCP dimensions in total. Once created and published, you can't modify existing dimensions, but you can add new ones (up to the limit of 24).
If you have questions, contact the [AWS Marketplace Seller Operations](https://aws.amazon.com/marketplace/management/contact-us/) team.
## Modifying your software to use the Metering Service
You will need to modify your software to record customer usage, send hourly usage reports to the Metering Service, and handle new failure modes. The software operates independently of pricing, but the software will need to know about the usage category, how it's consumed, and any dimensions.
### Measuring consumption
Your software must determine how much of the selected usage category and which dimensions the customer has consumed. This value will be sent, once each hour, to the Metering Service. In all cases, it's assumed that your software has the ability to measure, record, and read consumption of resources for the purpose of sending it on an hourly basis to the Metering Service.
For provisioned consumption, this will typically be read from the software configuration as a sampled value, but might also be a maximum configured value, recorded each hour. For concurrent consumption, this might be either a periodic sample or a maximum value recorded each hour. For accumulated consumption, this will be a value that is accumulated each hour.
For pricing on multiple dimensions, multiple values must be measured and sent to the Metering Service, one per dimension. This requires your software to be programmed or configured with the known set of dimensions when you provide the AMI. The set of dimensions can't change after a product is created.
For each pricing scenario, the following table describes recommended ways for measuring consumption each hour.
| **Scenario ** | **How to measure ** |
| --- | --- |
| Provisioned user | Current number of provisioned users (sampled). -OR- Maximum number of provisioned users (seen that hour). |
| Concurrent user | Current number of concurrent users (sampled). -OR- Maximum number of concurrent users (seen that hour). -OR- Total number of distinct users (seen that hour). |
| Provisioned host | Current number of provisioned hosts (sampled). -OR- Maximum number of provisioned hosts (seen that hour). |
| Concurrent host | Current number of concurrent hosts (sampled). -OR- Maximum number of concurrent hosts (seen that hour). -OR- Total number of distinct hosts (seen that hour). |
| Provisioned bandwidth | Current provisioned bandwidth setting (sampled). -OR- Maximum provisioned bandwidth (seen that hour). |
| Accumulated data | Current GB of data stored (sampled). -OR- Maximum GB of data stored (seen that hour). -OR- Total GB of data added or processed that hour. -OR- Total GB of data processed that hour. |
## Vendor-metered tagging (Optional)
Vendor-metered tagging helps Independent Software Vendors (ISVs) give the buyer more granular insight into their software usage and can help them perform cost allocation.
To tag a buyer's software usage, you need to determine how costs are allocated. First ask your buyers what they want to see in their cost allocation. Then you can split the usage across properties that you track for the buyer’s account. Examples of properties include `Account ID`, `Business Unit`, `Cost Centers`, and other relevant metadata for your product. These properties are exposed to the buyer as tags. Using tags, buyers can view their costs split into usage by the tag values in their AWS Billing Console ([https://console.aws.amazon.com/costmanagement/](https://console.aws.amazon.com/costmanagement/)). Vendor-metered tagging doesn't change the price, dimensions, or the total usage that you report. It allows your customer to view their costs by categories appropriate to your product.
In a common use case, a buyer subscribes to your product with one AWS account. The buyer also has numerous users associated with the same product subscription. You can create usage allocations with tags that have a key of `Account ID`, and then allocate usage to each user. In this case, buyers can activate the `Account ID` tag in their Billing and Cost Management console and analyze individual user usage.
### Seller experience
Sellers can aggregate the metering records for resources with the same set of tags instead of aggregating usage for all resources. For example, sellers can construct the metering record that includes different buckets of `UsageAllocations`. Each bucket represents `UsageQuantity` for a set of tags, such as `AccountId` and `BusinessUnit`.
In the following diagram, **Resource 1** has a unique set of `AccountId` and `BusinessUnit` tags, and appears in the **Metering Record** as a single entry.
**Resource 2** and **Resource 3** both have the same `AccountId` tag, `2222`, and the same `BusinessUnit` tag, `Operations`. As a result, they're combined into a single `UsageAllocations` entry in the **Metering Record**.
![\[Diagram showing how vendor metering tags combine usage data. Three resources (Resource 1, 2, and 3) with different AccountIds and BusinessUnits are consolidated into a single Metering Record with UsageAllocations grouped by AccountId and BusinessUnit before being sent to the AWS Marketplace Metering Service.\]](http://docs.aws.amazon.com/marketplace/latest/userguide/images/seller-vendor-meter-tag.png)
Sellers can also combine resources without tags into a single `UsageAllocation` with the allocated usage quantity and send it as one of the entries in `UsageAllocations`.
Limits include:
+ Number of tags – 5
+ Size of `UsageAllocations` (cardinality) – 2,500
Validations include:
+ Characters allowed for the tag key and value – a-zA-Z0-9\$1 -=.\$1:\$1/@
+ Maximum tags across `UsageAllocation` list – 5
+ Two `UsageAllocations` can't have the same tags (that is, the same combination of tag keys and values). If that's the case, they must use the same `UsageAllocation`.
+ The sum of `AllocatedUsageQuantity` of `UsageAllocation` must equal the `UsageQuantity`, which is the aggregate usage.
### Buyer experience
The following table shows an example of the buyer experience after a buyer activates the `AccountId` and `BusinessUnit` vendor tags.
In this example, the buyer can see allocated usage in their **Cost Usage Report**. The vendor-metered tags use the prefix `“aws:marketplace:isv”`. Buyers can activate them in the Billing and Cost Management, under **Cost Allocation Tags**, **AWS-generated cost allocation tags**.
The first and last rows of the **Cost Usage Report** are relevant to what the Seller sends to the Metering Service (as shown in the [Seller experience](container-metering-meterusage.md#container-vendor-metered-tag-seller) example).
**Cost Usage Report (Simplified)**
| ProductCode | Buyer | UsageDimension | UsageQuantity | `aws:marketplace:isv:AccountId ` | `aws:marketplace:isv:BusinessUnit` |
| --- | --- | --- | --- | --- | --- |
| xyz | 111122223333 | Network: per (GB) inspected | 70 | 2222 | Operations |
| xyz | 111122223333 | Network: per (GB) inspected | 30 | 3333 | Finance |
| xyz | 111122223333 | Network: per (GB) inspected | 20 | 4444 | IT |
| xyz | 111122223333 | Network: per (GB) inspected | 20 | 5555 | Marketing |
| xyz | 111122223333 | Network: per (GB) inspected | 30 | 1111 | Marketing |
For a code example, see [`MeterUsage` with usage allocation tagging (Optional)](custom-metering-with-mp-metering-service.md#ami-meterusage-code-example)
## Configuring custom metering
For more information about working with AWS Marketplace Metering Service, see [Configuring custom metering for AMI products with AWS Marketplace Metering Service](custom-metering-with-mp-metering-service.md).
# Configuring custom metering for AMI products with AWS Marketplace Metering Service
**Note**
For AMI-based products with custom metering pricing, your software must call the [MeterUsage API](https://docs.aws.amazon.com/marketplace/latest/APIReference/API_marketplace-metering_MeterUsage.html) using temporary AWS credentials of the IAM role for Amazon Elastic Compute Cloud attached to the Amazon EC2 instance. Using long-term access keys is not supported.
The AWS Marketplace Metering Service is a pricing and metering feature that you can use to directly charge for your software by usage category. There are five usage categories: users, data, bandwidth, hosts, or unit. You can use the Metering Service with Amazon Machine Image (AMI)-based, container-based, and software as a service (SaaS)-based products. The following sections provide more information about how to configure custom metering with AWS Marketplace Metering Service.
The AWS Marketplace Metering Service enables several new scenarios. For example, if your software monitors hosts, you can charge for each host monitored. You can have different prices based on the host size, and charge for the number of concurrent hosts monitored each hour. Similarly, if your software allows many users across an organization to sign in, you can charge by the number of users. Each hour, the customer is charged for the total number of provisioned users.
For more information, see the [https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/Welcome.html](https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/Welcome.html).
For more information about integrating AWS Marketplace Metering Service API for AMI-based products with custom metering pricing, see the [List AMI products priced by custom units](https://catalog.workshops.aws/mpseller/en-US/ami/list-ami-custom-units) lab of the *AWS Marketplace seller workshop*.
**Topics**
+ [Requirements](#metering-service-requirements)
+ [Call AWS Marketplace Metering Service](#call-aws-marketplace-metering-service)
+ [Failure handling](#important-information-about-failure-handling)
+ [Limitations](#limitations)
+ [Code example](#ami-metering-code-example)
## Requirements
All AMI-based software that uses the Metering Service must meet the following requirements:
+ Your software must be launched from AWS Marketplace through an Amazon Machine Image (AMI).
+ If you have an existing product in AWS Marketplace, you must submit a new AMI and create a new product to enable this feature.
+ All software must be provisioned with an AWS Identity and Access Management (IAM) role. The end customer must add an IAM role to the Amazon Elastic Compute Cloud (Amazon EC2) instance the user is provisioning with the software. The use of an IAM role is optional when you deploy software through AWS Marketplace. It's required when you deploy AWS Marketplace Metering Service software.
+ Your software must be able to determine consumption in some way.
## Call AWS Marketplace Metering Service
Your software must call the Metering Service hourly and record the consumption value for that hour.
When your software starts, it should record the minute-of-the-hour at which it started. This is referred to as the *start-minute*. Every hour on the start-minute, your software must determine the consumption value for that hour and call the Metering Service. For information about how to obtain this value, see [Modifying your software to use the Metering Service](https://docs.aws.amazon.com/marketplace/latest/userguide/custom-metering-pricing-ami-products.html#modifying-your-software-to-use-the-metering-service).
To wake up each hour at the start-minute, your software must use one of the following approaches:
+ A thread within your software.
+ A daemon process that starts up with the instance or software.
+ A cron job that is configured during application startup.
**Note**
Your software must call the AWS Marketplace Metering Service using the IAM role configured on the customer’s instance and specify the consumption dimension and amount.
Your software can use the AWS SDK to call the AWS Marketplace Metering Service, similar to the following example implementation:
1. Use the instance profile to create a service client. This requires the role configured for the EC2 instance. The role credentials are refreshed by the SDK automatically.
1. Each hour, read your software configuration and state to determine consumption values for that hour. This might include collecting a value-per-dimension.
1. Call the `meterUsage` method on the SDK client with the following parameters (call additionally for each dimension that has usage):
+ `timestamp` – Timestamp of the hour being recorded (in UTC).
+ `productCode` – Product code assigned to the software.
+ `dimension` – Dimension (or dimensions) assigned to the software.
+ `quantity` – Consumption value for the hour.
+ `allocations` – (Optional) You may provide allocations for the usage across properties that you track. These allocations must add up to the total consumption in the record. To the buyer, these display as potential cost allocation tags in their billing tools (such as the AWS Billing and Cost Management console). The buyer must activate the tags in their account in order to track their cost using these tags.
In addition, your software must call an in-Region AWS Marketplace Metering Service endpoint. Your product must have a correct Regional endpoint set up, so `us-east-1` sends records to a `us-east-1` endpoint, and `us-west-2` sends records to a `us-west-2` endpoint. Making in-Region calls provides buyers with a more stable experience and prevents situations in which an unrelated Region’s availability could impact software running in another Region.
When you send metering records to the service, you must connect to the AWS Marketplace Metering Service in your Region. Use the `getCurrentRegion()` helper method to determine the Region in which the EC2 instance is running, and then pass this Region information to the `MeteringServiceClient` constructor. If you don't specify an AWS Region in the SDK constructor, the default `us-east-1` Region is used. If your application attempts to make cross-Region calls to the service, the calls are rejected. For more information, see [Determining an Application’s Current Region](https://java.awsblog.com/post/Tx3GBOIEN1JJMQ5/Determining-an-Application-s-Current-Region) and [getCurrentRegion()](http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/regions/Regions.html#getCurrentRegion()).
## Failure handling
Your product must send metering records to the service, a public internet endpoint, so that usage can be captured and billed. Because it's possible for a customer to modify network settings in a way that prevents your metering records from being delivered, your product should account for this by choosing a failure mode.
**Note**
Some metering failures may be transient issues in connecting to the AWS Marketplace Metering Service. AWS Marketplace strongly recommends implementing retries for up to 30 minutes, with exponential back off, to avoid short-term outages or network issues.
Typically, software can fail open (provide a warning message but maintain full functionality) or fail closed (disable all functionality in the application until a connection has been reestablished). You can choose to fail open, closed, or something specific to your application. We strongly recommend that you refrain from failing closed after less than two hours of metering failures.
As an example of failing partially open, you could continue to allow access to the software but not allow the buyer to modify the software settings. Or, a buyer could still access the software but would not be able to create additional users. Your software is responsible for defining and enforcing this failure mode. Your software’s failure mode must be included when your AMI is submitted, and it can't be changed later.
## Limitations
Keep these limitations in mind when designing and submitting your Metering Service-enabled software:
+ **IAM role and internet gateway requirements for your customers** – Your customers must have an internet gateway and must launch your software with an IAM role with specific permissions. For more information, see [AWS Marketplace metering and entitlement API permissions](iam-user-policy-for-aws-marketplace-actions.md). Your software can't connect to the Metering Service if these two conditions aren't met.
+ **Inability to add new or change usage category to existing Metering Service product** – When customers subscribe to your software product, they're agreeing to terms and conditions. Changing the usage categories in products with the Metering Service requires a new product and a new subscription.
+ **Inability to change dimensions to existing Metering Service product** – When customers subscribe to your software product, they're agreeing to terms and conditions. Changing the dimensions in products with the Metering Service requires a new product and a new subscription. You *can* add new dimensions to existing products, up to the limit of 24.
+ **Lack of free trial and annual subscriptions** – Metering Service products don't support free trials and annual subscriptions at launch.
+ **Multi-instance or cluster-based deployment considerations** – Some software is deployed as part of a multi-instance deployment. When you design your software, consider how and where consumption is measured and where metering records are emitted.
## Code example
The following code example is provided to help you integrate your AMI product with the AWS Marketplace APIs required for publishing and maintaining your product.
### `MeterUsage` with usage allocation tagging (Optional)
The following code example is relevant for AMI products with consumption pricing models. The Python example sends a metering record with appropriate usage allocation tags to AWS Marketplace to charge your customers for pay-as-you-go fees.
```
# NOTE: Your application will need to aggregate usage for the
# customer for the hour and set the quantity as seen below.
# AWS Marketplace can only accept records for up to an hour in the past.
#
# productCode is supplied after the AWS Marketplace Ops team has
# published the product to limited
# Import AWS Python SDK
import boto3
import time
usageRecord = [
{
"AllocatedUsageQuantity": 2,
"Tags":
[
{ "Key": "BusinessUnit", "Value": "IT" },
{ "Key": "AccountId", "Value": "123456789" },
]
},
{
"AllocatedUsageQuantity": 1,
"Tags":
[
{ "Key": "BusinessUnit", "Value": "Finance" },
{ "Key": "AccountId", "Value": "987654321" },
]
}
]
marketplaceClient = boto3.client("meteringmarketplace")
response = marketplaceClient.meter_usage(
ProductCode="testProduct",
Timestamp=int(time.time()),
UsageDimension="Dimension1",
UsageQuantity=3,
DryRun=False,
UsageAllocations=usageRecord
)
```
For more information about `MeterUsage`, see [MeterUsage](https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/API_MeterUsage.html) in the *AWS Marketplace Metering Service API Reference*.
### Example response
```
{ "MeteringRecordId": "string" }
```
# Contract pricing for AMI products on AWS Marketplace
Contract pricing for Amazon Machine Image (AMI)-based products means that the buyer pays an upfront fee for a single AMI product or single AMI with AWS CloudFormation stack. For AMI-based products with contract pricing, AWS Marketplace bills your customers upfront or by the payment schedule that you define, based on the contract between you and your customer. After that point, they're entitled to use those resources. This topic provides more information about contract pricing.
To set your pricing, choose one or more contract durations that you offer customers. You can enter different prices for each contract duration. Your options are 1-month, 12-months, 24-month, and 36-month durations. For private offers, you can specify a custom duration in months (up to 60 months).
**Note**
Free trials are not available for AMI products with contract pricing.
Choose the category that best describes your product’s pricing. The pricing category appears to customers on the AWS Marketplace website. You can choose from **Bandwidth** (GB/s, MB/s), **Data** (GB, MB, TB), **Hosts**, **Requests**, **Tiers**, or **Users**. If none of the predefined categories fit your needs, you can choose the more generic **Units** category.
The offer allows for up to 24 dimensions to be added to it. Each dimension requires the following data:
+ **Contracts Category** – For contract products with no consumption-based pricing, you can choose a category which most closely resembles the category of dimension in the contract or choose **Units** if no values resemble the units for the dimension in the contract
+ **Contracts Unit** – Choose one of the available values for the units that closely matches your dimensions based on the Category selected.
+ **Contracts Dimension Allow Multiple Purchases** – This field is used to indicate whether an offer is a tiered pricing offer or a non-tiered offer:
Tiered offer – Allows the buyer to subscribe to only one of the available dimensions in the offer. Dimensions in a tiered offer don't have the concept of quantities. Signing a contract with a specific dimension essentially indicates that the buyer has chosen the specific feature indicated by that dimension.
Non-tiered offer – Allows the customer to procure more than one dimensions as part of the contract and allows them to procure multiple units of each such dimension.
Setting a value of *true* for this field indicates that the offer is a non-tiered offer. Setting a value of *false* for this field indicates that the offer is a tiered offer.
When using the Product Load Form (PLF) to create the contracts for your AMI product, you must define the following fields for your pricing dimensions:
+ **Contracts DimensionX API Name** – The name that should appear in the license generated in the buyer’s AWS License Manager account. This name is also used as the value for `Name` in `Entitlement` in the `Checkoutlicense` API call.
+ **Contracts DimensionX Display Name** – The customer-facing name of the dimension that will be displayed on the product detail and procurement pages of the AWS Marketplace website. Create a name that is be user-friendly. The name's maximum length is 24 characters. After the listing is public, the value of `Name`can't be changed.
+ **Contracts DimensionX Description** – The customer-facing description of a dimension that provides additional information about the dimension for the product, such as the capabilities that the specific dimension provides. The maximum length for the description is 70 characters.
+ **Contracts DimensionX Quantity** – This is used to calculate proration in cases of agreement amendments to a product. This value of this field should be set to 1 for all contract offers. It should not be edited.
+ **Contracts DimensionX **1-Month Rate**** – The contract rate to be charged for one month of entitlements against this dimension. For non-tiered offers, this rate is charged for each unit of the dimension that is procured. This field supports three decimal places.
+ **Contracts DimensionX **12-Month Rate**** – The contract rate to be charged for 12 months of entitlements against the dimension. For non-tiered offers, this rate is charged for each unit of the dimension that is procured. This field supports three decimal places.
+ **Contracts DimensionX **24-Month Rate**** – The contract rate to be charged for 24 months of entitlements against the dimension. For non-tiered offers, this rate is charged for each unit of the dimension that is procured. This field supports three decimal places.
+ **Contracts DimensionX **36-Month Rate**** – The contract rate to be charged for 36 months of entitlements against the dimension. For non-tiered offers, this rate is charged for each unit of the dimension that is procured. This field supports three decimal places.
**Example: Data storage application**
| | 1-month price | 12-month price | 24-month price | 36-month price |
| --- | --- | --- | --- | --- |
| Unencrypted data (GB) | \$11.50/GB | \$116.00/GB | \$130.00/GB | \$160.00/GB |
| Encrypted data (GB) | \$11.55/GB | \$116.60/GB | \$131.20/GB | \$161.20/GB |
**Example: Log monitoring product**
| | 1-month price | 12-month price | 24-month price | 36-month price |
| --- | --- | --- | --- | --- |
| Basic (10 hosts monitored, 5 containers monitored) | \$1100 | \$11000 | \$12000 | \$14000 |
| Standard (20 hosts monitored, 10 containers monitored) | \$1200 | \$12000 | \$14000 | \$18000 |
| Pro (40 hosts monitored, 20 containers monitored) | \$1400 | \$14000 | \$18000 | \$116,000 |
| Additional hosts monitored per hour | \$110 | \$1100 | \$1200 | \$1400 |
| Additional containers monitored per hour | \$110 | \$1100 | \$1200 | \$1400 |
**Note**
The prices can be for the following durations: 1 month, 12 months, 24 months, or 36 months. You can choose to offer one or more of these options for your product. The durations must be the same across each dimension.
**Example**
For example, in a case where you have `ReadOnlyUsers` and `AdminUsers` dimensions, if you offer a yearly price for ReadOnlyUsers, you must offer a yearly price for `AdminUsers`, too.
## Automatic renewals
When customers purchase your product through AWS Marketplace using AMI contracts, they can agree to automatically renew the contract terms. Customers continue to pay for the entitlements every month or for 1, 2, or 3 years.
Customers can modify their renewal settings at any time. For more information, see [Modifying an existing contract](https://docs.aws.amazon.com/marketplace/latest/buyerguide/buyer-ami-contracts.html#modify-existing-contract) in the *AWS Marketplace Buyer Guide*.
# Associating licenses with AMI-based products using AWS License Manager
For Amazon Machine Image (AMI)-based products with contract pricing, you can use AWS License Manager to associate licenses with your product. AWS License Manager is a license management tool that enables your application to track and update licenses (also known as entitlements) that have been purchased by a customer. After the integration is complete, you can publish your product listing on AWS Marketplace. The following sections provide more information about using AWS License Manager to associate licenses with your AMI-based product.
For more information about AWS License Manager, see the [AWS License Manager User Guide](https://docs.aws.amazon.com/license-manager/latest/userguide/license-manager.html) and the [AWS License Manager](https://docs.aws.amazon.com/cli/latest/reference/license-manager/index.html) section of the *AWS CLI Command Reference*.
For more information about integrating AWS License Manager with AMI-based products with contract pricing, see the [List AMI products priced by upfront payment](https://catalog.workshops.aws/mpseller/en-US/ami/list-ami-upfront-payment) lab of the *AWS Marketplace seller workshop*.
**Note**
Customers can't launch new instances of the AMI after the contract expiry period. However, during the contract duration, they can launch any number of instances. These licenses are not node-locked or tied to particular instances.
**Private Offer Creation**– Sellers can generate private offers for the products using the Private offer creation tool in the AWS Marketplace Management Portal.
**Reporting** – You can set up data feeds by setting up an Amazon S3 bucket in the **Report** section in the AWS Marketplace Management Portal. For more information, see [Seller reports, data feeds, and dashboards in AWS Marketplace](reports-and-data-feed.md).
**Topics**
+ [License models](#license-models)
+ [Integration workflow](#LM-workflow)
+ [License Manager integration prerequisites](#LM-prereqs)
+ [Integrating an AMI-based product with AWS License Manager](#integrate-with-LM)
+ [License renewals and upgrades](#lic-renew-upgrade)
## License models
AWS Marketplace integration with AWS License Manager supports two license models:
+ [Configurable license model](#config-lic-model)
+ [Tiered license model](#tiered-lic-model)
### Configurable license model
The configurable license model (also known as the quantifiable license model) entitles a buyer to a specific quantity of resources after a buyer has procured a license.
You set a pricing dimension and a per unit price. Then, buyer can choose the quantity of the resources that they want to purchase.
**Example of pricing dimension and per unit price**
You can set a pricing dimension (such as data backup) and per unit price (such as \$130/unit)
The buyer can choose to purchase 5, 10, or 20 units.
Your product tracks and meters usage to measure the quantity of resources consumed.
With the configuration model, the entitlements are counted in one of two ways:
+ [Drawdown licenses](#drawndown-lic)
+ [Floating licenses](#floating-lic)
#### Drawdown licenses
The license is drawn from the pool of allowed amount of licenses upon use. That entitlement is checked out permanently and can't be returned to the license pool.
**Example of processing a limited amount of data**
A user is entitled to process 500 GB of data. As they continue to process data, the quantity is drawn from the pool of 500 GB until all 500 GB licenses are consumed.
For drawdown licenses, you can use the `CheckoutLicense` API operation to check out license units that are consumed.
**Example of backup to Amazon S3 for a number of units/year**
You have a storage product that allows backup to Amazon Simple Storage Service for up to 1024 units for data for one year. Your application can be launched by using multiple Amazon EC2 instances. Your application has a mechanism to track and aggregate data. Your software calls the `CheckoutLicense` API operation with the Product ID upon every backup or at fixed intervals to update the consumed quantities.
In this example, your software calls `CheckoutLicense` to check out 10 units of data. When the total capacity reaches the backup limit that the customer has purchased, the API call fails.
**Request**
```
linux-machine ~]$ aws license-manager checkout-license\
--product-sku "2205b290-19e6-4c76-9eea-377d6bf7la47" \
--checkout-type "PERPETUAL" \
--key-fingerprint "aws:294406891311:AWS/Marketplace:issuer-fingerprint" \
--entitlements "Name=DataConsumption, Value=l0, Unit=Count" \
--client-token "AKIAIOSFODNN7EXAMPLE"
```
**Response**
```
{
"CheckoutType": "PERPETUAL",
"EntitlementsAllowed": [
{
"Name": "DataConsumption",
"Count": 10,
"Units": "Count",
"Value": "Enabled"
}
},
"Expiration": "2021-04-22Tl9:02: 36",
"IssuedAt": "2021-04-22Tl8:02:36",
"LicenseArn": "arn:aws:license-manager::294406891311:license:l-16bf01b...",
"LicenseConsumptionToken": "AKIAIOSFODNN7EXAMPLE"
}
```
#### Floating licenses
The license is returned to the pool of the allowed amount of licenses after use.
**Example of number of users from a fixed upper limit**
A user is entitled to 500 simultaneous users on the application. As users log in and log out, the users are drawn and returned to the pool of 500 users. However, the application can't draw more than 500 users from the pool because 500 simultaneous users is the fixed upper limit.
For floating licenses, you can use the `CheckInLicense` API operation to return the license units to the entitlement pool.
**Example of number of concurrent users for one year**
Your product is priced based on number of concurrent users. The customer purchases a license for 10 users for one year. The customer launches the software by providing AWS Identity and Access Management (IAM) permissions. When a user logs in, your application calls the `CheckoutLicense` API operation to reduce the quantity by 1. When the user logs out, the application returns that license to the pool by calling the `CheckInLicense` API operation. If you don't call `CheckInLicense`, the license unit will be automatically checked in after 1 hour.
**Note**
In the following Request, the `key-fingerprint` isn't a placeholder value but the actual value of the fingerprint with which all licenses will be published.
**Request**
```
linux-machine ~]$ aws license-manager checkout-license\
--product-sku "2205b290-19e6-4c76-9eea-377d6bf7la47" \
--checkout-type "PROVISIONAL" \
--key-fingerprint "aws:294406891311:AWS/Marketplace:issuer-fingerprint" \
--entitlements "Name=ReadOnlyUSers, Value=l0, Unit=Count" \
--client-token "AKIAIOSFODNN7EXAMPLE"
```
**Response**
```
{
"CheckoutType": "PROVISIONAL",
"EntitlementsAllowed": [
{
"Name": "ReadOnlyUsers",
"Count": 10,
"Units": "Count",
"Value": "Enabled"
}
},
"Expiration": "2021-04-22Tl9:02: 36",
"IssuedAt": "2021-04-22Tl8:02:36",
"LicenseArn": "arn:aws:license-manager::294406891311:license:l-16bf01b...",
"LicenseConsumptionToken": "AKIAIOSFODNN7EXAMPLE"
}
```
### Tiered license model
The tiered license model entitles a buyer to a specific level, or tier, of application features after a buyer has procured a license.
You create tiers for your product, such as Basic, Intermediate, and Premium. The buyer then selects one of the predefined tiers.
The application doesn't need to track or meter usage of the application.
With the tiered license model, the entitlements aren't counted but instead signify a tier of service that was procured by the customer.
If you want to offer bundled features together, we recommend using the tiered license model.
**Example of Basic, Intermediate, and Premium tiers**
A customer can sign a contract for one of three possible tiers of the software: Basic, Intermediate, or Premium. Each of these tiers has its own pricing. Your software can identify the tier that the customer has signed up for by invoking the `CheckoutLicense` API operation and specifying all possible tiers in the request.
The response of the request contains the entitlement corresponding to the tier the customer has procured. Based on this information, the software can provision the appropriate customer experience.
#### Request
```
linux-machine ~]$ aws license-manager checkout-license\
--product-sku "2205b290-19e6-4c76-9eea-377d6bf7la47" \
--checkout-type "PROVISIONAL" \
--key-fingerprint "aws:294406891311:AWS/Marketplace:issuer-fingerprint" \
--entitlements "Name=BasicTier, Unit=None" "Name=IntermediateTier, Unit=None" \ "Name=PremiumTier, Unit=None"
```
#### Response
```
{
"CheckoutType": "PROVISIONAL",
"EntitlementsAllowed": [
{
"Name": "IntermediateTier",
"Units": "None"
}
},
"Expiration": "2021-04-22Tl9:02:36",
"IssuedAt": "2021-04-22Tl8:02:36",
"LicenseArn": "arn:aws:license-manager::294406891311:license:l-16bf01b...",
"LicenseConsumptionToken": "AKIAIOSFODNN7EXAMPLE"
}
```
## Integration workflow
The following steps show the workflow for integrating your AMI product with AWS License Manager:
1. Seller creates a product with AWS License Manager integration.
1. Seller lists the product on AWS Marketplace.
1. Buyer finds the product on AWS Marketplace and purchases it.
1. A license is sent to the buyer in their AWS account.
1. Buyer uses the software by launching the Amazon Elastic Compute Cloud (Amazon EC2) instance, Amazon Elastic Container Service (Amazon ECS) task, or Amazon Elastic Kubernetes Service (Amazon EKS) pod software, The customer deploys by using an IAM role.
1. Software reads the license in the buyer's AWS License Manager account, discovers the entitlements purchased, and provisions the features accordingly.
**Note**
License Manager doesn't do any tracking or updates; this is done by the seller’s application.
## License Manager integration prerequisites
Before publishing the product, you must do the following:
1. Create a new AMI product in the AWS Marketplace Management Portal, and make a note of its product code.
1. Fill out the Product Load Form (PLF) with the necessary price information, and return it to us for processing.
1. Use an IAM role for the task or pod running your application with the IAM permissions necessary to call `CheckoutLicense`, `ExtendLicenseConsumption`, and `CheckInLicense`.
The required IAM permissions are detailed in the following IAM policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Sid":"VisualEditorO",
"Effect":"Allow",
"Action":[
"license-manager:CheckoutLicense",
"license-manager:GetLicense",
"license-manager:CheckInLicense",
"license-manager:ExtendLicenseConsumption",
"license-manager:ListReceivedLicenses"
],
"Resource":"*"
}
]
}
```
------
1. Make a test call to the `RegisterUsage` API operation with a record for all of the pricing dimensions you define.
## Integrating an AMI-based product with AWS License Manager
You can integrate your AMI-based product with License Manager by using the [AWS License Manager](https://docs.aws.amazon.com/license-manager/latest/APIReference/Welcome.html) API. Launch the Amazon EC2 instances by using AWS Marketplace AMI-based products.
**Note**
Make sure that you have completed the [License Manager integration prerequisites](#LM-prereqs) before you perform the following procedure.
**To integrate your AMI-based product with License Manager**
1. Complete the procedure in [Creating a test license in License Manager](#creating-test-license). You must create a test license in License Manager for testing your integration.
1. Run the [GetLicense](https://docs.aws.amazon.com/license-manager/latest/APIReference/API_GetLicense.html) API operation using the license Amazon Resource Name (ARN) that you obtained in step 1. Note the value of the `KeyFingerprint` attribute of the `GetLicense` response for later use.
1. Download and include the latest public AWS SDK in your application.
1. To verify that the buyer is entitled to use a license for your application, run the [CheckoutLicense](https://docs.aws.amazon.com/license-manager/latest/APIReference/API_CheckoutLicense.html) API operation. Use the entitlements details and the key fingerprint of the test license that you obtained in step 1.
If there are no entitlements found for the license, or the entitlement maximum count is exceeded, the `CheckoutLicense` API operation returns `NoEntitlementsAllowedException`. If the entitlements are valid, or available to use, the `CheckoutLicense` operation returns a successful response with the requested entitlements and their values.
1. (Required for floating entitlements only) Run the [CheckinLicense](https://docs.aws.amazon.com/license-manager/latest/APIReference/API_CheckInLicense.html) API operation using the `LicenseConsumptionToken` that was received in the `CheckoutLicense` response. This action releases previously checked-out entitlements back into the pool of available entitlements.
1. After you successfully verify the License Manager integration with the test license that you created in step 1, update the key fingerprint in your code to `aws:294406891311:AWS/Marketplace:issuer-fingerprint`. Now, you're ready to work with licenses issued by AWS Marketplace.
Follow the release process of building the application to an AMI product and then submit the product to AWS Marketplace following the product publishing process.
### Creating a test license in License Manager
You use version 2 of the AWS Command Line Interface (AWS CLI) to create a test license in AWS License Manager. This test license is only used for verifying and testing the AWS License Manager integration. After the testing is completed, you can delete the test license. The actual license is generated by AWS Marketplace with a different key fingerprint.
AWS Marketplace supports two types of entitlements in AWS License Manager. However, only one type can be enabled for a product. When you create a license, including a test license, you must specify one of the following types of entitlements:
**Tiered entitlements ** – The tiered license model entitles the customer to certain application features. Customers can't define the quantity of units they want to purchase. However, they can select a single predefined package or tier. Customers can modify the contract later to subscribe to another tier.
**Configurable entitlements ** – The configurable license model grants entitlements to a certain quantity of resources when the customer procures a license. The customer chooses the quantity of units they want to purchase during the subscription process and will be billed based on the unit price. Customers can also subscribe to multiple dimensions.
The required parameters for use in the `CheckoutLicense` API operation are as follows:
+ `CheckoutType` – The valid values are `Perpetual` or `Provisional`:
+ `Perpetual` – Used when the quantity of entitlements checked out will be exhausted from the pool. Example: Buyer is entitled to process 500 GB of data. As they continue to process data, the quantity is drawn down and exhausted from the pool of 500 GB. Gets the status of a purchased license on whether the license is expired or about to be expired to send a notification to the customer.
+ `Provisional` – Used for floating license entitlements where entitlements are checked out of the pool and returned back after use. Example: User is entitled to 500 simultaneous users in the application. As users log in and log out, the users are drawn and returned to the pool of 500 users. For more information about floating license entitlements, see [Seller issued licenses in AWS License Manager.](https://docs.aws.amazon.com/license-manager/latest/userguide/seller-issued-licenses.html)
+ `ClientToken` – Unique, case-sensitive identifier to ensure the exact result occurs and is the same no matter how many times attempted. We recommend that you use a random universally unique identifier (UUID) for each request.
+ `Entitlements` – List of entitlements to be checked out.
+ For tiered entitlements, provide `Name` and `Unit` properties as follows:
`{`
`"Name": "",`
`"Unit": "None"`
`}`
+ For configurable entitlements, provide `Name`, `Unit`, and `Value`properties as follows:
`{`
`"Name": "",`
`"Unit": "",`
`"Value": {`
\$1
+ `KeyFingerprint` – Use this key fingerprint to verify that the license is issued by AWS Marketplace. The key fingerprint for licenses issued by AWS Marketplace is as follows:
`aws:294406891311:AWS/Marketplace:issuer-fingerprint`
+ `Product SKU` – Product ID with a Globally Unique Identifier (GUID) format that is associated with an AWS Marketplace product.
**Example of a configurable entitlement**
The following is an example of a request that uses the `CheckoutLicense` API operation to check out a configurable entitlement named `PowerUsers`.
```
aws license-manager checkout-license \
product-sku "2205b290-19e6-4c76-9eea-377d6bf71a47" \
checkout-type "PROVISIONAL" \
client-token "79464194dca9429698cc774587a603a1" \"Statement":[
entitlements "Name=PowerUsers,Value=1,Unit=Count" \
key-fingerprint "aws:294406891311:AWS/Marketplace:issuer-fingerprint"
```
**Example of a tiered entitlement**
The following is an example of a request that uses the `CheckoutLicense` API operation to check out a feature entitlement named `EnterpriseEdition`.
```
aws license-manager checkout-license \
--product-sku "2205b290-19e6-4c76-9eea-377d6bf71a47" \
--checkout-type "PROVISIONAL" \
--client-token "79464194dca9429698cc774587a603a1" \
--entitlements "Name=EnterpriseEdition,Unit=None" \
--key-fingerprint "aws:294406891311:AWS/Marketplace:issuer-fingerprint"
```
**To create a test license for your AMI-based product**
1. From your local environment with AWS CLI v2 installed, run the following script. The script creates the test license and configures the appropriate product details.
**Note**
Use a different AWS account than the test AWS account in which you are deploying and testing your software. Licenses can't be created, granted to, and checked out in the same AWS account.
```
#!/bin/bash
# Replace with intended product ID on AWS Marketplace
PRODUCT_ID=
# Replace with license recipient's AWS Account ID
BENEFICIARY_ACCOUNT_ID=
# Replace with your product's name
PRODUCT_NAME="Test Product"
# Replace with your seller name on AWS Marketplace
SELLER_OF_RECORD="Test Seller"
# Replace with intended license name
LICENSE_NAME="AWSMP Test License"
# Replace the following with desired contract dimensions
# More info here: https://docs.aws.amazon.com/license-manager/latest/APIReference/API_Entitlement.html
# Example "configurable entitlement"
ENTITLEMENTS='[
{
"Name": "ReadOnly",
"MaxCount": 5,
"Overage": false,
"Unit": "Count",
"AllowCheckIn": true
}
]'
# Example "tiered entitlement"
# ENTITLEMENTS='[
# {
# "Name": "EnterpriseUsage",
# "Value": "Enabled",
# "Unit": "None"
# }
# ]'
# Format "yyyy-mm-ddTHH:mm:ss.SSSZ"
# This creates a validity period of 10 days starting the current day
# Can be updated to desired dates
VALIDITY_START=$(date +%Y-%m-%dT%H:%M:%S.%SZ)
VALIDITY_END=$(date --date="+10 days" +%Y-%m-%dT%H:%M:%S.%SZ)
# Configuration for consumption of the license as set on Marketplace products
CONSUMPTION_CONFIG='{
"RenewType": "None",
"ProvisionalConfiguration": {
"MaxTimeToLiveInMinutes": 60
}
}'
# License's home Region
HOME_REGION=us-east-1
# License issuer's name
ISSUER=Self
# Run AWS CLI command to create a license
aws license-manager create-license \
--license-name "${LICENSE_NAME}" \
--product-name "${PRODUCT_NAME}" \
--product-sku "${PRODUCT_ID}" \
--issuer Name="${ISSUER}" \
--beneficiary "${BENEFICIARY_ACCOUNT_ID}" \
--validity 'Begin="'"${VALIDITY_START}"'",End="'"${VALIDITY_END}"'"' \
--entitlements "${ENTITLEMENTS}" \
--home-region "${HOME_REGION}" \
--region "${HOME_REGION}" \
--consumption-configuration "${CONSUMPTION_CONFIG}" \
--client-token $(uuidgen)
```
1. Grant the license using the AWS License Manager console. For more information, see [distribute an entitlement](https://docs.aws.amazon.com/license-manager/latest/userguide/granted-licenses.html#distribute-entitlement.) in the *License Manager User Guide*.
1. Sign in to the AWS account that acts as a buyer account where you will deploy and test your software. This must be a different AWS account from the AWS account that created and granted the license.
1. Go to the AWS License Manager console to accept and activate the granted licenses. For more information, see [manage your granted licenses](https://docs.aws.amazon.com/license-manager/latest/userguide/granted-licenses.html#manage-granted-licenses) in the *License Manager User Guide*.
1. Run the following command in your environment.
```
# The following example uses a key fingerprint that should match the test license you created.
# When checking out an actual AWS Marketplace created license, use the following fingerprint:
# aws:294406891311:AWS/Marketplace:issuer-fingerprint
aws license-manager checkout-license \
--product-sku \
--checkout-type PROVISIONAL \
--key-fingerprint "aws::Self:issuer-fingerprint" \
--entitlements "Name=ReadOnly,Value=1,Unit=Count" \
--client-token $(uuidgen)
```
The previous command uses `PROVISIONAL` as the value for the `CheckoutType` parameter. If the entitlement uses a drawdown license, use `PERPETUAL` for the value.
### License Manager API calls
To manage the licenses stored in the customer's License Manager account, your software can use the following API calls:
+ `GetLicense` – Gets the status of a purchased license on whether the license is expired or about to be expired to send a notification to the customer.
+ `CheckoutLicense` – Discovers licenses that the user has purchased. You can also use it to update the license quantity when the user has consumed some quantity of licenses. With `CheckoutLicense`, you can keep checking out the quantities of the licenses used by the customer. When the customer exhausts all the licenses, this call returns an error. For information about the suggested cadence to run `CheckoutLicense`, see [License renewals and upgrades](#lic-renew-upgrade).
+ `ExtendLicenseConsumption` – In case of floating dimensions, when the software check outs a license, it will return the license to the pool automatically after 60 minutes. If you want to extend the time the license remains checked out, your software can call `ExtendLicenseConsumption` to extend the license for another 60 minutes.
+ `CheckInLicense` – In case of floating dimensions, when you want to return the license to the entitlement pool, use `CheckInLicense`.
+ `ListReceivedLicenses` – Lists licenses purchased by the buyer.
## License renewals and upgrades
Customers can renew or upgrade their licenses on the AWS Marketplace Management Portal. After they make an additional purchase, AWS Marketplace generates a new version of the license that reflects the new entitlements. Your software reads the new entitlements using the same API calls. You don't have to do anything different in terms of License Manager Integration to handle renewals and upgrades.
Due to license renewals, upgrades, cancellations, and so on, we recommend that your product performs the `CheckoutLicense` API call at a regular cadence while the product is in use. By using the `CheckoutLicense` API operation at a regular cadence, the product can detect changes in entitlements such as upgrades and expiry.
We recommend that you perform the `CheckoutLicense` API call every 15 minutes.
# Receiving Amazon SNS notifications for AMI products on AWS Marketplace
To receive notifications about changes to customer subscriptions for your products, you can subscribe to the Amazon Simple Notification Service (Amazon SNS) topics for AWS Marketplace provided to you during product creation. For example, you can know when customers accept a private offer. [Amazon SNS topic: aws-mp-subscription-notification](#ami-sns-subscription-message-body) is an Amazon SNS topic that is available for AMI products. This topic notifies you when a buyer subscribes or unsubscribes to a product. This notification is available for hourly pricing models, including hourly and hourly with annual. For more information, see the following sections.
**Note**
During the product creation process, an Amazon SNS topic is created for your product. To subscribe to notifications, you need the Amazon Resource Name (ARN) of the Amazon SNS topic (for example, `arn:aws:sns:us-east-1:123456789012:aws-mp-subscription-notification-PRODUCTCODE`). The ARN is not available in the seller portal for server products. Contact the [AWS Marketplace operations team](https://aws.amazon.com/marketplace/management/contact-us) to request the ARN.
**Topics**
+ [Amazon SNS topic: aws-mp-subscription-notification](#ami-sns-subscription-message-body)
+ [Subscribing an Amazon SQS queue to the Amazon SNS topic](#subscribing-an-sqs-queue-to-an-sns-topic)
## Amazon SNS topic: aws-mp-subscription-notification
Each message in the `aws-mp-subscription-notification` topic for the `subscribe-success` and `subscribe-fail` action has the following format.
```
{
"action": "action-name",
"customer-identifier": " X01EXAMPLEX",
"product-code": "n0123EXAMPLEXXXXXXXXXXXX",
"offer-identifier": "offer-abcexample123"
}
```
The ** will vary depending on the notification. Possible actions are:
+ `subscribe-success`
+ `subscribe-fail`
+ `unsubscribe-pending`
+ `unsubscribe-success`
The `offer-identifier` is included in the notification only when the action is `subscribe-success` or `subscribe-fail`. It isn't included in notifications when the action is `unsubscribe-pending` or `unsubscribe-success`. For offers created before January 2024, this identifier is included in the notification only for private offers. For offers created in January 2024 and later, this identifier is included in notifications for all offers, including both private offers and public offers.
For information on offer types, see the response from [DescribeEntity API](https://docs.aws.amazon.com//marketplace/latest/APIReference/work-with-private-offers.html#describe-entity) or the offer visibility of an agreement in the [Agreements renewals dashboard](https://docs.aws.amazon.com//marketplace/latest/userguide/agreements-renewals-dashboard.html).
**Note**
For [DescribeEntity API](https://docs.aws.amazon.com//marketplace/latest/APIReference/work-with-private-offers.html#describe-entity), if you find an AWS account in the account targeting facet of targeting rule for that offer, it is a private offer. If there is not an AWS account in the account targeting facet of targeting rule for that offer, it is a public offer.
## Subscribing an Amazon SQS queue to the Amazon SNS topic
We recommend subscribing an Amazon SQS queue to the provided SNS topics. For detailed instructions on creating an SQS queue and subscribing the queue to a topic, see [ Subscribing an Amazon SQS queue to an Amazon SNS topic](https://docs.aws.amazon.com/sns/latest/dg/subscribe-sqs-queue-to-sns-topic.html) in the *Amazon Simple Notification Service Developer Guide*.
**Note**
You can only subscribe to AWS Marketplace SNS topics from the AWS account used to sell the products. However, you can forward the messages to a different account. For more information, see [Sending Amazon SNS messages to an Amazon SQS queue in a different account](https://docs.aws.amazon.com/sns/latest/dg/sns-send-message-to-sqs-cross-account.html) in the *Amazon Simple Notification Service Developer Guide*.
### Polling the SQS queue for notifications
After you subscribe your SQS queue to an SNS topic, the messages are stored in SQS. You must define a service that continually polls the queue, looks for messages, and handles them accordingly.
# AMI product checklist for AWS Marketplace
Before submitting your Amazon Machine Image (AMI) product to AWS, use this checklist to validate your submission. Following these requirements will help ensure an efficient publication process.
## Product usage
+ AMI is production-ready.
+ Product usage is not restricted by time or any other measurements.
+ AMI is compatible with the 1-click fulfillment experience.
+ Everything required to use the product is in the software, including client applications. Products that require external dependencies, such as software packages or client applications, follow the [Product usage policies](product-and-ami-policies.md#product-usage) that include proper disclosure.
+ AMI meets the mandatory [AMI-based product requirements for AWS Marketplace](product-and-ami-policies.md).
+ No additional license is required to use the product.
+ The buyer doesn't have to provide personally identifiable information (for example, their email address) to use the product.
## AMI preparation
+ Your product name and description must match the **Description** field of the AMI product that you are providing.
+ Uses Hardware Virtual Machine (HVM) virtualization and 64-bit architecture.
+ Product does not contain any known vulnerabilities, malware, or viruses.
+ Customers are able to access the instance over network and use administrative access.
+ No hardcoded secrets are present on the AMI. Examples of hardcoded secrets include default passwords for system users and services, private keys, and credentials.
+ No hardcoded SSH authorized public keys are present on the AMI.
+ The Test 'Add Version' validation test completes successfully with no issues.
## Windows AMIs
+ For Windows Server 2012 and later operating systems, your AMI uses the latest version of [EC2Launch v2](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2launch-v2-install.html).
+ If you're using EC2Launch v2, complete the following:
+ In [Amazon EC2Launch settings](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2launch-v2-settings.html#ec2launch-v2-ui), choose **Random** under **Set administrator account** to have an administrator password generated at runtime.
+ In [Amazon EC2Launch settings](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2launch-v2-settings.html#ec2launch-v2-ui), select **Re-enable and start SSM service after Sysprep**.
+ Add **UserData** to the [EC2 v2 task configuration](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2launch-v2-settings.html#ec2launch-v2-task-configuration).
+ For Windows Server 2012 and later versions, avoid using [EC2Config](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/UsingConfig_Install.html). If EC2Config is required, ensure that you use the latest version.
+ If you use EC2Config, enable the following parameters in the [settings files](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2config-service.html#UsingConfigXML_WinAMI) for your AMI:
+ `Ec2SetPassword`
+ `Ec2WindowsActivate`
+ `Ec2HandleUserData`
+ Ensure that there are no guest accounts or remote desktop users present.
## Linux AMIs
+ Remote login as superuser is prohibited.
+ Password-based remote access is prohibited.
## Product load form or Product tab
+ All required fields are completed.
+ All values are within specified character limits.
+ All URLs load without error.
+ The product image is at least 110 pixels wide and between a 1:1 and 2:1 ratio.
+ Pricing is specified for all enabled instance types (for hourly, hourly-based monthly pricing, and hourly-based annual pricing models).
+ Monthly pricing is specified (for hourly-based monthly and monthly pricing models).
# AMI-based product requirements for AWS Marketplace
AWS Marketplace maintains the following policies for all Amazon Machine Image (AMI) products and offerings. The policies in this section are intended to provide customers with a safe, secure, and trustworthy compute platform.
All products and their related metadata are reviewed when submitted to ensure they meet or exceed current AWS Marketplace policies. These policies are regularly updated to align with evolving security guidelines. AWS Marketplace continuously scans products to verify that existing listings continue to meet any changes to these requirements. If a product falls out of compliance, AWS Marketplace will contact the seller to update their product to meet new standards. In some cases, products might be temporarily made unavailable to new subscribers until issues are resolved. This process helps maintain the security and trustworthiness of the AWS Marketplace platform for all users.
Before submitting your product, we strongly recommend using the [Test 'Add Version'](https://aws.amazon.com/marketplace/management/products/server) feature in the AWS Marketplace Management Portal to ensure compliance with current policies.
**Topics**
+ [AMI product seller policies](#ami-product-seller-policies)
+ [Security policies](#ami-security)
+ [Architecture policies](#architecture)
+ [AMI product usage instructions](#ami-product-usage-instructions)
+ [AMI product version policies](#ami-product-version-policies)
+ [FPGA Product Requirements](#ami-fpga-product-requirements)
+ [Customer information policies](#customer-information)
+ [Product usage policies](#product-usage)
## AMI product seller policies
All AMIs must adhere to the following seller policies:
+ By default, AWS Marketplace sellers are limited to a maximum of 75 public AMI product listings. All sellers above their limit are subject to periodic performance review and may be required to restrict underperforming listings. AWS Marketplace may grant and revoke increases to this limit at its sole discretion.
## Security policies
### General policies
All AMIs must comply with the following policies:
+ AMIs must pass all security checks performed by the [AWS Marketplace AMI scanning tool](https://aws.amazon.com/marketplace/management/products/server), showing no known vulnerabilities or malware.
+ AMIs must use currently supported operating systems and software. Operating systems and software that reached their end of life are not allowed.
+ Password-based authentication for instance services is prohibited. This applies even if the password is generated, reset, or defined by the user at launch. Null and blank passwords are not allowed.
Exceptions:
+ Administrator passwords generated by `EC2Config/EC2Launch` on Windows instances.
+ Non-administrative access to host services (for example, web applications) in the absence of other authentication methods. If strong passwords are used, they must be randomly generated for each instance, used once by the service administrator for initial authentication, and changed immediately after first login.
+ AMI must not contain hardcoded secrets such as system user and service passwords (including hashed passwords), private keys, or credentials.
+ AMIs must not request AWS credentials to access AWS services. If your product requires access to AWS services, an instance should be assigned a minimally privileged AWS Identity and Access Management (IAM) role. Users can create roles manually or by using a CloudFormation template. When single-AMI launch is enabled for products with a CloudFormation delivery method, usage instructions must include clear guidance for creating minimally privileged IAM roles. For more information, see [Delivering your AMI-based product using AWS CloudFormation](https://docs.aws.amazon.com/marketplace/latest/userguide/cloudformation.html).
+ A seller must not have access to instances run by a customer. In case such access is required for support or other purpose, the customer can be instructed to explicitly enable it.
### SSH (Secure Shell) access policies
In addition to [general policies](#general-policies), AMIs providing SSH (Secure Shell) access must comply with the following security policies:
+ AMIs must not allow password-based authentication using SSH. To ensure this, in your `sshd_config` file, set `PasswordAuthentication` to `no`.
+ AMIs must disable password-based remote logins for superuser accounts. For more information, see [Disable password-based remote logins for the root user](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/building-shared-amis.html#public-amis-disable-password-logins-for-root).
+ AMIs must not contain authorized public keys for SSH access.
+ SSH on AMIs must be accessible to AWS Marketplace internal vetting procedures.
+ The SSH service must listen on the TCP port specified for AMI scanning. For more information, see [Add a new version](https://docs.aws.amazon.com/marketplace/latest/userguide/single-ami-versions.html#single-ami-adding-version).
+ SSH must be accessible from subnets `10.0.0.0/16` and `10.2.0.0/16` on the IP address assigned by Amazon Elastic Compute Cloud (Amazon EC2) at instance launch.
### Policies for AMIs based on Linux and other Unix-like operating systems
In addition to [general policies](#general-policies), AMIs based on Linux and other Unix-like operating systems must comply with the following security policies:
+ AMIs must allow users to get fully privileged access (for example, to allow `sudo` access).
### Policies for Windows-based AMIs
In addition to [general policies](#general-policies), Windows-based AMIs must comply with the following security policies:
+ AMIs must not contain guest accounts.
+ Only administrator accounts may be granted remote desktop access to an instance.
+ Windows AMIs must generate administrator passwords by enabling these options in [EC2Launch](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/ec2launch-v2.html) (or [EC2Config](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/ec2config-service.html) for Windows 2016 and older):
+ `Ec2SetPassword`
+ `Ec2WindowsActivate`
+ `Ec2HandleUserData`
+ AMIs must be available to automated vetting. At least one of the following requirements must be implemented:
+ (Recommended option) SSM agent is installed and have administrative permissions and outbound network access.
+ [Windows Remote Management (WinRM) service](https://learn.microsoft.com/en-us/windows/win32/winrm/portal) is enabled, listens on TCP port `5985`, and is accessible from subnets `10.0.0.0/16` and `10.2.0.0/16` on the IP address assigned by Amazon Elastic Compute Cloud (Amazon EC2) at instance launch.
+ [Microsoft Server Message Block (SMB) Protocol and Common Internet File System (CIFS) Protocol service](https://learn.microsoft.com/en-us/windows/win32/fileio/microsoft-smb-protocol-and-cifs-protocol-overview) is enabled, listens on TCP ports `139` and `445` and is accessible from subnets `10.0.0.0/16` and `10.2.0.0/16` on the IP address assigned by Amazon Elastic Compute Cloud (Amazon EC2) at instance launch.
## Architecture policies
All AMIs must adhere to the following architecture policies:
+ Source AMIs for AWS Marketplace must be provided in the US East (N. Virginia) Region.
+ AMIs must use HVM virtualization.
+ AMIs must use x86-64 or 64-bit ARM architecture.
+ AMIs must be AMIs backed by Amazon Elastic Block Store (Amazon EBS). We don't support AMIs backed by Amazon Simple Storage Service.
+ AMIs must not use encrypted EBS snaphots.
+ AMIs must not use encrypted file systems.
+ AMIs must be built so that they can run in all AWS Regions and are Region-agnostic. AMIs built differently for different Regions aren't allowed.
## AMI product usage instructions
When creating usage instructions for your AMI product, please follow the steps and guidance located in [Creating AMI and container product usage instructions for AWS Marketplace](ami-container-product-usage-instructions.md).
## AMI product version policies
AWS Marketplace automates the version management experience for AWS customers and sellers using S-AMI, AMI with CloudFormation template, and container products. With automated version archival, any product version that has been restricted by a seller for longer than two years is automatically archived. Archived versions are no longer available to launch from AWS Marketplace for new customers, however existing users can continue to use the archived version through launch templates and Amazon EC2 Auto Scaling groups by specifying the AMI ID. Any archived version that has not been used to launch a new instances in the past 13 months is deleted. Once an archived version is deleted, it is no longer available to launch for new or existing users.
## FPGA Product Requirements
In addition to standard AMI product requirements, FPGA products must meet the following requirements:
+ AFI IDs must be owned by your AWS Marketplace seller account.
+ Each product version supports a maximum of 15 AFI IDs, allowing you to provide multiple FPGA configurations while maintaining manageable product complexity.
+ AFI IDs must be created and registered in the US East (N. Virginia) Region.
+ Regional availability is limited to regions where F2 instance types are supported.
+ The IAM access role provided during version creation has permissions to share the provided AFIs with AWS Marketplace. For more details about the required permissions, see [Giving AWS Marketplace access to your FPGA images](https://docs.aws.amazon.com/marketplace/latest/userguide/single-ami-marketplace-ami-access.html#single-ami-marketplace-afi-access).
## Customer information policies
All AMIs must adhere to the following customer information policies:
+ Software must not collect or export customer data without the customer's knowledge and express consent except as required by BYOL (Bring Your Own License). Applications that collect or export customer data must follow these guidelines:
+ The collection of the customer data must be self-service, automated, and secure. Buyers must not need to wait for sellers to approve to deploy the software.
+ Collection of customer data must be consistent with your agreements with AWS, including but not limited to, the [AWS Marketplace Terms and Conditions](https://aws.amazon.com/legal/seller-terms/), [AWS Service Terms](https://aws.amazon.com/service-terms/), [AWS Privacy Notice](https://aws.amazon.com/privacy/) and [AWS Customer Agreement](https://aws.amazon.com/agreement/).
+ Payment information must not be collected.
## Product usage policies
All AMIs must adhere to the following product usage policies:
+ Products must not restrict access to the product or product functionality by time, number of users, or other restrictions. Beta and prerelease products, or products whose sole purpose is to offer trial or evaluation functionality, are not supported. Developer, Community, and BYOL editions of commercial software are supported, provided an equivalent paid version is also available in AWS Marketplace.
+ All AMIs must be compatible with either the Launch from Website experience or AMI-based delivery through AWS CloudFormation. For Launch from Website, the AMI can't require customer or user data at instance creation to function correctly.
+ AMIs and their software must be deployable in a self-service manner and must not require additional payment methods or costs. Applications that require external dependencies on deployment must follow these guidelines:
+ The requirement must be disclosed in the description or the usage instructions of the listing. For example, *This product requires an internet connection to deploy properly. The following packages are downloaded on deployment: .*
+ Sellers are responsible for the use of and ensuring the availability and security of all external dependencies.
+ If the external dependencies are no longer available, the product must be removed from AWS Marketplace as well.
+ The external dependencies must not require additional payment methods or costs.
+ AMIs that require an ongoing connection to external resources not under the direct control of the buyer—for example, external APIs or AWS services managed by the seller or a third party—must follow these guidelines:
+ The requirement must be disclosed in the description or the usage instructions of the listing. For example, *This product requires an ongoing internet connection. The following ongoing external services are required to properly function: .*
+ Sellers are responsible for the use of and ensuring the availability and security of all external resources.
+ If the external resources are no longer available, the product must be removed from AWS Marketplace as well.
+ The external resources must not require additional payment methods or costs and the setup of the connection must be automated.
+ Product software and metadata must not contain language that redirects users to other cloud platforms, additional products, or upsell services that aren't available in AWS Marketplace.
+ If your product is an add-on to another product or another ISV’s product, your product description must indicate that it extends the functionality of the other product and that without it, your product has very limited utility. For example, *This product extends the functionality of and without it, this product has very limited utility. Please note that might require its own license for full functionality with this listing.*