Create a package

Open the Amazon Systems Manager console at https://console.amazonaws.cn/systems-manager/.

In the navigation pane, choose Distributor.

On the Distributor home page, choose Create package, and then choose Simple.

On the Create package page, enter a name for your package. Package names can contain letters, numbers, periods, dashes, and underscores. The name should be generic enough to apply to all versions of the package attachments, but specific enough to identify the purpose of the package.

(Optional) For Version name, enter a version name. Version names can be a maximum of 512 characters, and can't contain special characters.

For Location, choose a bucket by using the bucket name and prefix or by using the bucket URL.

For Upload software, choose Add software, and then navigate to installable software files with .rpm, .msi, or .deb extensions. If the file name contains spaces, the upload fails. You can upload more than one software file in a single action.

For Target platform, verify that the target operating system platform shown for each installable file is correct. If the operating system shown isn't correct, choose the correct operating system from the dropdown list.

For the Simple package creation workflow, because you upload each installable file only once, extra steps are required to instruct Distributor to target a single file at multiple operating systems. For example, if you upload an installable software file named Logtool_v1.1.1.rpm, you must change some defaults in the Simple workflow to target the same software at both Amazon Linux and Ubuntu operating systems. When targeting multiple platforms, do one of the following.

For Platform version, verify that the operating system platform version shown is either _any, a major release version followed by a wildcard (7.*), or the exact operating system release version to which you want your software to apply. For more information about specifying an operating system platform version, see step 4 in Step 2: Create the JSON package manifest.

For Architecture, choose the correct processor architecture for each installable file from the dropdown list. For more information about supported processor architectures, see Supported package platforms and architectures.

(Optional) Expand Scripts, and review the scripts that Distributor generates for your installable software.

(Optional) To provide an update script for use with in-place updates, expand Scripts, choose the Update script tab, and enter your update script commands.

Systems Manager doesn't generate update scripts on your behalf.

To add more installable software files, choose Add software. Otherwise, go to the next step.

(Optional) Expand Manifest, and review the JSON package manifest that Distributor generates for your installable software. If you changed any information about your software since you began this procedure, such as platform version or target platform, choose Generate manifest to show the updated package manifest.

You can edit the manifest manually if you want to target a software installable at more than one operating system, as described in step 8. For more information about editing the manifest, see Step 2: Create the JSON package manifest.

Choose Create package.

Add the schema version to your manifest. In this release, the schema version is always 2.0.

