Skip to content
This repository was archived by the owner on Mar 27, 2024. It is now read-only.

update docs #113

Merged
merged 2 commits into from
Oct 10, 2017
Merged

update docs #113

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
17e33eb
update docs
nkubala Oct 10, 2017
7320b9b
add local vs remote image example
nkubala Oct 10, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 34 additions & 28 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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 <img> [Run all analyzers]
container-diff analyze <img> [Run default analyzers]
container-diff analyze <img> --types=history [History]
container-diff analyze <img> --types=file [File System]
container-diff analyze <img> --types=pip [Pip]
Expand All @@ -52,7 +50,7 @@ container-diff analyze <img> --types=apt,node [Apt and Node]
# --types=<analyzer1>,<analyzer2>,<analyzer3>,...
```

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 <img1> <img2> [Run all differs]
container-diff diff <img1> <img2> --types=history [History]
Expand All @@ -65,7 +63,7 @@ container-diff diff <img1> <img2> --types=node [Node]
You can similarly run many analyzers at once:

```
container-diff diff <img1> <img2> --types=history,apt,node [History, Apt, and Node]
container-diff diff <img1> <img2> --types=history,apt,node
```

All of the analyzer flags with their long versions can be seen below:
Expand All @@ -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
Expand All @@ -96,27 +101,27 @@ 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",
"AnalyzeType": "Apt",
"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
Expand All @@ -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",
Expand All @@ -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 {
Expand All @@ -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 {
Expand All @@ -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
Expand All @@ -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 {
Expand All @@ -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 {
Expand All @@ -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 {
Expand All @@ -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
Expand Down Expand Up @@ -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:
```
[
{
Expand Down Expand Up @@ -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

Expand Down