From 68e5b486ec3b7c89d734c1b8aaa46ea19267d2dc Mon Sep 17 00:00:00 2001 From: Tejal Desai Date: Fri, 1 Nov 2019 15:45:44 -0700 Subject: [PATCH] separate the docs --- docs/content/en/docs/design/api.md | 4 +- .../en/docs/pipeline-stages/builders.md | 5 +- .../init.md} | 115 ++++++++++++++++-- docs/content/en/docs/quickstart/_index.md | 2 +- docs/content/en/docs/tutorials/_index.md | 1 - docs/content/en/docs/workflows/_index.md | 1 + docs/content/en/docs/workflows/ci-cd.md | 2 +- docs/content/en/docs/workflows/debug.md | 2 +- docs/content/en/docs/workflows/dev.md | 2 +- .../getting-started-with-your-project.md | 53 ++++++++ 10 files changed, 166 insertions(+), 21 deletions(-) rename docs/content/en/docs/{tutorials/getting-started-with-your-project.md => pipeline-stages/init.md} (51%) create mode 100644 docs/content/en/docs/workflows/getting-started-with-your-project.md diff --git a/docs/content/en/docs/design/api.md b/docs/content/en/docs/design/api.md index 1262aaf9ac7..b9ff37e9c57 100644 --- a/docs/content/en/docs/design/api.md +++ b/docs/content/en/docs/design/api.md @@ -95,12 +95,12 @@ Example scenarios: * port forwarding events are used by Cloud Code to attach debuggers automatically to running containers. * when a port-forwarded frontend service is redeployed successfully, kick-off a suite of Selenium tests that test changes to the newly deployed service.. -**Event API contract** +~~**Event API contract** | 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 index 3237210ee5d..1c51ca2dab0 100755 --- a/docs/content/en/docs/pipeline-stages/builders.md +++ b/docs/content/en/docs/pipeline-stages/builders.md @@ -22,9 +22,8 @@ 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/tutorials/getting-started-with-your-project.md b/docs/content/en/docs/pipeline-stages/init.md similarity index 51% rename from docs/content/en/docs/tutorials/getting-started-with-your-project.md rename to docs/content/en/docs/pipeline-stages/init.md index d5a38b6b3fb..a58a419cc08 100644 --- a/docs/content/en/docs/tutorials/getting-started-with-your-project.md +++ b/docs/content/en/docs/pipeline-stages/init.md @@ -1,19 +1,13 @@ --- -title: "Getting Started With Your Project" -linkTitle: "Getting Started With Your Project" -weight: 100 +title: "Init" +linkTitle: "Init" +weight: 1 --- -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`]({{}}). +`skaffold init` is an easy way to get your project up and running in seconds. -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. +Skaffold auto-generates `build` and `deploy` config for supported builders and deployers. -You can further set up [File Sync]({{}}) for file dependencies -that do not need a rebuild. - -If your project contain resources other than services, you can set-up [port-forwarding]({{}}) -to port-forward these resources in [`dev`]({{}}) or [`debug`]({{}}) mode. ## Build Config Initialization `skaffold init` currently supports build detection for two builders. @@ -75,4 +69,103 @@ deploy: ``` +## 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 `Dockerfiles` and images. +2. Generate Skaffold `build` config for a given artifact. + +**Init API contract** + +| API | flag | input/output | +| ---- | --- | --- | +| Analyze | `--analyze` and `--XXenableJibInit`| json encoded output of builders and images| +| Generate | `--artifact`| `=` delimited Dockerfile/image pair, or JSON string | + + +### Analyze API +Analyze API walks through all files in your project workspace and looks for +`Dockerfile`, `build.gradle` and `pom.xml` files. + +To get all image names and image builders, run +```json +skaffold init --analyze --XXenableJibInit | jq +{ + { + "builders": [ + { + "name": "Docker", + "payload": { + "path": "microservices/leeroy-app/Dockerfile" + } + }, + { + "name": "Jib Maven Plugin", + "payload": { + "image": "gcr.io/k8s-skaffold/project1", + "path": "pom.xml", + "project": "skaffold-project-1" + } + }, + { + "name": "Jib Maven Plugin", + "payload": { + "image": "gcr.io/k8s-skaffold/project2", + "path": "pom.xml", + "project": "skaffold-project-2" + } + } + ], + "images": [ + { + "name": "gcr.io/k8s-skaffold/skaffold-jib-1", + "foundMatch": false + }, + { + "name": "gcr.io/k8s-skaffold/skaffold-jib-2", + "foundMatch": false + }, + { + "name": "gcr.io/k8s-skaffold/leeroy-app", + "foundMatch": false + }, + ] + } +} +``` + +### Generate API +To generate a skaffold `build` config, use the `--artifact` flag per artifact. + +For multiple artifacts, use `--artifact` multiple times. + +```bash +multimodule$skaffold init \ + -a '{"builder":"Docker","payload":{"path":"web/Dockerfile.web"},"image":"gcr.io/web-project/image"}' \ + -a '{"builder":"Jib Maven Plugin","payload":{"path":"backend/pom.xml"},"image":"gcr.io/backend/image"}' \ + --XXenableJibInit + +apiVersion: skaffold/v1beta15 +kind: Config +metadata: + name: multimodule +build: + artifacts: + - image: gcr.io/web-project/image + context: web + docker: + dockerfile: web/Dockerfile.web + - image: gcr.io/backend/image + context: backend + jib: + args: + - -Dimage=gcr.io/backend/image +deploy: + kubectl: + manifests: + - web/kubernetes/web.yaml + - backend/kubernetes/deployment.yaml +``` \ No newline at end of file diff --git a/docs/content/en/docs/quickstart/_index.md b/docs/content/en/docs/quickstart/_index.md index 0c4f9b4c105..36ba5842a3e 100644 --- a/docs/content/en/docs/quickstart/_index.md +++ b/docs/content/en/docs/quickstart/_index.md @@ -141,7 +141,7 @@ 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]({{}}) tutorial. +For getting started with your project, see the [Getting Started With Your Project]({{}}) workflow. For more in-depth topics of Skaffold, explore [Configuration]({{< relref "/docs/design/config.md" >}}), [Skaffold Pipeline]({{}}), and [Architecture and Design]({{< relref "/docs/design" >}}). diff --git a/docs/content/en/docs/tutorials/_index.md b/docs/content/en/docs/tutorials/_index.md index b936570e042..746c78b4b0b 100755 --- a/docs/content/en/docs/tutorials/_index.md +++ b/docs/content/en/docs/tutorials/_index.md @@ -24,5 +24,4 @@ Take a look at our other guides | Tutorials References | |----------| -| [Getting Started With Your Project]({{< relref "/docs/tutorials/getting-started-with-your-project" >}}) | | [Custom Builder]({{< relref "/docs/tutorials/buildpacks" >}}) | diff --git a/docs/content/en/docs/workflows/_index.md b/docs/content/en/docs/workflows/_index.md index d3762f6b894..b6d59e63e0c 100644 --- a/docs/content/en/docs/workflows/_index.md +++ b/docs/content/en/docs/workflows/_index.md @@ -8,5 +8,6 @@ weight: 3 | 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` | diff --git a/docs/content/en/docs/workflows/ci-cd.md b/docs/content/en/docs/workflows/ci-cd.md index b1e340452d5..f13c378c4ee 100644 --- 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: 3 +weight: 40 --- {{< todo 3074>}} ci/cd writeup diff --git a/docs/content/en/docs/workflows/debug.md b/docs/content/en/docs/workflows/debug.md index 33040b48245..ce26576040a 100644 --- 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: 2 +weight: 30 --- {{< alert title="Note" >}} diff --git a/docs/content/en/docs/workflows/dev.md b/docs/content/en/docs/workflows/dev.md index 5cafe4379a0..b612c843646 100644 --- 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: 1 +weight: 20 --- {{< todo 3074>}} dev page \ No newline at end of file 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 new file mode 100644 index 00000000000..5fdd043ead0 --- /dev/null +++ b/docs/content/en/docs/workflows/getting-started-with-your-project.md @@ -0,0 +1,53 @@ +--- +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`]({{}}). + +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 +microservices$ skaffold init +? Choose the builder to build image gcr.io/k8s-skaffold/leeroy-app Docker (leeroy-app/Dockerfile) +? Choose the builder to build image gcr.io/k8s-skaffold/leeroy-web Docker (leeroy-web/Dockerfile) +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 + +Do you want to write this configuration to skaffold.yaml? [y/n]: y +Configuration skaffold.yaml was written +You can now run [skaffold build] to build the artifacts +or [skaffold run] to build and deploy +or [skaffold dev] to enter development mode, with auto-redeploy +``` + +You can further set up [File Sync]({{}}) for file dependencies +that do not need a rebuild. + +If your project contain resources other than services, you can set-up [port-forwarding]({{}}) +to port-forward these resources in [`dev`]({{}}) or [`debug`]({{}}) mode. + + +## What's next + +For more understanding on how init works, see [`skaffold init`]({{}}) + +Try out [dev]({{}}), [debug]({{}}) workflows. + + +