iSharkFly-Docs
/
packer-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

aws: rewrap struct comments for documentation generation

This commit is contained in:
Adrien Delorme 2019-06-06 16:45:37 +02:00
parent ee716d3f7e
commit 8e857d64f1
7 changed files with 229 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
builder/amazon/common/access_config.go
View File

@ -86,33 +86,39 @@ type AccessConfig struct {
// environmental variable.
Token string `mapstructure:"token" required:"false"`
session *session.Session
// Get credentials from Hashicorp Vault's aws
// secrets engine. You must already have created a role to use. For more
// information about generating credentials via the Vault engine, see the
// Vault
// docs.
// Get credentials from Hashicorp Vault's aws secrets engine. You must
// already have created a role to use. For more information about
// generating credentials via the Vault engine, see the [Vault
// docs.](https://www.vaultproject.io/api/secret/aws/index.html#generate-credentials)
// If you set this flag, you must also set the below options:
// - `name` (string) - Required. Specifies the name of the role to generate
// credentials against. This is part of the request URL.
// - `engine_name` (string) - The name of the aws secrets engine. In the
// Vault docs, this is normally referred to as "aws", and Packer will
// default to "aws" if `engine_name` is not set.
// - `role_arn` (string)- The ARN of the role to assume if credential\_type
// on the Vault role is assumed\_role. Must match one of the allowed role
// ARNs in the Vault role. Optional if the Vault role only allows a single
// AWS role ARN; required otherwise.
// - `ttl` (string) - Specifies the TTL for the use of the STS token. This
// is specified as a string with a duration suffix. Valid only when
// credential\_type is assumed\_role or federation\_token. When not
// specified, the default\_sts\_ttl set for the role will be used. If that
// is also not set, then the default value of 3600s will be used. AWS
// places limits on the maximum TTL allowed. See the AWS documentation on
// the DurationSeconds parameter for AssumeRole (for assumed\_role
// credential types) and GetFederationToken (for federation\_token
// credential types) for more details.
// - `name` (string) - Required. Specifies the name of the role to generate
// credentials against. This is part of the request URL.
// - `engine_name` (string) - The name of the aws secrets engine. In the
// Vault docs, this is normally referred to as "aws", and Packer will
// default to "aws" if `engine_name` is not set.
// - `role_arn` (string)- The ARN of the role to assume if credential\_type
// on the Vault role is assumed\_role. Must match one of the allowed role
// ARNs in the Vault role. Optional if the Vault role only allows a single
// AWS role ARN; required otherwise.
// - `ttl` (string) - Specifies the TTL for the use of the STS token. This
// is specified as a string with a duration suffix. Valid only when
// credential\_type is assumed\_role or federation\_token. When not
// specified, the default\_sts\_ttl set for the role will be used. If that
// is also not set, then the default value of 3600s will be used. AWS
// places limits on the maximum TTL allowed. See the AWS documentation on
// the DurationSeconds parameter for AssumeRole (for assumed\_role
// credential types) and GetFederationToken (for federation\_token
// credential types) for more details.
//
// Example:
// `json { "vault_aws_engine": { "name": "myrole", "role_arn": "myarn",
// ``` json
// {
// "vault_aws_engine": {
// "name": "myrole",
// "role_arn": "myarn",
// "ttl": "3600s"
// }
// }
// ```
VaultAWSEngine VaultAWSEngineOptions `mapstructure:"vault_aws_engine" required:"false"`
getEC2Connection func() ec2iface.EC2API

34
builder/amazon/common/ami_config.go
View File

@ -59,13 +59,12 @@ type AMIConfig struct {
// documentation on enabling enhanced
// networking](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enhanced-networking.html#enabling_enhanced_networking).
AMIENASupport *bool `mapstructure:"ena_support" required:"false"`
// Enable enhanced networking (SriovNetSupport but
// not ENA) on HVM-compatible AMIs. If true, add
// ec2:ModifyInstanceAttribute to your AWS IAM policy. Note: you must make
// sure enhanced networking is enabled on your instance. See Amazon's
// documentation on enabling enhanced
// networking.
// Default false.
// Enable enhanced networking (SriovNetSupport but not ENA) on
// HVM-compatible AMIs. If true, add `ec2:ModifyInstanceAttribute` to your
// AWS IAM policy. Note: you must make sure enhanced networking is enabled
// on your instance. See [Amazon's documentation on enabling enhanced
// networking](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enhanced-networking.html#enabling_enhanced_networking).
// Default `false`.
AMISriovNetSupport bool `mapstructure:"sriov_support" required:"false"`
// Force Packer to first deregister an existing
// AMI if one with the same name already exists. Default false.
@ -87,20 +86,21 @@ type AMIConfig struct {
// This field is validated by Packer, when using an alias, you will have to
// prefix `kms_key_id` with `alias/`.
AMIKmsKeyId string `mapstructure:"kms_key_id" required:"false"`
// a map of regions to copy the ami to, along with the custom kms key id
// (alias or arn) to use for encryption for that region. Keys must match
// the regions provided in ami_regions. If you just want to encrypt using a
// default ID, you can stick with kms_key_id and ami_regions. If you want a
// regions to copy the ami to, along with the custom kms key id (alias or
// arn) to use for encryption for that region. Keys must match the regions
// provided in `ami_regions`. If you just want to encrypt using a default
// ID, you can stick with `kms_key_id` and `ami_regions`. If you want a
// region to be encrypted with that region's default key ID, you can use an
// empty string "" instead of a key id in this map. (e.g. "us-east-1": "")
// However, you cannot use default key IDs if you are using this in
// conjunction with snapshot_users -- in that situation you must use custom
// keys. For valid formats see KmsKeyId in the AWS API docs - CopyImage.
// empty string `""` instead of a key id in this map. (e.g. `"us-east-1":
// ""`) However, you cannot use default key IDs if you are using this in
// conjunction with `snapshot_users` -- in that situation you must use
// custom keys. For valid formats see *KmsKeyId* in the [AWS API docs -
// CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html).
AMIRegionKMSKeyIDs map[string]string `mapstructure:"region_kms_key_ids" required:"false"`
// Tags to apply to snapshot.
// They will override AMI tags if already applied to snapshot. This is a
// template engine, see Build template
// data for more information.
// [template engine](../templates/engine.html), see [Build template
// data](#build-template-data) for more information.
SnapshotTags TagMap `mapstructure:"snapshot_tags" required:"false"`
// A list of account IDs that have
// access to create volumes from the snapshot(s). By default no additional

80
builder/amazon/common/block_device.go
View File

@ -69,27 +69,75 @@ type BlockDevices struct {
}
type AMIBlockDevices struct {
// Add one or
// more block device
// mappings
// Add one or more [block device
// mappings](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html)
// to the AMI. These will be attached when booting a new instance from your
// AMI. If this field is populated, and you are building from an existing source image,
// the block device mappings in the source image will be overwritten. This means you
// must have a block device mapping entry for your root volume, root_volume_size,
// and root_device_name. `Your options here may vary depending on the type of VM
// you use. The block device mappings allow for the following configuration:
// AMI. To add a block device during the Packer build see
// `launch_block_device_mappings` below. Your options here may vary
// depending on the type of VM you use. The block device mappings allow for
// the following configuration:
// - `delete_on_termination` (boolean) - Indicates whether the EBS volume is
// deleted on instance termination. Default `false`. **NOTE**: If this
// value is not explicitly set to `true` and volumes are not cleaned up by
// an alternative method, additional volumes will accumulate after every
// build.
//
// - `device_name` (string) - The device name exposed to the instance (for
// example, `/dev/sdh` or `xvdh`). Required for every device in the block
// device mapping.
//
// - `encrypted` (boolean) - Indicates whether or not to encrypt the volume.
// By default, Packer will keep the encryption setting to what it was in
// the source image. Setting `false` will result in an unencrypted device,
// and `true` will result in an encrypted one.
//
// - `iops` (number) - The number of I/O operations per second (IOPS) that
// the volume supports. See the documentation on
// [IOPs](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html)
// for more information
//
// - `kms_key_id` (string) - The ARN for the KMS encryption key. When
// specifying `kms_key_id`, `encrypted` needs to be set to `true`. For
// valid formats see *KmsKeyId* in the [AWS API docs -
// CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html).
//
// - `no_device` (boolean) - Suppresses the specified device included in the
// block device mapping of the AMI.
//
// - `snapshot_id` (string) - The ID of the snapshot.
//
// - `virtual_name` (string) - The virtual device name. See the
// documentation on [Block Device
// Mapping](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_BlockDeviceMapping.html)
// for more information.
//
// - `volume_size` (number) - The size of the volume, in GiB. Required if
// not specifying a `snapshot_id`.
//
// - `volume_type` (string) - The volume type. `gp2` for General Purpose
// (SSD) volumes, `io1` for Provisioned IOPS (SSD) volumes, `st1` for
// Throughput Optimized HDD, `sc1` for Cold HDD, and `standard` for
// Magnetic volumes.
AMIMappings []BlockDevice `mapstructure:"ami_block_device_mappings" required:"false"`
}
type LaunchBlockDevices struct {
// Add one
// or more block devices before the Packer build starts. If you add instance
// store volumes or EBS volumes in addition to the root device volume, the
// created AMI will contain block device mapping information for those
// volumes. Amazon creates snapshots of the source instance's root volume and
// any other EBS volumes described here. When you launch an instance from this
// new AMI, the instance automatically launches with these additional volumes,
// and will restore them from snapshots taken from the source instance.
// Add one or more block devices before the Packer build starts. If you add
// instance store volumes or EBS volumes in addition to the root device
// volume, the created AMI will contain block device mapping information
// for those volumes. Amazon creates snapshots of the source instance's
// root volume and any other EBS volumes described here. When you launch an
// instance from this new AMI, the instance automatically launches with
// these additional volumes, and will restore them from snapshots taken
// from the source instance.
//
// In addition to the fields available in ami_block_device_mappings, you
// may optionally use the following field:
// - `omit_from_artifact` (boolean) - If true, this block device will not
// be snapshotted and the created AMI will not contain block device mapping
// information for this volume. If false, the block device will be mapped
// into the final created AMI. Set this option to true if you need a block
// device mounted in the surrogate AMI but not in the final created AMI.
LaunchMappings []BlockDevice `mapstructure:"launch_block_device_mappings" required:"false"`
}

95
builder/amazon/common/run_config.go
View File

@ -149,14 +149,14 @@ type RunConfig struct {
// `security_group_ids`. Any filter described in the docs for
// [DescribeSecurityGroups](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSecurityGroups.html)
// is valid.
//
// `security_group_ids` take precedence over this.
SecurityGroupFilter SecurityGroupFilterOptions `mapstructure:"security_group_filter" required:"false"`
// Tags to apply to the instance
// that is launched to create the AMI. These tags are not applied to the
// resulting AMI unless they're duplicated in tags. This is a template
// engine, see Build template
// data for more information.
// Tags to apply to the instance that is *launched* to create the AMI.
// These tags are *not* applied to the resulting AMI unless they're
// duplicated in `tags`. This is a [template
// engine](/docs/templates/engine.html), see [Build template
// data](#build-template-data) for more information.
RunTags map[string]string `mapstructure:"run_tags" required:"false"`
// The ID (not the name) of the security
// group to assign to the instance. By default this is not set and Packer will
@ -173,8 +173,47 @@ type RunConfig struct {
// AMI with a root volume snapshot that you have access to. Note: this is not
// used when from_scratch is set to true.
SourceAmi string `mapstructure:"source_ami" required:"true"`
// Filters used to populate the source_ami
// Filters used to populate the `source_ami`
// field. Example:
//
// ``` json
// {
// "source_ami_filter": {
// "filters": {
// "virtualization-type": "hvm",
// "name": "ubuntu/images/\*ubuntu-xenial-16.04-amd64-server-\*",
// "root-device-type": "ebs"
// },
// "owners": ["099720109477"],
// "most_recent": true
// }
// }
// ```
//
// This selects the most recent Ubuntu 16.04 HVM EBS AMI from Canonical. NOTE:
// This will fail unless *exactly* one AMI is returned. In the above example,
// `most_recent` will cause this to succeed by selecting the newest image.
//
// - `filters` (map of strings) - filters used to select a `source_ami`.
// NOTE: This will fail unless *exactly* one AMI is returned. Any filter
// described in the docs for
// [DescribeImages](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html)
// is valid.
//
// - `owners` (array of strings) - Filters the images by their owner. You
// may specify one or more AWS account IDs, "self" (which will use the
// account whose credentials you are using to run Packer), or an AWS owner
// alias: for example, `amazon`, `aws-marketplace`, or `microsoft`. This
// option is required for security reasons.
//
// - `most_recent` (boolean) - Selects the newest created image when true.
// This is most useful for selecting a daily distro build.
//
// You may set this in place of `source_ami` or in conjunction with it. If you
// set this in conjunction with `source_ami`, the `source_ami` will be added
// to the filter. The provided `source_ami` must meet all of the filtering
// criteria provided in `source_ami_filter`; this pins the AMI returned by the
// filter, but will cause Packer to fail if the `source_ami` does not exist.
SourceAmiFilter AmiFilterOptions `mapstructure:"source_ami_filter" required:"false"`
// a list of acceptable instance
// types to run your build on. We will request a spot instance using the max
@ -203,8 +242,39 @@ type RunConfig struct {
// Requires spot_price to be
// set. This tells Packer to apply tags to the spot request that is issued.
SpotTags map[string]string `mapstructure:"spot_tags" required:"false"`
// Filters used to populate the subnet_id field.
// Filters used to populate the `subnet_id` field.
// Example:
//
// ``` json
// {
// "subnet_filter": {
// "filters": {
// "tag:Class": "build"
// },
// "most_free": true,
// "random": false
// }
// }
// ```
//
// This selects the Subnet with tag `Class` with the value `build`, which has
// the most free IP addresses. NOTE: This will fail unless *exactly* one
// Subnet is returned. By using `most_free` or `random` one will be selected
// from those matching the filter.
//
// - `filters` (map of strings) - filters used to select a `subnet_id`.
// NOTE: This will fail unless *exactly* one Subnet is returned. Any
// filter described in the docs for
// [DescribeSubnets](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSubnets.html)
// is valid.
//
// - `most_free` (boolean) - The Subnet with the most free IPv4 addresses
// will be used if multiple Subnets matches the filter.
//
// - `random` (boolean) - A random Subnet will be used if multiple Subnets
// matches the filter. `most_free` have precendence over this.
//
// `subnet_id` take precedence over this.
SubnetFilter SubnetFilterOptions `mapstructure:"subnet_filter" required:"false"`
// If using VPC, the ID of the subnet, such as
// subnet-12345def, where Packer will launch the EC2 instance. This field is
@ -212,10 +282,13 @@ type RunConfig struct {
SubnetId string `mapstructure:"subnet_id" required:"false"`
// The name of the temporary key pair to
// generate. By default, Packer generates a name that looks like
// packer_<UUID>, where <UUID> is a 36 character unique identifier.
// `packer_<UUID>`, where &lt;UUID&gt; is a 36 character unique identifier.
TemporaryKeyPairName string `mapstructure:"temporary_key_pair_name" required:"false"`
// A list of IPv4
// CIDR blocks to be authorized access to the instance, when packer is creating a temporary security group.
// A list of IPv4 CIDR blocks to be authorized access to the instance, when
// packer is creating a temporary security group.
//
// The default is [`0.0.0.0/0`] (i.e., allow any IPv4 source). This is only
// used when `security_group_id` or `security_group_ids` is not specified.
TemporarySGSourceCidrs []string `mapstructure:"temporary_security_group_source_cidrs" required:"false"`
// User data to apply when launching the instance. Note
// that you need to be careful about escaping characters due to the templates

9
builder/amazon/ebs/builder.go
View File

@ -1,3 +1,5 @@
//go:generate struct-markdown
// The amazonebs package contains a packer.Builder implementation that
// builds AMIs for Amazon EC2.
//
@ -28,7 +30,12 @@ type Config struct {
awscommon.AMIConfig `mapstructure:",squash"`
awscommon.BlockDevices `mapstructure:",squash"`
awscommon.RunConfig `mapstructure:",squash"`
VolumeRunTags awscommon.TagMap `mapstructure:"run_volume_tags"`
// Tags to apply to the volumes that are *launched* to create the AMI.
// These tags are *not* applied to the resulting AMI unless they're
// duplicated in `tags`. This is a [template
// engine](/docs/templates/engine.html), see [Build template
// data](#build-template-data) for more information.
VolumeRunTags awscommon.TagMap `mapstructure:"run_volume_tags"`
ctx interpolate.Context
}

17
builder/amazon/ebssurrogate/builder.go
View File

@ -27,10 +27,19 @@ type Config struct {
awscommon.RunConfig `mapstructure:",squash"`
awscommon.BlockDevices `mapstructure:",squash"`
awscommon.AMIConfig `mapstructure:",squash"`
// A block device mapping
// describing the root device of the AMI. This looks like the mappings in
// ami_block_device_mapping, except with an additional field:
RootDevice RootBlockDevice `mapstructure:"ami_root_device" required:"true"`
// A block device mapping describing the root device of the AMI. This looks
// like the mappings in `ami_block_device_mapping`, except with an
// additional field:
//
// - `source_device_name` (string) - The device name of the block device on
// the source instance to be used as the root device for the AMI. This
// must correspond to a block device in `launch_block_device_mapping`.
RootDevice RootBlockDevice `mapstructure:"ami_root_device" required:"true"`
// Tags to apply to the volumes that are *launched* to create the AMI.
// These tags are *not* applied to the resulting AMI unless they're
// duplicated in `tags`. This is a [template
// engine](/docs/templates/engine.html), see [Build template
// data](#build-template-data) for more information.
VolumeRunTags awscommon.TagMap `mapstructure:"run_volume_tags"`
// what architecture to use when registering the
// final AMI; valid options are "x86_64" or "arm64". Defaults to "x86_64".

27
builder/amazon/ebsvolume/builder.go
View File

@ -27,22 +27,19 @@ type Config struct {
// Add the block device
// mappings to the AMI. The block device mappings allow for keys:
VolumeMappings []BlockDevice `mapstructure:"ebs_volumes" required:"false"`
// Enable enhanced networking (ENA but not
// SriovNetSupport) on HVM-compatible AMIs. If set, add
// ec2:ModifyInstanceAttribute to your AWS IAM policy. If false, this will
// disable enhanced networking in the final AMI as opposed to passing the
// setting through unchanged from the source. Note: you must make sure
// enhanced networking is enabled on your instance. See Amazon's
// documentation on enabling enhanced
// networking.
// Enable enhanced networking (ENA but not SriovNetSupport) on
// HVM-compatible AMIs. If set, add ec2:ModifyInstanceAttribute to your AWS
// IAM policy. If false, this will disable enhanced networking in the final
// AMI as opposed to passing the setting through unchanged from the source.
// Note: you must make sure enhanced networking is enabled on your
// instance. See Amazon's documentation on enabling enhanced networking.
AMIENASupport *bool `mapstructure:"ena_support" required:"false"`
// Enable enhanced networking (SriovNetSupport but
// not ENA) on HVM-compatible AMIs. If true, add
// ec2:ModifyInstanceAttribute to your AWS IAM policy. Note: you must make
// sure enhanced networking is enabled on your instance. See Amazon's
// documentation on enabling enhanced
// networking.
// Default false.
// Enable enhanced networking (SriovNetSupport but not ENA) on
// HVM-compatible AMIs. If true, add `ec2:ModifyInstanceAttribute` to your
// AWS IAM policy. Note: you must make sure enhanced networking is enabled
// on your instance. See [Amazon's documentation on enabling enhanced
// networking](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enhanced-networking.html#enabling_enhanced_networking).
// Default `false`.
AMISriovNetSupport bool `mapstructure:"sriov_support" required:"false"`
launchBlockDevices awscommon.BlockDevices