Doc update; new example; new tutorial for artifact dependencies (#4971)

* add tutorial for `microservices` example with artifact dependencies

* Fix test

* update feature maturity.json

* add new example and redo the tutorial.

* Update doc for Docker builder

Author: gsquared94

docs/content/en/docs/pipeline-stages/builders/docker.md

@@ -44,6 +44,14 @@ Which is equivalent to:
 
 {{% readfile file="samples/builders/local-full.yaml" %}}
 
+**Artifact dependency**
+
+You can additionally define dependency on other artifacts using the `requires` expression:
+
+{{% readfile file="samples/builders/artifact-dependencies/docker-local.yaml" %}}
+
+The specified alias `IMAGE2` becomes available as a build-arg in the Dockerfile for `image1` and it's value automatically set to the image built from `image2`.
+
 ## Dockerfile in-cluster with Kaniko
 
 [Kaniko](https://github.com/GoogleContainerTools/kaniko) is a Google-developed

docs/content/en/docs/tutorials/_index.md

@@ -26,3 +26,4 @@ Take a look at our other guides:
 | Detailed Tutorials |
 |--------------------|
 | [Custom Build Script]({{< relref "/docs/tutorials/custom-builder" >}}) |
+| [Build Artifact Dependencies]({{< relref "/docs/tutorials/artifact-dependencies" >}}) |

docs/content/en/docs/tutorials/artifact-dependencies.md

@@ -0,0 +1,76 @@
+---
+title: "Defining dependencies between artifacts"
+linkTitle: "Build Dependencies"
+weight: 100
+---
+
+This page describes how to define dependencies between artifacts and reference them in the [docker builder]({{<relref "/docs/pipeline-stages/builders/docker" >}}).
+
+## Before you begin
+
+First, you will need to have Skaffold and a Kubernetes cluster set up.
+To learn more about how to set up Skaffold and a Kubernetes cluster, see the [quickstart docs]({{< relref "/docs/quickstart" >}}).
+
+## Tutorial - Simple artifact dependency
+
+This tutorial will be based on the [simple-artifact-dependency](https://github.com/GoogleContainerTools/skaffold/tree/master/examples/simple-artifact-dependency) example in our repository.
+
+
+## Adding an artifact dependency
+
+We have a `base` artifact which has a single Dockerfile that we build with the [docker builder]({{<relref "/docs/pipeline-stages/builders/docker" >}}):
+ {{% readfile file="samples/builders/artifact-dependencies/Dockerfile.base" %}}
+
+This artifact is used as the base image for the `app` artifact. We express this dependency in the `skaffold.yaml` using the `requires` expression.
+{{% readfile file="samples/builders/artifact-dependencies/skaffold.yaml" %}}
+
+The image alias `BASE` is now available as a build-arg in the Dockerfile for `app`:
+ 
+{{% readfile file="samples/builders/artifact-dependencies/Dockerfile.app" %}}
+
+## Build and Deploy
+
+In the [simple-artifact-dependency](https://github.com/GoogleContainerTools/skaffold/tree/master/examples/simple-artifact-dependency) directory, run:
+
+```text
+skaffold dev
+```
+
+If this is the first time you're running this, then it should build the artifacts, starting with `base` and later `app`. Skaffold can handle any arbitrary dependency graph between artifacts and schedule builds in the right order. It'll also report an error if it detects dependency cycles or self-loops.
+
+```text
+Checking cache...
+ - base: Not found. Building
+ - app: Not found. Building
+
+Building [base]...
+<docker build logs here>
+
+Building [app]...
+<docker build logs here>
+```
+It will then deploy a single container pod, while also monitoring for file changes.
+
+```text
+Watching for changes...
+[simple-artifact-dependency-app] Hello World
+[simple-artifact-dependency-app] Hello World
+```
+
+Modify the text in file `base/hello.txt` to something else instead:
+
+```text
+Hello World!!!
+```
+
+This will trigger a rebuild for the `base` artifact, and since `app` artifact depends on `base` it'll also trigger a rebuild for that. After deployment stabilizes, it should now show the logs reflecting this change:
+
+```text
+Watching for changes...
+[simple-artifact-dependency-app] Hello World!!!
+[simple-artifact-dependency-app] Hello World!!!
+```
+
+## Cleanup
+
+Hitting `Ctrl + C` on a running Skaffold process should end it and cleanup its deployments. If there are still persisting objects then you can issue `skaffold delete` command to attempt the cleanup again.

docs/content/en/samples/builders/artifact-dependencies/Dockerfile.app

@@ -0,0 +1,5 @@
+ARG BASE
+FROM golang:1.12.9-alpine3.10 as builder
+...
+FROM $BASE
+COPY --from=builder /app .

docs/content/en/samples/builders/artifact-dependencies/Dockerfile.base

@@ -0,0 +1,3 @@
+FROM alpine:3.10
+COPY hello.txt .
+CMD ["./app"]

docs/content/en/samples/builders/artifact-dependencies/docker-local.yaml

@@ -0,0 +1,8 @@
+build:
+  artifacts:
+  - image: image1
+    requires:
+      - image: image2
+        alias: IMAGE2
+  - image: image2
+  local: {}

docs/content/en/samples/builders/artifact-dependencies/skaffold.yaml

@@ -0,0 +1,11 @@
+apiVersion: skaffold/v2beta9
+kind: Config
+build:
+  artifacts:
+  - image: app
+    context: app
+    requires:
+    - image: base
+      alias: BASE
+  - image: base
+    context: base

docs/data/maturity.json

@@ -24,6 +24,16 @@
     "maturity": "beta",
     "description": "build locally using a custom build script "
   },
+  "build.dependencies": {
+    "dev": "x",
+    "build": "x",
+    "run": "x",
+    "debug": "x",
+    "area": "Build",
+    "feature": "Build Artifact Dependencies",
+    "maturity": "alpha",
+    "description": "Define build artifact dependencies"
+  },
   "build": {
     "dev": "x",
     "build": "x",

integration/examples/simple-artifact-dependency/app/Dockerfile

@@ -0,0 +1,8 @@
+ARG BASE
+FROM golang:1.12.9-alpine3.10 as builder
+COPY main.go .
+
+RUN go build -o /app .
+
+FROM $BASE
+COPY --from=builder /app .

integration/examples/simple-artifact-dependency/app/k8s-pod.yaml

@@ -0,0 +1,8 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: simple-artifact-dependency-app
+spec:
+  containers:
+  - name: simple-artifact-dependency-app
+    image: app

integration/examples/simple-artifact-dependency/app/main.go

@@ -0,0 +1,19 @@
+package main
+
+import (
+	"fmt"
+	"io/ioutil"
+	"time"
+)
+
+func main() {
+	dat, err := ioutil.ReadFile("hello.txt")
+	if err != nil {
+		panic(err)
+	}
+
+	for {
+		fmt.Println(string(dat))
+		time.Sleep(time.Second * 1)
+	}
+}

integration/examples/simple-artifact-dependency/base/Dockerfile

@@ -0,0 +1,3 @@
+FROM alpine:3.10
+COPY hello.txt .
+CMD ["./app"]

integration/examples/simple-artifact-dependency/base/hello.txt

@@ -0,0 +1 @@
+Hello World

integration/examples/simple-artifact-dependency/skaffold.yaml

@@ -0,0 +1,16 @@
+apiVersion: skaffold/v2beta9
+kind: Config
+build:
+  artifacts:
+  - image: app
+    context: app
+    requires:
+    - image: base
+      alias: BASE
+  - image: base
+    context: base
+deploy:
+  kubectl:
+    manifests:
+    - app/k8s-pod.yaml
+

pkg/skaffold/schema/samples_test.go

@@ -36,7 +36,7 @@ const (
 )
 
 var (
-	ignoredSamples = []string{"structureTest.yaml", "build.sh", "globalConfig.yaml"}
+	ignoredSamples = []string{"structureTest.yaml", "build.sh", "globalConfig.yaml", "Dockerfile.app", "Dockerfile.base"}
 )
 
 // Test that every example can be parsed and produces a valid