Merge pull request #3149 from tejal29/add_init_docs

[docs] add init docs
GoogleContainerTools · Nov 5, 2019 · e9225b1 · e9225b1
2 parents 24fdcca + dea39b4
commit e9225b1
Show file tree

Hide file tree

Showing 15 changed files with 182 additions and 13 deletions.
diff --git a/docs/content/en/docs/design/api.md b/docs/content/en/docs/design/api.md
@@ -100,7 +100,7 @@ Example scenarios:
 | protocol | endpoint | encoding |
 | ---- | --- | --- |
 | HTTP | `http://localhost:{HTTP_RPC_PORT}/v1/events` | newline separated JSON using chunk transfer encoding over HTTP|  
-| gRPC | `client.Events(ctx)` method on the [`SkaffoldService`]({{< relref "/docs/references/api#skaffoldservice">}}) | protobuf 3 over HTTP |  
+| gRPC | `client.Events(ctx)` method on the [`SkaffoldService`]({{< relref "/docs/references/api#skaffoldservice">}}) | protobuf 3 over HTTP |
 
 
 **Examples**

diff --git a/docs/content/en/docs/pipeline-stages/builders.md b/docs/content/en/docs/pipeline-stages/builders.md
@@ -15,16 +15,15 @@ Skaffold has native support for several different tools for building images:
   - on cloud with [Google Cloud Build](https://cloud.google.com/cloud-build/docs/)
 * [Bazel](https://bazel.build/) locally
 * Custom script locally
-* [CNCF Buildpacks](../tutorials/buildpacks.md)
+* [CNCF Buildpacks]({{<relref "/docs/tutorials/buildpacks">}})
 
 The `build` section in the Skaffold configuration file, `skaffold.yaml`,
 controls how artifacts are built. To use a specific tool for building
 artifacts, add the value representing the tool and options for using that tool
 to the `build` section.
 
-For a detailed discussion on Skaffold configuration, see
-[Skaffold Concepts]({{< relref "/docs/design/config.md" >}}) and
-[skaffold.yaml References]({{< relref "/docs/references/yaml" >}}).
+For a detailed discussion on [Skaffold Configuration]({{< relref "/docs/design/config.md" >}}),
+see [skaffold.yaml References]({{< relref "/docs/references/yaml" >}}).
 
 ## Dockerfile locally with Docker
 

diff --git a/docs/content/en/docs/pipeline-stages/init.md b/docs/content/en/docs/pipeline-stages/init.md
@@ -0,0 +1,133 @@
+---
+title: "Init"
+linkTitle: "Init"
+weight: 1
+---
+
+`skaffold init` is an easy way to get your project up and running in seconds.
+
+Skaffold auto-generates `build` and `deploy` config for supported builders and deployers.
+
+
+## Build Config Initialization
+`skaffold init` currently supports build detection for two builders.
+
+1. [Docker]({{<relref "/docs/pipeline-stages/builders#dockerfile-locally-with-docker">}})
+2. [Jib]({{<relref "/docs/pipeline-stages/builders#jib-maven-and-gradle-locally">}})
+
+`skaffold init` will walk your project directory and look for any `Dockerfiles` 
+or `build.gradle/pom.xml`.
+
+If you have multiple `Dockerfile` or `build.gradle/pom.xml` files, Skaffold will provide an option
+to pair an image with one of the file.
+
+E.g. For a multi-services [microservices example](https://github.com/GoogleContainerTools/skaffold/tree/master/examples/microservices)
+
+```bash
+skaffold init
+```
+![microservices](/images/microservices-init-flow.png)
+
+
+{{< alert title="Note" >}}
+You can choose <code>None (image not built from these sources)</code> in case none of the suggested 
+options are correct. <br>
+You will have to manually set up build config for this artifact
+{{</alert>}}
+
+`skaffold` init also recognizes a maven or gradle project and will auto-suggest [`jib`]({{<relref "/docs/pipeline-stages/builders#jib-maven-and-gradle-locally">}}) builder.
+Currently `jib` artifact detection is disabled by default, you can turn it on using the flag `--XXenableJibInit`.
+
+You can try it this out on example [jib project](https://github.com/GoogleContainerTools/skaffold/tree/master/examples/jib-multimodule)
+
+```bash
+skaffold init --XXenableJibInit
+```
+
+![jib-multimodule](/images/jib-multimodule-init-flow.png)
+
+
+In case you want to configure build artifacts on your own, use `--skip-build` flag.
+
+## Deploy Config Initialization
+`skaffold init` currently supports only [`Kubeclt` deployer]({{<relref "/docs/pipeline-stages/deployers#deploying-with-kubectl" >}})
+Skaffold will walk through all the `yaml` files in your project and find valid kubernetes manifest files.
+
+These files will be added to `deploy` config in `skaffold.yaml`.
+
+```yaml
+deploy:
+  kubectl:
+    manifests:
+    - leeroy-app/kubernetes/deployment.yaml
+    - leeroy-web/kubernetes/deployment.yaml
+```
+
+
+## Init API
+`skaffold init` also exposes an api which tools like IDEs can integrate with via flags.
+
+This API can be used to 
+
+1. Analyze a project workspace and discover all build definitions (e.g. `Dockerfile`s) and artifacts (image names from the Kubernetes manifests) - this then provides an ability for tools to ask the user to pair the artifacts with Dockerfiles interactively. 
+2. Given a pairing between the image names (artifacts) and build definitions (e.g. Dockerfiles), generate Skaffold `build` config for a given artifact.
+
+**Init API contract**
+
+| API | flag | input/output |
+| ---- | --- | --- |
+| Analyze | `--analyze` | json encoded output of builders and images|  
+| Generate | `--artifact`| "`=` delimited" build definition/image pair (for example: `=path1/Dockerfile=artifact1`) or <br>JSON string (for example: `{"builder":"Docker","payload":{"path":"Dockerfile"},"image":"artifact")`|
+
+
+### Analyze API
+Analyze API walks through all files in your project workspace and looks for 
+`Dockerfile` files.
+
+To get all image names and dockerfiles, run
+```bash
+skaffold init --analyze | jq
+```
+will give you a json output
+```json
+{
+  "dockerfiles": [
+    "leeroy-app/Dockerfile",
+    "leeroy-web/Dockerfile"
+  ],
+  "images": [
+    "gcr.io/k8s-skaffold/leeroy-app",
+    "gcr.io/k8s-skaffold/leeroy-web"
+  ]
+}
+```
+
+### Generate API
+To generate a skaffold `build` config, use the `--artifact` flag per artifact.
+
+For multiple artifacts, use `--artifact` multiple times.
+
+```bash
+microservices$skaffold init \
+  -a '{"builder":"Docker","payload":{"path":"leeroy-app/Dockerfile"},"image":"gcr.io/k8s-skaffold/leeroy-app"}' \
+  -a '{"builder":"Docker","payload":{"path":"leeroy-web/Dockerfile"},"image":"gcr.io/k8s-skaffold/leeroy-web"}'
+```
+
+will produce an `skaffold.yaml` config like this
+```bash
+apiVersion: skaffold/v1beta15
+kind: Config
+metadata:
+  name: microservices
+build:
+  artifacts:
+  - image: gcr.io/k8s-skaffold/leeroy-app
+    context: leeroy-app
+  - image: gcr.io/k8s-skaffold/leeroy-web
+    context: leeroy-web
+deploy:
+  kubectl:
+    manifests:
+    - leeroy-app/kubernetes/deployment.yaml
+    - leeroy-web/kubernetes/deployment.yaml
+```
diff --git a/docs/content/en/docs/quickstart/_index.md b/docs/content/en/docs/quickstart/_index.md
@@ -141,11 +141,13 @@ Skaffold will perform the workflow described in `skaffold.yaml` exactly once.
 
 ## What's next
 
+For getting started with your project, see the [Getting Started With Your Project]({{<relref "/docs/workflows/getting-started-with-your-project" >}}) workflow.
+
 For more in-depth topics of Skaffold, explore [Configuration]({{< relref "/docs/design/config.md" >}}),
-[Skaffold Pipeline](/docs/pipeline-stages), and [Architecture and Design]({{< relref "/docs/design" >}}).
+[Skaffold Pipeline]({{<relref "/docs/pipeline-stages" >}}), and [Architecture and Design]({{< relref "/docs/design" >}}).
 
 To learn more about how Skaffold builds, tags, and deploys your app, see the How-to Guides on
-using [Builders](/docs/pipeline-stages/builders), [Taggers](/docs/pipeline-stages/taggers), and [Deployers]({{< relref "/docs/pipeline-stages/deployers" >}}).
+using [Builders]({{<relref "/docs/pipeline-stages/builders" >}}), [Taggers]({{< relref "/docs/pipeline-stages/taggers">}}), and [Deployers]({{< relref "/docs/pipeline-stages/deployers" >}}).
 
 [Skaffold Tutorials]({{< relref "/docs/tutorials" >}}) details some of the common use cases of Skaffold.
 

diff --git a/docs/content/en/docs/references/deprecation/_index.md b/docs/content/en/docs/references/deprecation/_index.md
@@ -128,4 +128,4 @@ This flag will will be removed earliest 06/15/2019.
 - `DIGEST_ALGO`
 - `DIGEST_HEX`
 Currently these variables resolve to `_DEPRECATED_<envvar>_`, and the new tagging mechanism adds a digest to the image name thus it shouldn't break existing configurations.
-This backward compatibility behavior will be removed earliest 05/14/2019.
+This backward compatibility behavior will be removed earliest 05/14/2019.
diff --git a/docs/content/en/docs/tutorials/_index.md b/docs/content/en/docs/tutorials/_index.md
@@ -16,4 +16,12 @@ As we have gcr.io/k8s-skaffold in our image names, to run the examples, you have
     1. skaffold config for current kubectl context: `skaffold config set default-repo <myrepo>`
 
 
-:mega: **Please fill out our [quick 5-question survey](https://forms.gle/BMTbGQXLWSdn7vEs6)** to tell us how satisfied you are with Skaffold, and what improvements we should make. Thank you! :dancers:
+:mega: **Please fill out our [quick 5-question survey](https://forms.gle/BMTbGQXLWSdn7vEs6)** to tell us how satisfied you are with Skaffold, and what improvements we should make. Thank you! :dancers:
+
+
+## What's next
+Take a look at our other guides
+
+| Tutorials References  |
+|----------|
+| [Custom Builder]({{< relref "/docs/tutorials/buildpacks" >}}) |
diff --git a/docs/content/en/docs/tutorials/buildpacks.md b/docs/content/en/docs/tutorials/buildpacks.md
@@ -1,7 +1,7 @@
 ---
 title: "Building Artifacts with CNCF Buildpacks"
 linkTitle: "Buildpacks"
-weight: 100
+weight: 110
 ---
 
 This page describes building Skaffold artifacts with [buildpacks](https://buildpacks.io/).

diff --git a/docs/content/en/docs/workflows/_index.md b/docs/content/en/docs/workflows/_index.md
@@ -8,6 +8,7 @@ weight: 1
 
 | Skaffold Workflow | |
 |----------|---|
+| [`skaffold init`]({{< relref "getting-started-with-your-project" >}}) | Getting started with your project|
 | [`skaffold dev`]({{< relref "dev.md" >}}) | Continuous development with `skaffold dev` |
 | [`skaffold debug`]({{< relref "debug.md" >}}) | Debugging your application on-cluster with `skaffold debug` |
 | [`CI/CD with skaffold`]({{< relref "ci-cd.md" >}}) | CI/CD integration with Skaffold |
diff --git a/docs/content/en/docs/workflows/ci-cd.md b/docs/content/en/docs/workflows/ci-cd.md
@@ -1,7 +1,7 @@
 ---
 title: "CI/CD with Skaffold"
 linkTitle: "CI/CD with Skaffold"
-weight: 30
+weight: 40
 ---
 
 Skaffold offers several sub-commands for its workflows that make it quite flexible when integrating with CI/CD pipelines.

diff --git a/docs/content/en/docs/workflows/debug.md b/docs/content/en/docs/workflows/debug.md
@@ -1,7 +1,7 @@
 ---
 title: "Debugging with Skaffold"
 linkTitle: "Debugging"
-weight: 20
+weight: 30
 ---
 
 {{< alert title="Note" >}}

diff --git a/docs/content/en/docs/workflows/dev.md b/docs/content/en/docs/workflows/dev.md
@@ -1,7 +1,7 @@
 ---
 title: "skaffold dev"
 linkTitle: "Continuous development"
-weight: 10
+weight: 20
 ---
 
 `skaffold dev` enables continuous local development on an application.

diff --git a/docs/content/en/docs/workflows/getting-started-with-your-project.md b/docs/content/en/docs/workflows/getting-started-with-your-project.md
@@ -0,0 +1,26 @@
+---
+title: "Getting Started With Your Project"
+linkTitle: "Getting Started With Your Project"
+weight: 10
+---
+
+Skaffold requires a `skaffold.yaml`, but - for supported projects - Skaffold can generate a simple config for you that you can get started with. To configure Skaffold for your application you can run [`skaffold init`]({{<relref "docs/references/cli#skaffold-init" >}}).
+
+Running `skaffold init` at the root of your project directory will walk you through a wizard
+and create a `skaffold.yaml` with [build](#build-config-initialization) and [deploy](#deploy-config-initialization) config.
+
+```bash
+skaffold init
+```
+
+![init-flow](/images/init-flow.png)
+
+## What's next
+You can further set up [File Sync]({{<relref "/docs/pipeline-stages/filesync" >}}) for source files 
+that do not need a rebuild in [dev mode]({{<relref "/docs/workflows/dev">}}). 
+
+Skaffold automatically forwards Kubernetes Services in [dev mode]({{<relref "/docs/workflows/dev">}}) if you run it with `--port-forward`. If your project contains resources other than services, you can set-up [port-forwarding]({{<relref "/docs/pipeline-stages/port-forwarding" >}})
+to port-forward these resources in [`dev`]({{<relref "docs/workflows/dev" >}}) or [`debug`]({{<relref "/docs/workflows/debug" >}}) mode.
+
+
+For more understanding on how init works, see [`skaffold init`]({{<relref "/docs/pipeline-stages/init" >}})
diff --git a/docs/static/images/init-flow.png b/docs/static/images/init-flow.png
diff --git a/docs/static/images/jib-multimodule-init-flow.png b/docs/static/images/jib-multimodule-init-flow.png
diff --git a/docs/static/images/microservices-init-flow.png b/docs/static/images/microservices-init-flow.png