Work with EC2 Image Builder component products - AWS Marketplace
Building and testing your Image Builder componentCopying the component ARNCreating AWS Marketplace IAM policiesCreating the AWS Marketplace IAM rolePrepare your Image Builder component listingPublishing your Image Builder component product listingUpdating Image Builder component product informationAdding a new version to an existing Image Builder component productUpdating information about an existing versionRestricting an Image Builder component product versionMonitoring a change set

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.

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

  1. Sign in to the AWS Management Console and open the Image Builder console at https://console.aws.amazon.com/imagebuilder/.

  2. In the left navigation bar, under Saved resources, choose Components.

  3. On the Components page, for Filter owner, choose Owned by me.

  4. Choose the component name.

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

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the left navigation bar, choose Roles.

  3. Choose Create role.

  4. Select Custom trust policy.

  5. Enter the following statement:

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

  6. Choose Next.

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

  8. Choose Next.

  9. Enter a role name, such as MPEC2IBIngestion.

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

  1. In the IAM console, in the left navigation bar, choose Roles.

  2. Choose the AWS Marketplace IAM role you created previously, such as MPEC2IBIngestion.

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

  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. On the product detail page, on the Request changes menu, choose the item that corresponds to the information you want to update.

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

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

  2. 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"
                        }
                    }
                }
            ]
        }
    }
]

  3. Save the changeset file with the name addIBversion.json.

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

Updating information about an existing version

To update information about an existing version

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

  2. 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'

  3. In the output returned, go to the DetailsDocument, Versions section. Copy the DeliveryOptions, Id value for the version you want to update.

  4. 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"
                        }
                    }
                }
            ]
        }
    }
]

  5. Save the changeset file with the name updateVersionInfo.json.

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

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

  2. 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'

  3. In the output returned, go to the DetailsDocument, Versions section. Copy the DeliveryOptions, Id value for the version you want to update.

  4. 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"
            ]
        }
    }
]

  5. Save the changeset file with the name restrictec2ibversion.json.

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