cos_image_analyzer: Add some details in user guide.
This CL has the following changes:
1) polish the user guide:
- Stress that The -local input expects disk.raw file. So users need to
unzip tarball if needed.
- Explain the service account credentials that required by -gcs input
and add link to the instruction.
- Correct the default list of -compressRootfs flag.
- Explain why root is needed for the program.
- Delete words about commits and release notes from the usage because
they are not implemented yet.
2) Change the default value of -package flag from true to false.
Because the feature is not ready yet.
3) Allow to choose whether to authenticate when downloading from GCS.
This is useful to download public data from GCS.
Change-Id: Id602b4e27abeb2ea0a7238fb62ab6b6164cdc8e4
diff --git a/go.mod b/go.mod
index 83152aa..d2cd902 100644
--- a/go.mod
+++ b/go.mod
@@ -17,5 +17,6 @@
github.com/urfave/cli/v2 v2.2.0
go.chromium.org/luci v0.0.0-20200722211809-bab0c30be68b
golang.org/x/oauth2 v0.0.0-20200107190931-bf48bf16ab8d
+ google.golang.org/api v0.28.0
google.golang.org/protobuf v1.25.0
)
diff --git a/src/cmd/cos_image_analyzer/internal/binary/info.go b/src/cmd/cos_image_analyzer/internal/binary/info.go
index c0d21c2..e5a350a 100644
--- a/src/cmd/cos_image_analyzer/internal/binary/info.go
+++ b/src/cmd/cos_image_analyzer/internal/binary/info.go
@@ -46,7 +46,7 @@
// it into the image's temporary directory
func getKernelConfigs(image *input.ImageInfo) error {
gcsObject := filepath.Join(image.BuildID, kernelHeaderGCSObject)
- tarFile, err := utilities.GcsDowndload(cosGCSBucket, gcsObject, image.TempDir, kernelHeaderGCSObject)
+ tarFile, err := utilities.GcsDowndload(cosGCSBucket, gcsObject, image.TempDir, kernelHeaderGCSObject, false)
if err != nil {
return fmt.Errorf("failed to download GCS object %v from bucket %v: %v", gcsObject, cosGCSBucket, err)
}
diff --git a/src/cmd/cos_image_analyzer/internal/input/imageinfo.go b/src/cmd/cos_image_analyzer/internal/input/imageinfo.go
index 8f75fd5..f4583cc 100644
--- a/src/cmd/cos_image_analyzer/internal/input/imageinfo.go
+++ b/src/cmd/cos_image_analyzer/internal/input/imageinfo.go
@@ -157,7 +157,7 @@
}
image.TempDir = tempDir
- tarFile, err := utilities.GcsDowndload(gcsBucket, gcsObject, image.TempDir, filepath.Base(gcsObject))
+ tarFile, err := utilities.GcsDowndload(gcsBucket, gcsObject, image.TempDir, filepath.Base(gcsObject), true)
if err != nil {
return fmt.Errorf("failed to download GCS object %v from bucket %v: %v", gcsObject, gcsBucket, err)
}
diff --git a/src/cmd/cos_image_analyzer/internal/input/parse.go b/src/cmd/cos_image_analyzer/internal/input/parse.go
index b489622..11854e3 100644
--- a/src/cmd/cos_image_analyzer/internal/input/parse.go
+++ b/src/cmd/cos_image_analyzer/internal/input/parse.go
@@ -24,8 +24,8 @@
// Custom usage function. See -h flag
func printUsage() {
usageTemplate := `NAME
- cos_image_analyzer - finds all meaningful differences of two COS Images (binary, package, commit, and release notes differences).
- If only one image is passed in, its binary info, package info, commit log, and release-notes will be returned.
+ cos_image_analyzer - finds all meaningful differences of two COS Images (binary and package differences).
+ If only one image is passed in, its binary info and package info will be returned.
SYNOPSIS
%s [-local] FILE-1 [FILE-2] (default true)
@@ -35,17 +35,22 @@
%s -local -binary=Sysctl-settings,OS-config -package=false image-cos-77-12371-273-0/disk.raw
%s -gcs GCS-PATH-1 [GCS-PATH-2]
- GCS-PATH - the GCS "bucket/object" path for the COS Image ("object" is type .tar.gz)
- Ex: %s -gcs my-bucket/cos-images/cos-77-12371-273-0.tar.gz my-bucket/cos-images/cos-81-12871-119-0.tar.gz
+ GCS-PATH - the GCS "gs://bucket/object" path for the COS Image ("object" is type .tar.gz)
+ Ex: %s -gcs gs://my-bucket/cos-images/cos-77-12371-273-0.tar.gz gs://my-bucket/cos-images/cos-81-12871-119-0.tar.gz
DESCRIPTION
Input Flags:
-local (default true, flag is optional)
- input is one or two DOS/MBR disk file on the local filesystem.
+ input is one or two DOS/MBR disk file on the local filesystem. If the images are downloaded from
+ Google Cloud as a tarball, decompress the tarball first then pass the disk.raw file to the program.
-gcs
input is one or two objects stored on Google Cloud Storage of type (.tar.gz). This flag temporarily downloads,
unzips, and loop device mounts the images into this tool's directory.
+ To download images from Google Cloud Storage, you need to pass a service account credential to the program.
+ Folllow https://cloud.google.com/docs/authentication/production#create_service_account to create a service account and
+ download the service account key. Then point environment variable GOOGLE_APPLICATION_CREDENTIALS to the key file then
+ run the program.
Difference Flags:
-binary (string)
@@ -55,21 +60,21 @@
comma. To NOT list any binary difference, set flag to "false". (default all types)
-package
specify whether to show package difference. Shows addition/removal of packages and package version updates.
- To NOT list any package difference, set flag to false. (default true)
+ To NOT list any package difference, set flag to false. (default false)
Attribute Flags
-verbose
- include flag to increase verbosity of Rootfs, Stateful-partition, and OS-config differences. See the
- "internal/binary/CompressRootfs.txt", "internal/binary/CompressStateful.txt", and "internal/binary/CompressOSConfigs.txt"
- files to edit the default directories whose differences are compressed together.
+ include flag to increase verbosity of Rootfs, Stateful-partition, and OS-config differences. See -compress-rootfs and
+ -compress-stateful flags descriptions for the directories that are compressed by default.
-compress-rootfs (string)
to customize which directories are compressed in a non-verbose Rootfs and OS-config difference output, provide a local
- file path to a text file. Format of the file must be one root file path per line with an ending back slash and no commas.
+ file path to a .txt file. Format of the file must be one root file path per line with an ending back slash and no commas.
By default the directory(s) that are compressed during a diff are /bin/, /lib/modules/, /lib64/, /usr/libexec/, /usr/bin/,
- /usr/sbin/, /usr/lib64/, /usr/share/zoneinfo/, /usr/share/git/, /usr/lib/, and /sbin/.
+ /usr/sbin/, /usr/lib64/, /usr/share/zoneinfo/, /usr/share/git/, /usr/lib/, /sbin/, /etc/ssh/, /etc/os-release/ and
+ /etc/package_list/.
-compress-stateful (string)
to customize which directories are compressed in a non-verbose Stateful-partition difference output, provide a local
- file path to a text file. Format of file must be one root file path per line with no commas. By default the directory(s)
+ file path to a .txt file. Format of file must be one root file path per line with no commas. By default the directory(s)
that are compressed during a diff are /var_overlay/db/.
Output Flags:
@@ -78,6 +83,9 @@
OUTPUT
Based on the "-output" flag. Either "terminal" stdout or machine readable "json" format.
+
+NOTE
+ The root permission is needed for this program because it needs to mount images into your local filesystem to calculate difference.
`
cmd := filepath.Base(os.Args[0])
usage := fmt.Sprintf(usageTemplate, cmd, cmd, cmd, cmd, cmd)
@@ -159,7 +167,7 @@
flag.StringVar(&flagInfo.ProjectIDPtr, "projectID", "", "")
flag.StringVar(&flagInfo.BinaryDiffPtr, "binary", "", "")
- flag.BoolVar(&flagInfo.PackageSelected, "package", true, "")
+ flag.BoolVar(&flagInfo.PackageSelected, "package", false, "")
flag.BoolVar(&flagInfo.CommitSelected, "commit", true, "")
flag.BoolVar(&flagInfo.ReleaseNotesSelected, "release-notes", true, "")
diff --git a/src/cmd/cos_image_analyzer/internal/utilities/gcs_download.go b/src/cmd/cos_image_analyzer/internal/utilities/gcs_download.go
index 8b1a8c1..25a9e45 100644
--- a/src/cmd/cos_image_analyzer/internal/utilities/gcs_download.go
+++ b/src/cmd/cos_image_analyzer/internal/utilities/gcs_download.go
@@ -11,24 +11,35 @@
"time"
"cloud.google.com/go/storage"
+ "google.golang.org/api/option"
)
const contextTimeOut = time.Second * 50
const base10 = 10
// GcsDowndload calls the GCS client api to download a specified object from
-// a GCS bucket. ADC is used for authorization
+// a GCS bucket.
// Input:
// (string) bucket - Name of the GCS bucket
// (string) object - Name of the GCS object
// (string) destDir - Destination for downloaded GCS object
// (string) name - Name for the downloaded file
+// (bool) authenticate - Indicates whether the GCS client need to be authenticated.
+// Use unauthenticated client if you only wish to access public data.
+// Otherwise, ADC will be used for authorization.
// Output:
// (string) downloadedFile - Path to downloaded GCS object
-func GcsDowndload(bucket, object, destDir, name string) (string, error) {
+func GcsDowndload(bucket, object, destDir, name string, authenticate bool) (string, error) {
// Call API to download GCS object into tempDir
+ var client *storage.Client
+ var err error
+
ctx := context.Background()
- client, err := storage.NewClient(ctx)
+ if authenticate {
+ client, err = storage.NewClient(ctx)
+ } else {
+ client, err = storage.NewClient(ctx, option.WithoutAuthentication())
+ }
if err != nil {
return "", fmt.Errorf("failed to create new Google Cloud Go storage client: %v", err)
}
