diff --git a/README.md b/README.md index df78585c..816689e3 100644 --- a/README.md +++ b/README.md @@ -5,15 +5,13 @@ Status](https://travis-ci.org/GoogleCloudPlatform/container-diff.svg?branch=mast ## What is container-diff? -container-diff is an image analysis command line tool. container-diff can analyze images along several different criteria, currently including: +container-diff is a tool for analyzing and comparing container images. container-diff can examine images along several different criteria, including: - Docker Image History - Image file system -- apt-get installed packages -- pip installed packages -- npm installed packages -The above analyses can be performed on a single image, or a diff can be performed on two images to compare images. - -This tool can help you as a developer better understand what is changing within your images and better understand what your images contain. +- Apt packages +- pip packages +- npm packages +These analyses can be performed on a single image, or a diff can be performed on two images to compare. The tool can help users better understand what is changing inside their images, and give them a better look at what their images contain. ## Installation @@ -39,10 +37,10 @@ Download the [container-diff-windows-amd64.exe](https://storage.googleapis.com/c ## Quickstart -To use `container-diff analyze` to perform analysis on a single image, you need one Docker image (in the form of an ID, tarball, or URL from a repo). Once you have that image, you can run any of the following analyzers: +To use `container-diff analyze` to perform analysis on a single image, you need one Docker image (in the form of an ID, tarball, or URL from a repo). Once you have that image, you can run any of the following analyzers: ``` -container-diff analyze [Run all analyzers] +container-diff analyze [Run default analyzers] container-diff analyze --types=history [History] container-diff analyze --types=file [File System] container-diff analyze --types=pip [Pip] @@ -52,7 +50,7 @@ container-diff analyze --types=apt,node [Apt and Node] # --types=,,,... ``` -To use container-diff to perform a diff analysis on two images, you need two Docker images (in the form of an ID, tarball, or URL from a repo). Once you have those images, you can run any of the following differs: +To use container-diff to perform a diff analysis on two images, you need two Docker images (in the form of an ID, tarball, or URL from a repo). Once you have those images, you can run any of the following differs: ``` container-diff diff [Run all differs] container-diff diff --types=history [History] @@ -65,7 +63,7 @@ container-diff diff --types=node [Node] You can similarly run many analyzers at once: ``` -container-diff diff --types=history,apt,node [History, Apt, and Node] +container-diff diff --types=history,apt,node ``` All of the analyzer flags with their long versions can be seen below: @@ -79,6 +77,13 @@ All of the analyzer flags with their long versions can be seen below: | apt-get installed packages| -a | --apt | +## Image Sources + +container-diff supports Docker images located in both a local Docker daemon and a remote registry. To explicitly specify a local image, use the `daemon://` prefix on the image name; similarly, for an explicitly remote image, use the `remote://` prefix. + +```container-diff diff daemon://modified_debian:latest remote://gcr.io/google-appengine/debian8:latest``` + +Additionally, tarballs can be provided to the tool directly. Make sure your file has a valid tar extension (.tar, .tar.gz, .tgz). ## Other Flags @@ -96,7 +101,7 @@ To order files and packages by size (in descending order) when performing file s ## Analysis Result Format -The JSONs for analysis results are in the following format: +JSON output for analysis results is in the following format: ``` { "Image": "foo", @@ -104,19 +109,19 @@ The JSONs for analysis results are in the following format: "Analysis": {}, } ``` -The possible structures of the `Analysis` field are detailed below. +The possible contents of the `Analysis` field are detailed below. ### History Analysis -The history analyzer outputs a list of strings representing descriptions of how an image layer was created. +The history analyzer outputs a list of strings representing descriptions of how an image layer was created. This is the only analyzer that requires a working Docker daemon to run. ### File System Analysis -The file system analyzer outputs a list of strings representing file system contents. +The file system analyzer outputs a list of file system contents, including names, paths, and sizes. ### Package Analysis -Package analyzers such as pip, apt, and node inspect the packages installed within the image provided. All package analyses leverage the PackageOutput struct, which contains the version and size for a given package instance (and a potential installation path for a specific instance of a package where multiple versions are allowed to be installed), as detailed below: +Package analyzers such as pip, apt, and node inspect the packages installed within the image provided. All package analyses leverage the PackageOutput struct, which contains the version and size for a given package instance (and a potential installation path for a specific instance of a package where multiple versions are allowed to be installed), as detailed below: ``` type PackageOutput struct { Name string @@ -142,7 +147,7 @@ Here, the `Path` field is included because there may be more than one instance o ## Diff Result Format -The JSONs for diff results are in the following format: +JSON output for diff results is in the following format: ``` { "Image1": "foo", @@ -155,7 +160,7 @@ The possible structures of the `Diff` field are detailed below. ### History Diff -The history differ has the following json output structure: +The history differ has the following JSON output structure: ``` type HistDiff struct { @@ -166,7 +171,7 @@ type HistDiff struct { ### File System Diff -The file system differ has the following json output structure: +The file system differ has the following JSON output structure: ``` type DirDiff struct { @@ -178,7 +183,7 @@ type DirDiff struct { ### Package Diffs -Package differs such as pip, apt, and node inspect the packages contained within the images provided. All packages differs currently leverage the PackageInfo struct which contains the version and size for a given package instance, as detailed below: +Package differs such as pip, apt, and node inspect the packages contained within the images provided. All packages differs currently leverage the PackageInfo struct which contains the version and size for a given package instance, as detailed below: ``` type PackageInfo struct { Version string @@ -188,7 +193,7 @@ type PackageInfo struct { #### Single Version Package Diffs -Single version differs (apt) have the following json output structure: +Single version differs (apt) have the following JSON output structure: ``` type PackageDiff struct { @@ -198,11 +203,11 @@ type PackageDiff struct { } ``` -Packages1 and Packages2 detail which packages exist uniquely in Image1 and Image2, respectively, with package name, version and size info. InfoDiff contains a list of Info structs, each of which contains the package name (which occurred in both images but had a difference in size or version), and the PackageInfo struct for each package instance. +Packages1 and Packages2 detail which packages exist uniquely in Image1 and Image2, respectively, with package name, version and size info. InfoDiff contains a list of Info structs, each of which contains the package name (which occurred in both images but had a difference in size or version), and the PackageInfo struct for each package instance. #### Multi Version Package Diffs -The multi version differs (pip, node) support processing images which may have multiple versions of the same package. Below is the json output structure: +The multi version differs (pip, node) support processing images which may have multiple versions of the same package. Below is the json output structure: ``` type MultiVersionPackageDiff struct { @@ -212,7 +217,7 @@ type MultiVersionPackageDiff struct { } ``` -Packages1 and Packages2 detail which packages exist uniquely in Image1 and Image2, respectively, with package name, installation path, version and size info. InfoDiff here is exanded to allow for multiple versions to be associated with a single package. In this case, a package of the same name is considered to differ between two images when there exist one or more instances of it installed in one image but not the other (i.e. have a unique version and/or size). +Packages1 and Packages2 detail which packages exist uniquely in Image1 and Image2, respectively, with package name, installation path, version and size info. InfoDiff here is exanded to allow for multiple versions to be associated with a single package. In this case, a package of the same name is considered to differ between two images when there exist one or more instances of it installed in one image but not the other (i.e. have a unique version and/or size). ``` type MultiVersionInfo struct { @@ -224,7 +229,8 @@ type MultiVersionInfo struct { ## Known issues -To run container-diff on image IDs, docker must be installed. +To run container-diff using image IDs, docker must be installed. +Tarballs provided directly to the tool must be in the Docker format (i.e. have a manifest.json file for layer ordering) ## Example Run @@ -259,8 +265,8 @@ Packages found only in gcr.io/google-appengine/python:2017-06-29-190410: None Version differences: None ``` -## Example Run with json post-processing -The following example demonstrates how one might selectively display the output of their diff, such that version differences are ignored and only package absence/presence is displayed and the packages present in only one image are sorted by size in descending order. A small piece of the json being post-processed can be seen below: +## Example Run with JSON post-processing +The following example demonstrates how one might selectively display the output of their diff, such that version differences are ignored and only package absence/presence is displayed and the packages present in only one image are sorted by size in descending order. A small piece of the JSON being post-processed can be seen below: ``` [ { @@ -338,7 +344,7 @@ Only in image2 ``` ## Make your own differ -Feel free to develop your own analyzer leveraging the utils currently available. PRs are welcome. +Feel free to develop your own analyzer leveraging the utils currently available. PRs are welcome! ### Custom Analyzer Quickstart