From ae23f891e17cf2930de6a652f0c04691a8df1b62 Mon Sep 17 00:00:00 2001 From: Wilken Rivera Date: Fri, 7 Aug 2020 16:34:38 -0400 Subject: [PATCH] post-processor/googlecompute-export: Update documentation (#9727) * Add markdown generator to post-processor config * Add HCL2 example --- .../googlecompute-export/post-processor.go | 49 ++++++++---- .../post-processor.hcl2spec.go | 6 +- .../post-processors/googlecompute-export.mdx | 76 +++++++++---------- .../Config-not-required.mdx | 32 ++++++++ .../googlecompute-export/Config-required.mdx | 4 + 5 files changed, 113 insertions(+), 54 deletions(-) create mode 100644 website/pages/partials/post-processor/googlecompute-export/Config-not-required.mdx create mode 100644 website/pages/partials/post-processor/googlecompute-export/Config-required.mdx diff --git a/post-processor/googlecompute-export/post-processor.go b/post-processor/googlecompute-export/post-processor.go index 70434543c..c00a2e353 100644 --- a/post-processor/googlecompute-export/post-processor.go +++ b/post-processor/googlecompute-export/post-processor.go @@ -1,3 +1,4 @@ +//go:generate struct-markdown //go:generate mapstructure-to-hcl2 -type Config package googlecomputeexport @@ -22,20 +23,42 @@ import ( type Config struct { common.PackerConfig `mapstructure:",squash"` + //The JSON file containing your account credentials. + //If specified, the account file will take precedence over any `googlecompute` builder authentication method. AccountFile string `mapstructure:"account_file"` - IAP bool `mapstructure-to-hcl2:",skip"` - - DiskSizeGb int64 `mapstructure:"disk_size"` - DiskType string `mapstructure:"disk_type"` - MachineType string `mapstructure:"machine_type"` - Network string `mapstructure:"network"` - Paths []string `mapstructure:"paths"` - Subnetwork string `mapstructure:"subnetwork"` - VaultGCPOauthEngine string `mapstructure:"vault_gcp_oauth_engine"` - Zone string `mapstructure:"zone"` - ServiceAccountEmail string `mapstructure:"service_account_email"` - account *jwt.Config - ctx interpolate.Context + //The size of the export instances disk. + //The disk is unused for the export but a larger size will increase `pd-ssd` read speed. + //This defaults to `200`, which is 200GB. + DiskSizeGb int64 `mapstructure:"disk_size"` + //Type of disk used to back the export instance, like + //`pd-ssd` or `pd-standard`. Defaults to `pd-ssd`. + DiskType string `mapstructure:"disk_type"` + //The export instance machine type. Defaults to `"n1-highcpu-4"`. + MachineType string `mapstructure:"machine_type"` + //The Google Compute network id or URL to use for the export instance. + //Defaults to `"default"`. If the value is not a URL, it + //will be interpolated to `projects/((builder_project_id))/global/networks/((network))`. + //This value is not required if a `subnet` is specified. + Network string `mapstructure:"network"` + //A list of GCS paths where the image will be exported. + //For example `'gs://mybucket/path/to/file.tar.gz'` + Paths []string `mapstructure:"paths" required:"true"` + //The Google Compute subnetwork id or URL to use for + //the export instance. Only required if the `network` has been created with + //custom subnetting. Note, the region of the subnetwork must match the + //`zone` in which the VM is launched. If the value is not a URL, + //it will be interpolated to + //`projects/((builder_project_id))/regions/((region))/subnetworks/((subnetwork))` + Subnetwork string `mapstructure:"subnetwork"` + //The zone in which to launch the export instance. Defaults + //to `googlecompute` builder zone. Example: `"us-central1-a"` + Zone string `mapstructure:"zone"` + IAP bool `mapstructure-to-hcl2:",skip"` + VaultGCPOauthEngine string `mapstructure:"vault_gcp_oauth_engine"` + ServiceAccountEmail string `mapstructure:"service_account_email"` + + account *jwt.Config + ctx interpolate.Context } type PostProcessor struct { diff --git a/post-processor/googlecompute-export/post-processor.hcl2spec.go b/post-processor/googlecompute-export/post-processor.hcl2spec.go index dc752016a..ea5f04585 100644 --- a/post-processor/googlecompute-export/post-processor.hcl2spec.go +++ b/post-processor/googlecompute-export/post-processor.hcl2spec.go @@ -21,10 +21,10 @@ type FlatConfig struct { DiskType *string `mapstructure:"disk_type" cty:"disk_type" hcl:"disk_type"` MachineType *string `mapstructure:"machine_type" cty:"machine_type" hcl:"machine_type"` Network *string `mapstructure:"network" cty:"network" hcl:"network"` - Paths []string `mapstructure:"paths" cty:"paths" hcl:"paths"` + Paths []string `mapstructure:"paths" required:"true" cty:"paths" hcl:"paths"` Subnetwork *string `mapstructure:"subnetwork" cty:"subnetwork" hcl:"subnetwork"` - VaultGCPOauthEngine *string `mapstructure:"vault_gcp_oauth_engine" cty:"vault_gcp_oauth_engine" hcl:"vault_gcp_oauth_engine"` Zone *string `mapstructure:"zone" cty:"zone" hcl:"zone"` + VaultGCPOauthEngine *string `mapstructure:"vault_gcp_oauth_engine" cty:"vault_gcp_oauth_engine" hcl:"vault_gcp_oauth_engine"` ServiceAccountEmail *string `mapstructure:"service_account_email" cty:"service_account_email" hcl:"service_account_email"` } @@ -54,8 +54,8 @@ func (*FlatConfig) HCL2Spec() map[string]hcldec.Spec { "network": &hcldec.AttrSpec{Name: "network", Type: cty.String, Required: false}, "paths": &hcldec.AttrSpec{Name: "paths", Type: cty.List(cty.String), Required: false}, "subnetwork": &hcldec.AttrSpec{Name: "subnetwork", Type: cty.String, Required: false}, - "vault_gcp_oauth_engine": &hcldec.AttrSpec{Name: "vault_gcp_oauth_engine", Type: cty.String, Required: false}, "zone": &hcldec.AttrSpec{Name: "zone", Type: cty.String, Required: false}, + "vault_gcp_oauth_engine": &hcldec.AttrSpec{Name: "vault_gcp_oauth_engine", Type: cty.String, Required: false}, "service_account_email": &hcldec.AttrSpec{Name: "service_account_email", Type: cty.String, Required: false}, } return s diff --git a/website/pages/docs/post-processors/googlecompute-export.mdx b/website/pages/docs/post-processors/googlecompute-export.mdx index fef1c4edc..c10a1b9c4 100644 --- a/website/pages/docs/post-processors/googlecompute-export.mdx +++ b/website/pages/docs/post-processors/googlecompute-export.mdx @@ -1,10 +1,7 @@ --- description: > The Google Compute Image Exporter post-processor exports an image from a - Packer - - googlecompute builder run and uploads it to Google Cloud Storage. The exported - + Packer googlecompute builder run and uploads it to Google Cloud Storage. The exported images can be easily shared and uploaded to other Google Cloud Projects. layout: docs page_title: Google Compute Image Exporter - Post-Processors @@ -28,47 +25,18 @@ credentials. As such, the authentication credentials that built the image must have write permissions to the GCS `paths`. +~> **Note**: By default the GCE image being exported will be deleted once the image has been exported. +To prevent Packer from deleting the image set the `keep_input_artifact` configuration option to `true`. See [Post-Processor Input Artifacts](https://www.packer.io/docs/templates/post-processors#input-artifacts) for more details. + ## Configuration ### Required -- `paths` (list of string) - The list of GCS paths, e.g. - 'gs://mybucket/path/to/file.tar.gz', where the image will be exported. +@include 'post-processor/googlecompute-export/Config-required.mdx' ### Optional -- `account_file` (string) - The JSON file containing your account - credentials. If specified, this take precedence over `googlecompute` - builder authentication method. - -- `disk_size` (number) - The size of the export instances disk, this disk - is unused for the export but a larger size increase `pd-ssd` read speed. - This defaults to `200`, which is 200GB. - -- `disk_type` (string) - Type of disk used to back export instance, like - `pd-ssd` or `pd-standard`. Defaults to `pd-ssd`. - -- `keep_input_artifact` (boolean) - If `true`, do not delete the Google Compute - Engine (GCE) image being exported. defaults to `false`. - -- `machine_type` (string) - The export instance machine type. Defaults - to `"n1-highcpu-4"`. - -- `network` (string) - The Google Compute network id or URL to use for the - export instance. Defaults to `"default"`. If the value is not a URL, it - will be interpolated to - `projects/((builder_project_id))/global/networks/((network))`. This value - is not required if a `subnet` is specified. - -- `subnetwork` (string) - The Google Compute subnetwork id or URL to use for - the export instance. Only required if the `network` has been created with - custom subnetting. Note, the region of the subnetwork must match the - `zone` in which the VM is launched. If the value is not a URL, - it will be interpolated to - `projects/((builder_project_id))/regions/((region))/subnetworks/((subnetwork))` - -- `zone` (string) - The zone in which to launch the export instance. Defaults - to `googlecompute` builder zone. Example: `"us-central1-a"` +@include 'post-processor/googlecompute-export/Config-not-required.mdx' ## Basic Example @@ -83,6 +51,9 @@ In order for this example to work, the account associated with `account.json` must have write access to both `gs://mybucket1/path/to/file1.tar.gz` and `gs://mybucket2/path/to/file2.tar.gz`. + + + ```json { "builders": [ @@ -106,3 +77,32 @@ must have write access to both `gs://mybucket1/path/to/file1.tar.gz` and ] } ``` + + + + + +```hcl + + source "googlecompute" "example" { + account_file = "account.json" + project_id = "my-project" + source_image = "debian-7-wheezy-v20150127" + zone = "us-central1-a" + } + + build { + sources = ["source.googlecompute.example"] + + post-processor "googlecompute-export" { + paths = [ + "gs://mybucket1/path/to/file1.tar.gz", + "gs://mybucket2/path/to/file2.tar.gz" + ] + keep_input_artifact = true + } + } +``` + + + diff --git a/website/pages/partials/post-processor/googlecompute-export/Config-not-required.mdx b/website/pages/partials/post-processor/googlecompute-export/Config-not-required.mdx new file mode 100644 index 000000000..0e6351f52 --- /dev/null +++ b/website/pages/partials/post-processor/googlecompute-export/Config-not-required.mdx @@ -0,0 +1,32 @@ + + +- `account_file` (string) - The JSON file containing your account credentials. + If specified, the account file will take precedence over any `googlecompute` builder authentication method. + +- `disk_size` (int64) - The size of the export instances disk. + The disk is unused for the export but a larger size will increase `pd-ssd` read speed. + This defaults to `200`, which is 200GB. + +- `disk_type` (string) - Type of disk used to back the export instance, like + `pd-ssd` or `pd-standard`. Defaults to `pd-ssd`. + +- `machine_type` (string) - The export instance machine type. Defaults to `"n1-highcpu-4"`. + +- `network` (string) - The Google Compute network id or URL to use for the export instance. + Defaults to `"default"`. If the value is not a URL, it + will be interpolated to `projects/((builder_project_id))/global/networks/((network))`. + This value is not required if a `subnet` is specified. + +- `subnetwork` (string) - The Google Compute subnetwork id or URL to use for + the export instance. Only required if the `network` has been created with + custom subnetting. Note, the region of the subnetwork must match the + `zone` in which the VM is launched. If the value is not a URL, + it will be interpolated to + `projects/((builder_project_id))/regions/((region))/subnetworks/((subnetwork))` + +- `zone` (string) - The zone in which to launch the export instance. Defaults + to `googlecompute` builder zone. Example: `"us-central1-a"` + +- `vault_gcp_oauth_engine` (string) - Vault GCP Oauth Engine + +- `service_account_email` (string) - Service Account Email diff --git a/website/pages/partials/post-processor/googlecompute-export/Config-required.mdx b/website/pages/partials/post-processor/googlecompute-export/Config-required.mdx new file mode 100644 index 000000000..a0bdc0e61 --- /dev/null +++ b/website/pages/partials/post-processor/googlecompute-export/Config-required.mdx @@ -0,0 +1,4 @@ + + +- `paths` ([]string) - A list of GCS paths where the image will be exported. + For example `'gs://mybucket/path/to/file.tar.gz'`