Merge pull request #2962 from ostenbom/snapshots-docs

estesp · web-flow · commit 77d7b0123300 · 2019-01-29T20:50:40.000Z
Update snapshots docs with garbage collector label
diff --git a/snapshots/snapshotter.go b/snapshots/snapshotter.go
@@ -160,9 +160,13 @@ func (u *Usage) Add(other Usage) {
 //	layerPath, tmpDir := getLayerPath(), mkTmpDir() // just a path to layer tar file.
 //
 // We start by using a Snapshotter to Prepare a new snapshot transaction, using a
-// key and descending from the empty parent "":
+// key and descending from the empty parent "". To prevent our layer from being
+// garbage collected during unpacking, we add the `containerd.io/gc.root` label:
 //
-//	mounts, err := snapshotter.Prepare(ctx, key, "")
+//	noGcOpt := snapshotter.WithLabels(map[string]string{
+//		"containerd.io/gc.root": time.Now().UTC().Format(time.RFC3339),
+//	})
+//	mounts, err := snapshotter.Prepare(ctx, key, "", noGcOpt)
 // 	if err != nil { ... }
 //
 // We get back a list of mounts from Snapshotter.Prepare, with the key identifying
@@ -191,23 +195,21 @@ func (u *Usage) Add(other Usage) {
 //
 // Now that we've verified and unpacked our layer, we commit the active
 // snapshot to a name. For this example, we are just going to use the layer
-// digest, but in practice, this will probably be the ChainID:
+// digest, but in practice, this will probably be the ChainID. This also removes
+// the active snapshot:
 //
-//	if err := snapshotter.Commit(ctx, digest.String(), key); err != nil { ... }
+//	if err := snapshotter.Commit(ctx, digest.String(), key, noGcOpt); err != nil { ... }
 //
 // Now, we have a layer in the Snapshotter that can be accessed with the digest
-// provided during commit. Once you have committed the snapshot, the active
-// snapshot can be removed with the following:
-//
-// 	snapshotter.Remove(ctx, key)
+// provided during commit.
 //
 // Importing the Next Layer
 //
 // Making a layer depend on the above is identical to the process described
 // above except that the parent is provided as parent when calling
 // Manager.Prepare, assuming a clean, unique key identifier:
 //
-// 	mounts, err := snapshotter.Prepare(ctx, key, parentDigest)
+// 	mounts, err := snapshotter.Prepare(ctx, key, parentDigest, noGcOpt)
 //
 // We then mount, apply and commit, as we did above. The new snapshot will be
 // based on the content of the previous one.
