Building and testing your Image Builder component Copying the component ARN Creating AWS Marketplace IAM policies Creating the AWS Marketplace IAM role Prepare your Image Builder component listing Publishing your Image Builder component product listing Updating Image Builder component product information Adding a new version to an existing Image Builder component product Updating information about an existing version Restricting an Image Builder component product version Monitoring a change set Securing software downloads

Work with EC2 Image Builder component products

As an AWS Marketplace seller, you can list AMI-based products delivered to AWS Marketplace buyers using EC2 Image Builder components. To create your component and publish an AWS Marketplace listing, proceed sequentially through the following sections.

Topics

Building and testing your Image Builder component
Copying the component ARN
Creating AWS Marketplace IAM policies
Creating the AWS Marketplace IAM role
Prepare your Image Builder component listing
Publishing your Image Builder component product listing
Updating Image Builder component product information
Adding a new version to an existing Image Builder component product
Updating information about an existing version
Restricting an Image Builder component product version
Monitoring a change set
Securing software downloads

Building and testing your Image Builder component

Build and test your component on Image Builder. For instructions, refer to Develop custom components for your Image Builder image in the Image Builder User Guide. When creating your component using Image Builder, ensure that you do the following:

The component and all of its underlying dependencies, such as an Amazon Simple Storage Service (Amazon S3) bucket, secrets, or parameters, must be created in the US East (N. Virginia) (us-east-1) AWS Region.
Include supported architecture and any software dependencies in the component description.
Test your component in your AWS account by creating an image pipeline and deploying the AMI created by the pipeline.
If your component contains instructions to copy binaries, packages, or files from an S3 bucket, use the S3Download action module. In the S3Download module, for source, enter the static location of your file in the S3 bucket. The following example copies a binary from an S3 bucket as part of the component installation.
```
- name: DownloadMyFile
    action: S3Download
    inputs:
      - source: s3://amzn-s3-demo-source-bucket/path/to/package.zip
        destination: C:\myfolder\package.zip
```
Components can ingest files of up to 2 GB when using the S3Download action.
If your component uses parameters, ensure that all parameters have default values. For example, if you have a parameter named region, ensure that you have a valid default value such as us-east-1. These default values are for AWS Marketplace processing and testing. Testing may fail if you do not include default values.
If your component uses AWS Secrets Manager, Parameter Store, or a capability of AWS Systems Manager to store parameters, do the following:
- To retrieve values as a step in your component, embed AWS Command Line Interface commands in your YAML configuration file.
- Create a corresponding entry in Secrets Manager or Parameter Store in your AWS account. Use the default key and provide a valid value that will assist in building the component during the AWS Marketplace testing process. For example, say you have a parameter called saas_token with a default value of token that uses Parameter Store. In this case, create a key-value pair in Parameter Store. Use token as the key. For the value, enter a valid SaaS token for your application.
  
  Note that values stored in your AWS Marketplace seller account will only be used for AWS Marketplace testing purposes. These values will not be shared with buyers.
- AWS Marketplace automatically generates Amazon Machine Images (AMIs) for your component across all compatible operating system versions you choose during the component creation process. When building your component, choose at least one compatible operating system version. Validate your component's compatibility with all chosen operating system versions by using EC2 Image Builder pipelines to create and test AMIs.

Copying the component ARN

After creating and testing the component on Image Builder, copy and save the component ARN. You will use the ARN when you publish the product listing using the AWS Marketplace Catalog API.

To copy the Image Builder component ARN

Sign in to the AWS Management Console and open the Image Builder console at https://console.aws.amazon.com/imagebuilder/.
In the left navigation bar, under Saved resources, choose Components.
On the Components page, for Filter owner, choose Owned by me.
Choose the component name.
On the component detail page, in the Summary section, copy the ARN.

Creating AWS Marketplace IAM policies

Create the following IAM policies to grant AWS Marketplace access to your Image Builder component and related resources like Amazon S3 buckets and secrets. Use the example policies provided. You attach these policies to an AWS Marketplace IAM role. For help creating policies, see Creating policies using the JSON editor in the IAM User Guide.

