github.com/ratanraj/packer@v1.3.2/website/source/docs/post-processors/amazon-import.html.md (about)

     1  ---
     2  description: |
     3      The Packer Amazon Import post-processor takes an OVA artifact from various
     4      builders and imports it to an AMI available to Amazon Web Services EC2.
     5  layout: docs
     6  page_title: 'Amazon Import - Post-Processors'
     7  sidebar_current: 'docs-post-processors-amazon-import'
     8  ---
     9  
    10  # Amazon Import Post-Processor
    11  
    12  Type: `amazon-import`
    13  
    14  The Packer Amazon Import post-processor takes an OVA artifact from various builders and imports it to an AMI available to Amazon Web Services EC2.
    15  
    16  ~> This post-processor is for advanced users. It depends on specific IAM roles inside AWS and is best used with images that operate with the EC2 configuration model (eg, cloud-init for Linux systems). Please ensure you read the [prerequisites for import](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/VMImportPrerequisites.html) before using this post-processor.
    17  
    18  ## How Does it Work?
    19  
    20  The import process operates making a temporary copy of the OVA to an S3 bucket, and calling an import task in EC2 on the OVA file. Once completed, an AMI is returned containing the converted virtual machine. The temporary OVA copy in S3 can be discarded after the import is complete.
    21  
    22  The import process itself run by AWS includes modifications to the image uploaded, to allow it to boot and operate in the AWS EC2 environment. However, not all modifications required to make the machine run well in EC2 are performed. Take care around console output from the machine, as debugging can be very difficult without it. You may also want to include tools suitable for instances in EC2 such as `cloud-init` for Linux.
    23  
    24  Further information about the import process can be found in AWS's [EC2 Import/Export Instance documentation](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instances_of_your_vm.html).
    25  
    26  ## Configuration
    27  
    28  There are some configuration options available for the post-processor. They are
    29  segmented below into two categories: required and optional parameters.
    30  Within each category, the available configuration keys are alphabetized.
    31  
    32  Required:
    33  
    34  -   `access_key` (string) - The access key used to communicate with AWS. [Learn
    35      how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
    36  
    37  -   `region` (string) - The name of the region, such as `us-east-1` in which to upload the OVA file to S3 and create the AMI. A list of valid regions can be obtained with AWS CLI tools or by consulting the AWS website.
    38  
    39  -   `s3_bucket_name` (string) - The name of the S3 bucket where the OVA file will be copied to for import. This bucket must exist when the post-processor is run.
    40  
    41  -   `secret_key` (string) - The secret key used to communicate with AWS. [Learn
    42      how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
    43  
    44  Optional:
    45  
    46  -   `ami_description` (string) - The description to set for the resulting
    47      imported AMI. By default this description is generated by the AMI import
    48      process.
    49  
    50  -   `ami_groups` (array of strings) - A list of groups that have access to
    51      launch the imported AMI. By default no groups have permission to launch the
    52      AMI. `all` will make the AMI publicly accessible. AWS currently doesn't
    53      accept any value other than "all".
    54  
    55  -   `ami_name` (string) - The name of the ami within the console. If not
    56      specified, this will default to something like `ami-import-sfwerwf`.
    57      Please note, specifying this option will result in a slightly longer
    58      execution time.
    59  
    60  -   `ami_users` (array of strings) - A list of account IDs that have access to
    61      launch the imported AMI. By default no additional users other than the user
    62      importing the AMI has permission to launch it.
    63  
    64  -   `custom_endpoint_ec2` (string) - This option is useful if you use a cloud
    65      provider whose API is compatible with aws EC2. Specify another endpoint
    66      like this `https://ec2.custom.endpoint.com`.
    67  
    68  -   `license_type` (string) - The license type to be used for the Amazon Machine
    69      Image (AMI) after importing. Valid values: `AWS` or `BYOL` (default).
    70      For more details regarding licensing, see
    71      [Prerequisites](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/VMImportPrerequisites.html)
    72      in the VM Import/Export User Guide.
    73  
    74  -   `mfa_code` (string) - The MFA [TOTP](https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm)
    75      code. This should probably be a user variable since it changes all the time.
    76  
    77  -   `profile` (string) - The profile to use in the shared credentials file for
    78      AWS. See Amazon's documentation on [specifying
    79      profiles](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-profiles)
    80      for more details.
    81  
    82  -   `role_name` (string) - The name of the role to use when not using the default role, 'vmimport'
    83  
    84  -   `s3_key_name` (string) - The name of the key in `s3_bucket_name` where the
    85      OVA file will be copied to for import. If not specified, this will default
    86      to "packer-import-{{timestamp}}.ova". This key (i.e., the uploaded OVA) will
    87      be removed after import, unless `skip_clean` is `true`.
    88  
    89  -   `skip_clean` (boolean) - Whether we should skip removing the OVA file uploaded to S3 after the
    90      import process has completed. "true" means that we should leave it in the S3 bucket, "false" means to clean it out. Defaults to `false`.
    91  
    92  -   `skip_region_validation` (boolean) - Set to true if you want to skip
    93      validation of the region configuration option. Default `false`.
    94  
    95  -   `tags` (object of key/value strings) - Tags applied to the created AMI and
    96      relevant snapshots.
    97  
    98  -   `token` (string) - The access token to use. This is different from the
    99      access key and secret key. If you're not sure what this is, then you
   100      probably don't need it. This will also be read from the `AWS_SESSION_TOKEN`
   101      environmental variable.
   102  
   103  ## Basic Example
   104  
   105  Here is a basic example. This assumes that the builder has produced an OVA artifact for us to work with, and IAM roles for import exist in the AWS account being imported into.
   106  
   107  ``` json
   108  {
   109    "type": "amazon-import",
   110    "access_key": "YOUR KEY HERE",
   111    "secret_key": "YOUR SECRET KEY HERE",
   112    "region": "us-east-1",
   113    "s3_bucket_name": "importbucket",
   114    "license_type": "BYOL",
   115    "tags": {
   116      "Description": "packer amazon-import {{timestamp}}"
   117    }
   118  }
   119  ```
   120  
   121  ## VMWare Example
   122  
   123  This is an example that uses `vmware-iso` builder and exports the `.ova` file using ovftool.
   124  
   125  ``` json
   126  "post-processors" : [
   127       [
   128          {
   129            "type": "shell-local",
   130            "inline": [ "/usr/bin/ovftool <packer-output-directory>/<vmware-name>.vmx <packer-output-directory>/<vmware-name>.ova" ]
   131          },
   132          {
   133             "files": [
   134               "<packer-output-directory>/<vmware-name>.ova"
   135             ],
   136             "type": "artifice"
   137          },
   138          {
   139            "type": "amazon-import",
   140            "access_key": "YOUR KEY HERE",
   141            "secret_key": "YOUR SECRET KEY HERE",
   142            "region": "us-east-1",
   143            "s3_bucket_name": "importbucket",
   144            "license_type": "BYOL",
   145            "tags": {
   146              "Description": "packer amazon-import {{timestamp}}"
   147            }
   148         }
   149      ]
   150    ]
   151  ```
   152  
   153  ## Troubleshooting Timeouts
   154  The amazon-import feature can take a long time to upload and convert your OVAs
   155  into AMIs; if you find that your build is failing because you have exceeded your
   156  max retries or find yourself being rate limited, you can override the max
   157  retries and the delay in between retries by setting the environment variables
   158   `AWS_MAX_ATTEMPTS` and `AWS_POLL_DELAY_SECONDS` on the machine running the
   159   Packer build. By default, the waiter that waits for your image to be imported
   160   from s3 will retry for up to an hour: it retries up to 720 times with a 5
   161   second delay in between retries.
   162  
   163   This is dramatically higher than many of our other waiters, to account for how
   164   long this process can take.
   165  
   166  -&gt; **Note:** Packer can also read the access key and secret access key from
   167  environmental variables. See the configuration reference in the section above
   168  for more information on what environmental variables Packer will look for.
   169  
   170  This will take the OVA generated by a builder and upload it to S3. In this case, an existing bucket called `importbucket` in the `us-east-1` region will be where the copy is placed. The key name of the copy will be a default name generated by packer.
   171  
   172  Once uploaded, the import process will start, creating an AMI in the "us-east-1" region with a "Description" tag applied to both the AMI and the snapshots associated with it. Note: the import process does not allow you to name the AMI, the name is automatically generated by AWS.
   173  
   174  After tagging is completed, the OVA uploaded to S3 will be removed.