{ "schemaVersion": "2.0",

Add a user-defined package version to your manifest. This is also the value of Version name that you specify when you add your package to Distributor. It becomes part of the Amazon Systems Manager document that Distributor creates when you add your package. You also provide this value as an input in the AWS-ConfigureAWSPackage document to install a version of the package other than the latest. A version value can contain letters, numbers, underscores, hyphens, and periods, and be a maximum of 128 characters in length. We recommend that you use a human-readable package version to make it easier for you and other administrators to specify exact package versions when you deploy. The following is an example.

"version": "1.0.1",

(Optional) Add a publisher name. The following is an example.

"publisher": "MyOrganization",

Add packages. The "packages" section describes the platforms, release versions, and architectures supported by the .zip files in your package. For more information, see Supported package platforms and architectures.

The platform-version can be the wildcard value, _any. Use it to indicate that a .zip file supports any release of the platform. You can also specify a major release version followed by a wildcard so all minor versions are supported, for example 7.*. If you choose to specify a platform-version value for a specific operating system version, be sure that it matches the exact release version of the operating system AMI that you're targeting. The following are suggested resources for getting the correct value of the operating system.

"packages": {
    "platform": {
      "platform-version": {
        "architecture": {
          "file": ".zip-file-name-1.zip"
        }
      }
    },
    "another-platform": {
      "platform-version": {
        "architecture": {
          "file": ".zip-file-name-2.zip"
        }
      }
    },
    "another-platform": {
      "platform-version": {
        "architecture": {
          "file": ".zip-file-name-3.zip"
        }
      }
    }
  }

The following is an example. In this example, the operating system platform is amazon, the supported release version is 2016.09, the architecture is x86_64, and the .zip file that supports this platform is test.zip.

{
    "amazon": {
        "2016.09": {
            "x86_64": {
                "file": "test.zip"
            }
        }
    }
},

You can add the _any wildcard value to indicate that the package supports all versions of the parent element. For example, to indicate that the package is supported on any release version of Amazon Linux, your package statement should be similar to the following. You can use the _any wildcard at the version or architecture levels to support all versions of a platform, or all architectures in a version, or all versions and all architectures of a platform.

{
    "amazon": {
        "_any": {
            "x86_64": {
                "file": "test.zip"
            }
        }
    }
},

The following example adds _any to show that the first package, data1.zip, is supported for all architectures of Amazon Linux 2016.09. The second package, data2.zip, is supported for all releases of Amazon Linux, but only for managed nodes with x86_64 architecture. Both the 2016.09 and _any versions are entries under amazon. There is one platform (Amazon Linux), but different supported versions, architectures, and associated .zip files.

{
    "amazon": {
        "2016.09": {
            "_any": {
                "file": "data1.zip"
            }
        },
        "_any": {
            "x86_64": {
                "file": "data2.zip"
            }
        }
    }
}

You can refer to a .zip file more than once in the "packages" section of the manifest, if the .zip file supports more than one platform. For example, if you have a .zip file that supports both Red Hat Enterprise Linux 7.x versions and Amazon Linux, you have two entries in the "packages" section that point to the same .zip file, as shown in the following example.

{
    "amazon": {
        "2018.03": {
            "x86_64": {
                "file": "test.zip"
            }
        }
    },
    "redhat": {
        "7.*": {
            "x86_64": {
                "file": "test.zip"
            }
        }
    }
},

Add the list of .zip files that are part of this package from step 4. Each file entry requires the file name and sha256 hash value checksum. Checksum values in the manifest must match the sha256 hash value in the zipped assets to prevent the package installation from failing.

To get the exact checksum from your installables, you can run the following commands. On Linux, run shasum -a 256 file-name.zip or openssl dgst -sha256 file-name.zip. On Windows, run the Get-FileHash -Path path-to-.zip-file cmdlet in PowerShell.

The "files" section of the manifest includes one reference to each of the .zip files in your package.

"files": {
        "test-agent-x86.deb.zip": {
            "checksums": {
                "sha256": "EXAMPLE2706223c7616ca9fb28863a233b38e5a23a8c326bb4ae241dcEXAMPLE"
            }
        },
        "test-agent-x86_64.deb.zip": {
            "checksums": {
                "sha256": "EXAMPLE572a745844618c491045f25ee6aae8a66307ea9bff0e9d1052EXAMPLE"
            }
        },
        "test-agent-x86_64.nano.zip": {
            "checksums": {
                "sha256": "EXAMPLE63ccb86e830b63dfef46995af6b32b3c52ce72241b5e80c995EXAMPLE"
            }
        },
        "test-agent-rhel5-x86.nano.zip": {
            "checksums": {
                "sha256": "EXAMPLE13df60aa3219bf117638167e5bae0a55467e947a363fff0a51EXAMPLE"
            }
        },
        "test-agent-x86.msi.zip": {
            "checksums": {
                "sha256": "EXAMPLE12a4abb10315aa6b8a7384cc9b5ca8ad8e9ced8ef1bf0e5478EXAMPLE"
            }
        },
        "test-agent-x86_64.msi.zip": {
            "checksums": {
                "sha256": "EXAMPLE63ccb86e830b63dfef46995af6b32b3c52ce72241b5e80c995EXAMPLE"
            }
        },
        "test-agent-rhel5-x86.rpm.zip": {
            "checksums": {
                "sha256": "EXAMPLE13df60aa3219bf117638167e5bae0a55467e947a363fff0a51EXAMPLE"
            }
        },
        "test-agent-rhel5-x86_64.rpm.zip": {
            "checksums": {
                "sha256": "EXAMPLE7ce8a2c471a23b5c90761a180fd157ec0469e12ed38a7094d1EXAMPLE"
            }
        }
    }

After you add your package information, save and close the manifest file.

Copy or move all .zip archive files that you specified in the manifest to a folder or directory. Don't zip the folder or directory you move your .zip archive files and manifest file to.

Create a bucket or choose an existing bucket. For more information, see Create a Bucket in the Amazon Simple Storage Service Getting Started Guide. For more information about how to run an Amazon CLI command to create a bucket, see mb in the Amazon CLI Command Reference.

Upload the folder or directory to the bucket. For more information, see Add an Object to a Bucket in the Amazon Simple Storage Service Getting Started Guide. If you plan to paste your JSON manifest into the Amazon Systems Manager console, don't upload the manifest. For more information about how to run an Amazon CLI command to upload files to a bucket, see mv in the Amazon CLI Command Reference.

On the bucket's home page, choose the folder or directory that you uploaded. If you uploaded your files to a subfolder in a bucket, be sure to note the subfolder (also known as a prefix). You need the prefix to add your package to Distributor.

Open the Amazon Systems Manager console at https://console.amazonaws.cn/systems-manager/.

In the navigation pane, choose Distributor.

On the Distributor home page, choose Create package, and then choose Advanced.

On the Create package page, enter a name for your package. Package names can contain letters, numbers, periods, dashes, and underscores. The name should be generic enough to apply to all versions of the package attachments, but specific enough to identify the purpose of the package.

For Version name, enter the exact value of the version entry in your manifest file.

For S3 bucket name, choose the name of the bucket to which you uploaded your .zip files and manifest in Step 3: Upload the package and manifest to an Amazon S3 bucket.

For S3 key prefix, enter the subfolder of the bucket where your .zip files and manifest are stored.

For Manifest, choose Extract from package to use a manifest that you have uploaded to the Amazon S3 bucket with your .zip files.

(Optional) If you didn't upload your JSON manifest to the S3 bucket where you stored your .zip files, choose New manifest. You can author or paste the entire manifest in the JSON editor field. For more information about how to create the JSON manifest, see Step 2: Create the JSON package manifest.

When you're finished with the manifest, choose Create package.

Wait for Distributor to create your package from your .zip files and manifest. Depending on the number and size of packages you are adding, this can take a few minutes. Distributor automatically redirects you to the Package details page for the new package, but you can choose to open this page yourself after the software is uploaded. The Package details page doesn't show all information about your package until Distributor finishes the package creation process. To stop the upload and package creation process, choose Cancel.

To use the Amazon CLI to create a package, run the following command, replacing package-name with the name of your package and path-to-manifest-file with the file path for your JSON manifest file. DOC-EXAMPLE-BUCKET is the URL of the Amazon S3 bucket where the entire package is stored. When you run the create-document command in Distributor, you specify the Package value for --document-type.

If you didn't add your manifest file to the Amazon S3 bucket, the --content parameter value is the file path to the JSON manifest file.

aws ssm create-document \
    --name "package-name" \
    --content file://path-to-manifest-file \
    --attachments Key="SourceUrl",Values="DOC-EXAMPLE-BUCKET" \
    --version-name version-value-from-manifest \
    --document-type Package

The following is an example.

aws ssm create-document \
    --name "ExamplePackage" \
    --content file://path-to-manifest-file \
    --attachments Key="SourceUrl",Values="https://s3.amazonaws.com.cn/DOC-EXAMPLE-BUCKET/ExamplePackage" \
    --version-name 1.0.1 \
    --document-type Package

Verify that your package was added and show the package manifest by running the following command, replacing package-name with the name of your package. To get a specific version of the document (not the same as the version of a package), you can add the --document-version parameter.

aws ssm get-document \
    --name "package-name"