Image Builder get-component policy, to allow AWS Marketplace to access your component on Image Builder. This policy is required. Name the policy mp_ib_ingest.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "imagebuilder:GetComponent",
            "Resource": "*"
        }
    ]
}

Amazon S3 read-access policy, to allow AWS Marketplace to retrieve binaries from an S3 bucket. This policy is only required if your component uses the S3Download action module and stores associated binaries in an S3 bucket. Name the policy mp_ib_s3_read_only.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ListObjectsInBucket",
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::bucket_name"
            ]
        },
        {
            "Sid": "ReadObjectsInBucket",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:GetObjectAttributes"
            ],
            "Resource": [
                "arn:aws:s3:::bucket_name/*"
            ]
        }
    ]
}

Secrets Manager read-access policy, to allow AWS Marketplace to retrieve secrets stored in Secrets Manager. This policy is only required if your component uses Secrets Manager to store secrets. Name the policy mp_ib_sm_read_only. To restrict the policy to just your secret, replace the * in the Resource section with your secret.
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}
```
Parameter Store read-access policy, to allow AWS Marketplace to retrieve secrets stored in Parameter Store. This policy is only required if your component uses Parameter Store to store secrets. Name the policy mp_ib_ssm_parameter_read_only. To restrict the policy to just your secret, replace the * in the Resource section with your secret.
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Statement1",
            "Effect": "Allow",
            "Action": [
                "ssm:getParameter"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}
```

Creating the AWS Marketplace IAM role

Use the following procedure to create an AWS Marketplace IAM role with policies to grant AWS Marketplace access to your component and its dependencies.

To create the AWS Marketplace IAM role

Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.
In the left navigation bar, choose Roles.
Choose Create role.
Select Custom trust policy.

Enter the following statement:


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Statement1",
            "Effect": "Allow",
            "Principal": {
                "Service": "assets.marketplace.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Choose Next.
Add the Image Builder get-component policy you created previously. The get-component policy is required. Add the relevant policies for S3, Secrets Manager, and Parameter Store if your component uses these AWS services.
Choose Next.
Enter a role name, such as MPEC2IBIngestion.
Choose Create role.

Copy AWS Marketplace IAM role ARN

After creating the AWS Marketplace IAM role, copy and save the role ARN. You will use the ARN when publishing the listing using the AWS Marketplace Catalog API.

To copy the AWS Marketplace IAM role ARN

In the IAM console, in the left navigation bar, choose Roles.
Choose the AWS Marketplace IAM role you created previously, such as MPEC2IBIngestion.
On the role detail page, in the Summary section, copy the ARN.

Prepare your Image Builder component listing

Before publishing your AWS Marketplace listing, ensure that you have the following information ready:

Product metadata – Metadata includes the product logo, product title, End User License agreement, supported instance types, and AWS Region.
Pricing information – You can offer your product for free, at an hourly rate, or at an hourly rate with an initial free trial period. Bring your own license (BYOL) is not supported.
Component details – Details include the component Amazon Resource Number (ARN), usage details, and AWS Identity and Access Management (IAM) role that AWS Marketplace will assume to process your component.

Publishing your Image Builder component product listing

This topic contains instructions to publish your EC2 Image Builder component listing on AWS Marketplace using the AWS Marketplace Catalog API.

Prerequisites

Ensure that you have the following before publishing your Image Builder component product listing:

Registration as a seller in AWS Marketplace. For more information, refer to Register as an AWS Marketplace seller.
An IAM user with AWSMarketplaceSellerFullAccess permission.
A publicly accessible Amazon Simple Storage Service (Amazon S3) bucket to host your company logo and EULA, if used in your component. You will enter the URL for the S3 bucket in your ChangeSet JSON file.
AWS Command Line Interface (AWS CLI). For more information, refer to What is the AWS Command Line Interface? in the AWS Command Line Interface User Guide.

Creating an Image Builder component product on AWS Marketplace

To create an EC2 Image Builder component product on AWS Marketplace using the Catalog API, refer to Create a product.

Updating Image Builder component product information

You can update information about a Image Builder component product on the AWS Marketplace Management Portal.

To update Image Builder component product information

Open the AWS Marketplace Management Portal and sign in to your seller account.
On the Products menu, choose Server.
On the Server products page, select the product.
On the product detail page, on the Request changes menu, choose the item that corresponds to the information you want to update.
After submitting any changes, the request will appear on the Requests tab in "Under review" status, and will change to "Succeeded" once completed.

Adding a new version to an existing Image Builder component product

You can add a new version to an Image Builder component product on AWS Marketplace using the AWS Marketplace Catalog API.

To add a new version

From the AWS Marketplace Management Portal, obtain the Product ID.
1. Open the AWS Marketplace Management Portal and sign in to your seller account.
2. On the Products menu, choose Server.
3. On the Server products page, select the product.
4. In the Product summary, copy the Product ID.

Using the following code example, create a changeset file in JSON format. In the example, replace your-product-ID with the product ID you obtained in step 1. Replace new-version-name with your version title. Replace new-delivery-option-title with your delivery option title.


[
    {
        "ChangeType": "AddDeliveryOptions",
        "Entity": {
            "Identifier": "your-product-ID",
            "Type": "AmiProduct@1.0"
        },
        "DetailsDocument": {
            "Version": {
                "VersionTitle": "new-version-name",
                "ReleaseNotes": "Release notes goes here."
            },
            "DeliveryOptions": [
                {
                    "DeliveryOptionTitle": "new title",
                    "Details": {
                        "Ec2ImageBuilderComponentDeliveryOptionDetails": {
                            "UsageInstructions": "Test usage instructions for IB",
                            "AccessRoleArn": "arn:aws:iam::123456789:role/sample",
                            "ComponentArn": "arn:aws:imagebuilder:us-east-1:123456789:component/sample/2.0.0/1"
                        }
                    }
                }
            ]
        }
    }
]

Save the changeset file with the name addIBversion.json.

In your terminal or AWS CloudShell, run the following command:


aws marketplace-catalog start-change-set --catalog AWSMarketplace --region us-east-1 --change-set file://addIBversion.json

The start-change-set command will return a ChangeSetId value. To monitor a change set, see Monitoring a change set.

Asynchronous Errors

The following errors are specific to AddDeliveryOptions actions in the AWS Marketplace Catalog API. These errors are returned when you call DescribeChangeSet after a change set is processing. For more information about using DescribeChangeSet to get the status of a change request, see Working with change sets.

Note

The following error codes are specific to the Image Builder delivery method. For existing error messages on fields such as Usage Instructions, Recommended Instance type, and AccessRoleArn, see Add a new version.

Error code	Error message
ASSET_NOT_FOUND	`Check if [component arn] exists in [account-id] AWS account and the AccessARN provided [ARN] has permissions to share this Image Builder component with AWS Marketplace.`
ASSET_NOT_FOUND	`The specified S3 link [x] within the component[x] does not exist. Provide a valid S3 link within the component.`
DUPLICATE_COMPONENT_NAME	`The component name [x] already exists within the same version. Provide a different component name.`
DUPLICATE_COMPONENT_NAME	`The component name [x] you provided is already in use by a different product. Provide a different component name.`
DUPLICATE_COMPONENT_ARN	`The component Arn [x] must be different from Component Arn used in other delivery options of the same version of this product.`
DUPLICATE_COMPONENT_ARN	`The component ARN [x] must be different from component ARN used in other versions of this product.`
SCAN_ERROR	`Fix security vulnerability [y] on Component [x].`
ASSET_ACCESS_EXCEPTION	`We don't have the necessary permissions to read the contents from the specified S3 bucket[x]. Ensure the S3 bucket has the appropriate read permissions.`
ASSET_ACCESS_EXCEPTION	`We don't have the necessary permissions to read the contents of the specified component ARN[x]. Ensure the component ARN has the appropriate read permissions.`
ASSET_ACCESS_EXCEPTION	`We don't have the necessary permissions to read the contents of the specified package URI [x]. Ensure the package URI has the appropriate read permissions.`
ASSET_ACCESS_EXCEPTION	`Failed to read from the HTTP source [x]. Verify that the provided HTTP source is correct.`
INVALID_IMAGE_BUILDER_COMPONENT_PACKAGE	`Component assets exceed the size limit for ingestion. Reduce the size of S3/web downloads or eliminate unnecessary downloads to proceed.`
INVALID_IMAGE_BUILDER_COMPONENT_PACKAGE	`Component assets are taking too long to ingest. Ensure that your network connection is stable and has adequate bandwidth.`
TOO_MANY_IMAGE_BUILDER_COMPONENTS	`Max of 5 unique component names are supported per product, restrict the additional delivery option.`
INCOMPLETE_SELLER_PUBLIC_PROFILE	`Your seller public profile is not complete. Complete your public profile before adding versions to the product.`
INVALID_DESCRIPTION	`The description is missing. Provide a description with fewer than 1024 characters in component [x].`
INVALID_COMPONENT_NAME	`Provide a component name with fewer than [x] characters.`
INVALID_SUPPORTED_OS_VERSION	`The OS version is missing. Provide a valid supported OS version in component [x].`
INVALID_PATH_FORMAT	`Step [STEP_NAME] in phase [PHASE_NAME] is not allowed to use S3 or web URLs for the InstallMSI/UninstallMSI actions. Ensure that the path specified is a valid local path accessible from the system executing the action.`
INCOMPATIBLE_OS_TYPE	`The specified component OS type[x] is not compatible with the platform of the base image. Provide an OS type that is compatible with the base image.`
ASSET_ACCESS_EXCEPTION	`We don't have the necessary permissions to read the contents from the specified SSM parameter [x]. Ensure that the IAM access role provided in the API input has the required read permissions.`
ASSET_ACCESS_EXCEPTION	`We don't have the necessary permissions to read the contents from the specified SecretsManager secret [x]. Ensure that the IAM access role provided in the API input has the required read permissions.`
INVALID_IB_COMPONENT_PARAMETER	`Unable to parse the SSM parameter in input [x] for component [y].`
INVALID_IB_COMPONENT_PARAMETER	`Unable to parse the SecretsManager secret in input [x] for component [y].`
MISSING_IB_COMPONENT_PARAMETER	`Parameter not found in component [x] for input [y]`
INVALID_IB_COMPONENT_PARAMETER	`Provide a default value for parameter [x] in component [y].`
FAILED_LAUNCH_TEST	`The launch test for component [x] has failed. Error message: [z]`
SSHAuthFailedForUserAndKeypair	`Unable to log into the instance with OS default username [X].`
INVALID_IB_COMPONENT	`A component build phase is required. Add a valid build phase to component [x]`
DUPLICATE_VERSION_TITLE	`The version title must be different from any other version titles of this product.`
INVALID_VERSION_TITLE	`Remove spaces before the trademark symbol.`
INVALID_VERSION_TITLE	`Remove unsupported characters: [x, y, z]`
INVALID_VERSION_TITLE	`Remove spaces from the beginning of the version title.`
INVALID_VERSION_TITLE	`Provide version title with fewer than [x] characters.`
INVALID_RELEASE_NOTES	`Remove spaces before the trademark symbol.`
INVALID_RELEASE_NOTES	`Remove unsupported characters: [x, y, z]`
INVALID_RELEASE_NOTES	`Remove spaces from the beginning of release notes.`
INVALID_RELEASE_NOTES	`Provide release notes with fewer than (x) characters.`
INVALID_USAGE_INSTRUCTIONS	`Remove spaces before the trademark symbol.`
INVALID_USAGE_INSTRUCTIONS	`Remove unsupported characters: [x, y, z]`
INVALID_USAGE_INSTRUCTIONS	`Provide usage instructions with fewer than (x) characters.`
DUPLICATE_DELIVERY_OPTION_TITLES	`Provide unique delivery option title.`
INVALID_DELIVERY_OPTION_TITLES	`Delivery option title already exists, retry with a different title.`

Updating information about an existing version

To update information about an existing version

From the AWS Marketplace Management Portal, obtain the Product ID.
1. Open the AWS Marketplace Management Portal and sign in to your seller account.
2. On the Products menu, choose Server.
3. On the Server products page, select the product.
4. In the Product summary, copy the Product ID.
In your terminal, run the following command. In the command, replace your-product-ID with the ID you obtained in step 1.
```
aws marketplace-catalog describe-entity --catalog AWSMarketplace --region us-east-1 --entity-id 'your-product-ID'
```
In the output returned, go to the DetailsDocument, Versions section. Copy the DeliveryOptions, Id value for the version you want to update.

Using the following code example, create a changeset file in JSON format. In the example, replace your-product-ID with the product ID you obtained in step 1. Replace your-release-notes with your release notes. Replace your-delivery-option-ID with the ID of the delivery option you obtained in step 3. Replace your-usage-instructions with your usage instructions.


[
    {
        "ChangeType": "UpdateDeliveryOptions",
        "Entity": {
            "Identifier": "your-product-ID",
            "Type": "AmiProduct@1.0"
        },
        "DetailsDocument": {
            "Version": {
                "ReleaseNotes": "your-release-notes"
            },
            "DeliveryOptions": [
                {
                    "Id": "your-delivery-option-ID",
                    "Details": {
                        "Ec2ImageBuilderComponentDeliveryOptionDetails": {
                            "UsageInstructions": "your-usage-instructions"
                        }
                    }
                }
            ]
        }
    }
]

Save the changeset file with the name updateVersionInfo.json.

In your terminal or AWS CloudShell, run the following command:


aws marketplace-catalog start-change-set --catalog AWSMarketplace --region us-east-1 --change-set file://updateVersionInfo.json

The start-change-set command will return a ChangeSetId value. To monitor a change set, see Monitoring a change set.

Restricting an Image Builder component product version

Restricting a version makes it unavailable to buyers. You can restrict a version of your Image Builder component product on AWS Marketplace using the AWS Marketplace Catalog API. You must keep at least one version of your product unrestricted on AWS Marketplace. You can't restrict access to the only public version.

To update information about an existing version

From the AWS Marketplace Management Portal, obtain the Product ID.
1. Open the AWS Marketplace Management Portal and sign in to your seller account.
2. On the Products menu, choose Server.
3. On the Server products page, select the product.
4. In the Product summary, copy the Product ID.
In your terminal, run the following command. In the command, replace your-product-ID with the ID you obtained in step 1.
```
aws marketplace-catalog describe-entity --catalog AWSMarketplace --region us-east-1 --entity-id 'your-product-ID'
```
In the output returned, go to the DetailsDocument, Versions section. Copy the DeliveryOptions, Id value for the version you want to update.

Using the following code example, create a changeset file in JSON format. In the example, replace your-product-ID with the product ID you obtained in step 1. Replace your-delivery-option-ID with the ID of the delivery option you obtained in step 3.


[
    {
        "ChangeType": "RestrictDeliveryOptions",
        "Entity": {
            "Identifier": "your-product-ID",
            "Type": "AmiProduct@1.0"
        },
        "DetailsDocument": {
            "DeliveryOptionIds": [
                "your-delivery-option-ID"
            ]
        }
    }
]

Save the changeset file with the name restrictec2ibversion.json.

In your terminal or AWS CloudShell, run the following command:


aws marketplace-catalog start-change-set --catalog AWSMarketplace --region us-east-1 --change-set file://restrictec2ibversion.json

The start-change-set command will return a ChangeSetId value. To monitor a change set, see Monitoring a change set.

Monitoring a change set

The start-change-set command will return a ChangeSetId value. You can monitor change set progress in the following ways:

Run the following command in your terminal. In the command. replace changeset-ID with the ChangeSetId value returned by the start-change-set command.
```
aws marketplace-catalog describe-change-set ‐‐catalog AWSMarketplace ‐‐change-set-id changesetID
```
View the request status on the Requests tab in the AWS Marketplace Management Portal.

Securing software downloads

To safeguard ISV software intellectual property and ensure stable, consistent software delivery to AWS Marketplace buyers, AWS Marketplace automatically parses S3Download and WebDownload action modules in your component. The referenced files are then securely stored in a private Amazon S3 bucket managed by AWS Marketplace. To opt out of this ingestion process and manage software downloads independently, run bash scripts that use the wget or curl download commands.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Work with AMI-based products

Work with container-based products