diff --git a/examples/bazel/README.adoc b/examples/bazel/README.adoc deleted file mode 100644 index 02d0c4838b4..00000000000 --- a/examples/bazel/README.adoc +++ /dev/null @@ -1,42 +0,0 @@ -=== Example: bazel -:icons: font - -Bazel is one of the supported builders in Skaffold. -The way you configure it in `skaffold.yaml` is the following build stanza: - -[source,yaml] ----- -build: - artifacts: - - image: gcr.io/k8s-skaffold/skaffold-example - context: . <1> - bazel: # <2> - target: //:skaffold_example.tar # <3> ----- -<1> make sure the context contains the bazel files (`WORKSPACE`, `BUILD`) -<2> add bazel to each artifact -<3> specify target - our builder will use this to load to the image to the Docker daemon - -ifndef::env-github[] -==== link:{github-repo-tree}/examples/bazel[Example files icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,go, indent=3, title=main.go, syntax=go] ----- -include::main.go[] ----- - -[source,bazel, indent=3, title=WORKSPACE] ----- -include::WORKSPACE[] ----- - -[source,bazel, indent=3, title=BUILD] ----- -include::BUILD[] ----- -endif::[] diff --git a/examples/bazel/README.md b/examples/bazel/README.md new file mode 100644 index 00000000000..0c31660d138 --- /dev/null +++ b/examples/bazel/README.md @@ -0,0 +1,18 @@ +### Example: bazel + +Bazel is one of the supported builders in Skaffold. + +The way you configure it in `skaffold.yaml` is the following build stanza: + +```yaml +build: + artifacts: + - image: gcr.io/k8s-skaffold/skaffold-example + context: . + bazel: + target: //:skaffold_example.tar +``` + +1. make sure the `context` contains the bazel files (`WORKSPACE`, `BUILD`) +2. add `bazel` section to each artifact +3. specify `target` - our builder will use this to load to the image to the Docker daemon diff --git a/examples/buildpacks/README.md b/examples/buildpacks/README.md new file mode 100644 index 00000000000..87e6f8d132a --- /dev/null +++ b/examples/buildpacks/README.md @@ -0,0 +1,7 @@ +### Example: kaniko + +This is an example demonstrating: + +* **building** a single Go file app built with [Cloud Native Buildpacks](https://buildpacks.io/) +* **tagging** using the default tagPolicy (`gitCommit`) +* **deploying** a single container pod using `kubectl` diff --git a/examples/compose/README.adoc b/examples/compose/README.adoc deleted file mode 100644 index 494c948092f..00000000000 --- a/examples/compose/README.adoc +++ /dev/null @@ -1,10 +0,0 @@ -=== Example: Running skaffold with docker-compose files -:icons: font - -This example provides a simple application set up to run with -https://docs.docker.com/compose/[docker-compose]. -Notice there is no skaffold configuration present: to run this example, -first run `skaffold init --compose-file docker-compose.yaml`, which will -invoke the https://github.com/kubernetes/kompose[kompose] binary to generate -kubernetes manifests based off of the docker-compose configuration, and then run -`skaffold init` to generate the skaffold configuration. diff --git a/examples/compose/README.md b/examples/compose/README.md new file mode 100644 index 00000000000..652de133314 --- /dev/null +++ b/examples/compose/README.md @@ -0,0 +1,15 @@ +### Example: running Skaffold with docker-compose files + +This example provides a simple application set up to run with +[Docker Compose](https://docs.docker.com/compose/). + +Notice there is no `skaffold.yaml` configuration present. +To run this example, use: + +```bash +skaffold init --compose-file docker-compose.yaml +``` + +1. This will invoke the [kompose](https://github.com/kubernetes/kompose) binary to generate +kubernetes manifests based off of the Docker Compose configuration. +2. This will generate the `skaffold.yaml` configuration. diff --git a/examples/custom/README.adoc b/examples/custom/README.md similarity index 55% rename from examples/custom/README.adoc rename to examples/custom/README.md index 6dd401b7bd8..1a8d661adc5 100644 --- a/examples/custom/README.adoc +++ b/examples/custom/README.md @@ -1,27 +1,27 @@ -=== Example: Getting started with buildpacks -:icons: font +### Example: use the custom builder with Cloud Native Buildpacks -This is a simple example based on +This example shows how the custom builder can be used to +build artifacts with Cloud Native Buildpacks. -* *building* a single go file app with buildpacks -* *tagging* using the default tagPolicy (`gitCommit`) -* *deploying* a single container pod using `kubectl` +* **building** a single Go file app with buildpacks +* **tagging** using the default tagPolicy (`gitCommit`) +* **deploying** a single container pod using `kubectl` -## Before you begin +#### Before you begin For this tutorial to work, 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 https://skaffold.dev/docs/getting-started[getting started docs]. +To learn more about how to set up Skaffold and a Kubernetes cluster, see the [getting started docs](https://skaffold.dev/docs/getting-started). To use buildpacks with Skaffold, please install the following additional tools: -* https://buildpacks.io/docs/install-pack/[pack] -* https://docs.docker.com/install/[docker] +* [pack](https://buildpacks.io/docs/install-pack/) +* [docker](https://docs.docker.com/install/) -## Tutorial +#### Tutorial This tutorial will demonstrate how Skaffold can build a simple Hello World Go application with buildpacks and deploy it to a Kubernetes cluster. -First, clone the Skaffold https://github.com/GoogleContainerTools/skaffold[repo] and navigate to the https://github.com/GoogleContainerTools/skaffold/tree/master/examples/buildpacks[buildpacks example] for sample code: +First, clone the Skaffold [repo](https://github.com/GoogleContainerTools/skaffold) and navigate to the [buildpacks example](https://github.com/GoogleContainerTools/skaffold/tree/master/examples/buildpacks) for sample code: ```shell $ git clone https://github.com/GoogleContainerTools/skaffold @@ -54,7 +54,8 @@ build: custom: buildCommand: ./build.sh ``` -For more information about how this works, see the Skaffold custom builder https://skaffold.dev/docs/how-tos/builders/#custom-build-script-run-locally[documentation]. + +For more information about how this works, see the Skaffold custom builder [documentation](https://skaffold.dev/docs/how-tos/builders/#custom-build-script-run-locally). Now, use Skaffold to deploy this application to your Kubernetes cluster: @@ -63,30 +64,12 @@ $ skaffold run --tail --default-repo ``` With this command, Skaffold will build the `skaffold-example` artifact with buildpacks and deploy the application to Kubernetes. -You should be able to see "Hello, World!" printed every second in the Skaffold logs. +You should be able to see *Hello, World!* printed every second in the Skaffold logs. + +#### Cleanup To clean up your Kubernetes cluster, run: ```shell $ skaffold delete ``` - -ifndef::env-github[] -==== link:{github-repo-tree}/examples/buildpacks[Example files icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,go, indent=3, title=main.go, syntax=go] ----- -include::main.go[] ----- - -[source,yaml, indent=3, title=k8s-pod.yaml] ----- -include::k8s-pod.yaml[] ----- - -endif::[] diff --git a/examples/gcb-kaniko/README.adoc b/examples/gcb-kaniko/README.adoc deleted file mode 100644 index f90ed055aa1..00000000000 --- a/examples/gcb-kaniko/README.adoc +++ /dev/null @@ -1,33 +0,0 @@ -=== Example: Getting started with a simple go app -:icons: font - -This is a simple example based on - -* *building* a single go file app and with a multistage `Dockerfile` using https://github.com/GoogleContainerTools/kaniko[kaniko] in Google Cloud Build -* *tagging* using the default tagPolicy (`gitCommit`) -* *deploying* a single container pod using `kubectl` - -ifndef::env-github[] -==== link:{github-repo-tree}/examples/getting-started[Example files icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,go, indent=3, title=main.go, syntax=go] ----- -include::main.go[] ----- - -[source,docker, indent=3, title=Dockerfile] ----- -include::Dockerfile[] ----- - -[source,yaml, indent=3, title=k8s-pod.yaml] ----- -include::k8s-pod.yaml[] ----- - -endif::[] diff --git a/examples/gcb-kaniko/README.md b/examples/gcb-kaniko/README.md new file mode 100644 index 00000000000..f4e65c3c097 --- /dev/null +++ b/examples/gcb-kaniko/README.md @@ -0,0 +1,7 @@ +### Example: Getting started with a simple go app + +This is a simple example based on: + +* **building** a single Go file app and with a multistage `Dockerfile` using [kaniko](https://github.com/GoogleContainerTools/kaniko) in Google Cloud Build +* **tagging** using the default tagPolicy (`gitCommit`) +* **deploying** a single container pod using `kubectl` diff --git a/examples/generate-pipeline/README.adoc b/examples/generate-pipeline/README.md similarity index 73% rename from examples/generate-pipeline/README.adoc rename to examples/generate-pipeline/README.md index ff993154a42..68a6039910d 100644 --- a/examples/generate-pipeline/README.adoc +++ b/examples/generate-pipeline/README.md @@ -1,5 +1,4 @@ -=== Example: Getting started with skaffold and CI/CD using Tekton -:icons: font +### Example: Getting started with skaffold and CI/CD using Tekton This is a simple example to show users how to run the generate-pipeline command @@ -7,15 +6,16 @@ _Please keep in mind that the generate-pipeline command is still a WIP_ Prerequisites: -* Install tekton on your cluster (https://github.com/tektoncd/pipeline/blob/master/docs/install.md) -* Have kaniko secrets setup (https://github.com/GoogleContainerTools/kaniko) +* Install [tekton](https://github.com/tektoncd/pipeline/blob/master/docs/install.md) on your cluster +* Have [kaniko](https://github.com/GoogleContainerTools/kaniko) secrets setup * Container registry must be public * Give your default service account the cluster-admin role (necessary to have pipeline access secrets) ----- + +```shell kubectl create clusterrolebinding serviceaccounts-cluster-admin \ --clusterrole=cluster-admin \ --user=system:serviceaccount:default:default ----- +``` To generate and run a pipeline: diff --git a/examples/getting-started/README.adoc b/examples/getting-started/README.adoc deleted file mode 100644 index ba15fd56e93..00000000000 --- a/examples/getting-started/README.adoc +++ /dev/null @@ -1,33 +0,0 @@ -=== Example: Getting started with a simple go app -:icons: font - -This is a simple example based on - -* *building* a single go file app and with a multistage `Dockerfile` using local docker to build -* *tagging* using the default tagPolicy (`gitCommit`) -* *deploying* a single container pod using `kubectl` - -ifndef::env-github[] -==== link:{github-repo-tree}/examples/getting-started[Example files icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,go, indent=3, title=main.go, syntax=go] ----- -include::main.go[] ----- - -[source,docker, indent=3, title=Dockerfile] ----- -include::Dockerfile[] ----- - -[source,yaml, indent=3, title=k8s-pod.yaml] ----- -include::k8s-pod.yaml[] ----- - -endif::[] diff --git a/examples/getting-started/README.md b/examples/getting-started/README.md new file mode 100644 index 00000000000..a87d20a507b --- /dev/null +++ b/examples/getting-started/README.md @@ -0,0 +1,7 @@ +### Example: Getting started with a simple go app + +This is a simple example based on: + +* **building** a single Go file app and with a multistage `Dockerfile` using local docker to build +* **tagging** using the default tagPolicy (`gitCommit`) +* **deploying** a single container pod using `kubectl` \ No newline at end of file diff --git a/examples/google-cloud-build/README.adoc b/examples/google-cloud-build/README.adoc deleted file mode 100644 index 4b4e8b09266..00000000000 --- a/examples/google-cloud-build/README.adoc +++ /dev/null @@ -1,33 +0,0 @@ -=== Example: Getting started with a simple go app -:icons: font - -This is a simple example based on - -* *building* a single go file app and with a multistage `Dockerfile` using Google Cloud Build -* *tagging* using the default tagPolicy (`gitCommit`) -* *deploying* a single container pod using `kubectl` - -ifndef::env-github[] -==== link:{github-repo-tree}/examples/getting-started[Example files icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,go, indent=3, title=main.go, syntax=go] ----- -include::main.go[] ----- - -[source,docker, indent=3, title=Dockerfile] ----- -include::Dockerfile[] ----- - -[source,yaml, indent=3, title=k8s-pod.yaml] ----- -include::k8s-pod.yaml[] ----- - -endif::[] diff --git a/examples/google-cloud-build/README.md b/examples/google-cloud-build/README.md new file mode 100644 index 00000000000..ba5577be07d --- /dev/null +++ b/examples/google-cloud-build/README.md @@ -0,0 +1,7 @@ +### Example: Getting started with a simple go app + +This is a simple example based on: + +* **building** a single Go file app and with a multistage `Dockerfile` using Google Cloud Build +* **tagging** using the default tagPolicy (`gitCommit`) +* **deploying** a single container pod using `kubectl` diff --git a/examples/helm-deployment-dependencies/README.adoc b/examples/helm-deployment-dependencies/README.md similarity index 71% rename from examples/helm-deployment-dependencies/README.adoc rename to examples/helm-deployment-dependencies/README.md index 9a1cff3e1a1..016bb81c943 100644 --- a/examples/helm-deployment-dependencies/README.adoc +++ b/examples/helm-deployment-dependencies/README.md @@ -1,15 +1,12 @@ -=== Example: helm-dependencies -:icons: font +### Example: deploy helm charts with local dependencies -==== Deploy helm charts with local dependencies - -This example follows the link:{github-repo-tree}/examples/helm-deployment-dependencies[helm] example, but with a local chart as a depenency. +This example follows the [helm](../helm-deployment) example, but with a local chart as a dependency. The `skipBuildDependencies` option is used to skip the `helm dep build` command. This must be disabled for charts with local dependencies. The image can be passed to the subchart using the standard Helm format of `subchart-name.value`. -``` +```yaml deploy: helm: releases: diff --git a/examples/helm-deployment/README.adoc b/examples/helm-deployment/README.md similarity index 78% rename from examples/helm-deployment/README.adoc rename to examples/helm-deployment/README.md index ac728ada731..8b803f93560 100644 --- a/examples/helm-deployment/README.adoc +++ b/examples/helm-deployment/README.md @@ -1,19 +1,13 @@ -=== Example: helm -:icons: font - -ifndef::env-github[] -link:{github-repo-tree}/examples/helm-deployment[see on Github icon:github[]] -endif::[] - -==== Deploy multiple releases with Helm +### Example: deploy multiple releases with Helm You can deploy multiple releases with skaffold, each will need a chartPath, a values file, and namespace. Skaffold can inject intermediate build tags in the the values map in the skaffold.yaml. -Let's walk through the skaffold yaml +Let's walk through the skaffold yaml: We'll be building an image called `skaffold-helm`, and its a dockerfile, so we'll add it to the artifacts. -``` + +```yaml build: artifacts: - image: skaffold-helm @@ -21,7 +15,8 @@ build: Now, we want to deploy this image with helm. We add a new release in the helm part of the deploy stanza. -``` + +```yaml deploy: helm: releases: @@ -35,7 +30,8 @@ deploy: ``` This part tells skaffold to set the `image` parameter of the values file to the built skaffold-helm image and tag. -``` + +```yaml values: image: skaffold-helm ``` diff --git a/examples/hot-reload/README.md b/examples/hot-reload/README.md new file mode 100644 index 00000000000..3fa2da3e6d0 --- /dev/null +++ b/examples/hot-reload/README.md @@ -0,0 +1,18 @@ +### Example: hot-reload with Node and Python + +Application demonstrating the file synchronization mode with both NodeJS and Python. + +#### Init + +```bash +skaffold dev +``` + +#### Workflow + +* Make some changes to `node/src/index.js`: + * The file will be synchronized to the cluster + * `nodemon` will restart the application +* Make some changes to `python/src/app.py`: + * The file will be synchronized to the cluster + * `flask` will restart the application diff --git a/examples/jib-gradle/README.md b/examples/jib-gradle/README.md new file mode 100644 index 00000000000..853459c217d --- /dev/null +++ b/examples/jib-gradle/README.md @@ -0,0 +1,15 @@ +### Example: Jib (Gradle) + +[Jib](https://github.com/GoogleContainerTools/jib) is one of the supported builders in Skaffold. +It builds Docker and OCI images +for your Java applications and is available as plugins for Maven and Gradle. + +The way you configure it in `skaffold.yaml` is the following build stanza: + +```yaml +build: + artifacts: + - image: gcr.io/k8s-skaffold/skaffold-example + context: . + jib: {} +``` diff --git a/integration/examples/jib-multimodule/README.adoc b/examples/jib-multimodule/README.md similarity index 57% rename from integration/examples/jib-multimodule/README.adoc rename to examples/jib-multimodule/README.md index 7dfdcbd5b45..98946823329 100644 --- a/integration/examples/jib-multimodule/README.adoc +++ b/examples/jib-multimodule/README.md @@ -1,8 +1,7 @@ -=== Example: Jib Multi-Module -:icons: font +### Example: Jib Multi-Module -Jib is one of the supported builders in Skaffold. -https://github.com/GoogleContainerTools/jib[Jib] builds Docker and OCI images +[Jib](https://github.com/GoogleContainerTools/jib) is one of the supported builders in Skaffold. +It builds Docker and OCI images for your Java applications and is available as plugins for Maven and Gradle. Sometimes a project is configured to have multiple _modules_ to create several @@ -11,8 +10,7 @@ required. The way you configure it in `skaffold.yaml` is the following build stanza: -[source,yaml] ----- +```yaml build: artifacts: - image: gcr.io/k8s-skaffold/skaffold-jib-1 @@ -29,26 +27,12 @@ build: context: . jib: project: :artifactId ----- +``` There are a few caveats: - - The `jib-maven-plugin` must be either be configured referenced in the - root module of the project. This is easily done through a `pluginManagement` - block. +- The `jib-maven-plugin` must be either be configured referenced in the +root module of the project. This is easily done through a `pluginManagement` +block. - - The artifact modules must have a `jib:xxx` goal bound to the `package` phase. - -ifndef::env-github[] -==== link:{github-repo-tree}/examples/jib[Example files icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,xml, indent=3, title=pom.xml, syntax=xml] ----- -include::pom.xml[] ----- -endif::[] +- The artifact modules must have a `jib:xxx` goal bound to the `package` phase. diff --git a/examples/jib/README.adoc b/examples/jib/README.md similarity index 54% rename from examples/jib/README.adoc rename to examples/jib/README.md index 1c49e6c847a..4ff86e5382e 100644 --- a/examples/jib/README.adoc +++ b/examples/jib/README.md @@ -1,36 +1,20 @@ -=== Example: Jib -:icons: font +### Example: Jib (Maven) -Jib is one of the supported builders in Skaffold. -[Jib](https://github.com/GoogleContainerTools/jib) builds Docker and OCI images +[Jib](https://github.com/GoogleContainerTools/jib) is one of the supported builders in Skaffold. +It builds Docker and OCI images for your Java applications and is available as plugins for Maven and Gradle. The way you configure it in `skaffold.yaml` is the following build stanza: -[source,yaml] ----- +```yaml build: artifacts: - image: gcr.io/k8s-skaffold/skaffold-example context: . jib: {} ----- +``` Please note that this example is for a standalone Maven project, where all dependencies are resolved from outside. The Jib builder requires that the projects are configured to use the Jib plugins for Maven or Gradle. Multi-module builds require a bit additional configuration. - -ifndef::env-github[] -==== link:{github-repo-tree}/examples/jib[Example files icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,xml, indent=3, title=pom.xml, syntax=xml] ----- -include::pom.xml[] ----- -endif::[] diff --git a/examples/kaniko-local/README.adoc b/examples/kaniko-local/README.adoc deleted file mode 100644 index f0eaa62695a..00000000000 --- a/examples/kaniko-local/README.adoc +++ /dev/null @@ -1,34 +0,0 @@ -=== Example: kaniko-local -:icons: font - -This is an example demonstrating - -* *building* a single go file app and with a single stage `Dockerfile` using https://github.com/GoogleContainerTools/kaniko[kaniko] to build on a K8S cluster directly from a local build context -* *tagging* using the default tagPolicy (`gitCommit`) -* *deploying* a single container pod using `kubectl` - -ifndef::env-github[] -==== Example files -link:{github-repo-tree}/examples/kaniko[see on Github icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,go, indent=3, title=main.go, syntax=go] ----- -include::main.go[] ----- - -[source,docker, indent=3, title=Dockerfile] ----- -include::Dockerfile[] ----- - -[source,yaml, indent=3, title=k8s-pod.yaml] ----- -include::k8s-pod.yaml[] ----- - -endif::[] diff --git a/examples/kaniko-local/README.md b/examples/kaniko-local/README.md new file mode 100644 index 00000000000..0e877b5a804 --- /dev/null +++ b/examples/kaniko-local/README.md @@ -0,0 +1,7 @@ +### Example: kaniko-local + +This is an example demonstrating: + +* **building** a single Go file app and with a single stage `Dockerfile` using [kaniko](https://github.com/GoogleContainerTools/kaniko) to build on a K8S cluster directly from a local build context +* **tagging** using the default tagPolicy (`gitCommit`) +* **deploying** a single container pod using `kubectl` diff --git a/examples/kaniko/README.adoc b/examples/kaniko/README.adoc deleted file mode 100644 index 537f94a53a6..00000000000 --- a/examples/kaniko/README.adoc +++ /dev/null @@ -1,34 +0,0 @@ -=== Example: kaniko -:icons: font - -This is an example demonstrating - -* *building* a single go file app and with a single stage `Dockerfile` using https://github.com/GoogleContainerTools/kaniko[kaniko] to build on a K8S cluster -* *tagging* using the default tagPolicy (`gitCommit`) -* *deploying* a single container pod using `kubectl` - -ifndef::env-github[] -==== Example files -link:{github-repo-tree}/examples/kaniko[see on Github icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,go, indent=3, title=main.go, syntax=go] ----- -include::main.go[] ----- - -[source,docker, indent=3, title=Dockerfile] ----- -include::Dockerfile[] ----- - -[source,yaml, indent=3, title=k8s-pod.yaml] ----- -include::k8s-pod.yaml[] ----- - -endif::[] diff --git a/examples/kaniko/README.md b/examples/kaniko/README.md new file mode 100644 index 00000000000..c88f8483535 --- /dev/null +++ b/examples/kaniko/README.md @@ -0,0 +1,7 @@ +### Example: kaniko + +This is an example demonstrating: + +* **building** a single Go file app and with a single stage `Dockerfile` using [kaniko](https://github.com/GoogleContainerTools/kaniko) to build on a K8S cluster +* **tagging** using the default tagPolicy (`gitCommit`) +* **deploying** a single container pod using `kubectl` diff --git a/examples/kustomize/README.adoc b/examples/kustomize/README.adoc deleted file mode 100644 index 8da32c884af..00000000000 --- a/examples/kustomize/README.adoc +++ /dev/null @@ -1,44 +0,0 @@ -=== Example: kustomize -:icons: font - -This is an example demonstrating how skaffold can work with kustomize with the `skaffold deploy` command. - -ifndef::env-github[] -==== Example files -link:{github-repo-tree}/examples/kustomize[see on Github icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,yaml, indent=3, title=kustomization.yaml] ----- -include::kustomization.yaml[] ----- - -[source,patch, indent=3, title=patch.yaml] ----- -include::patch.yaml[] ----- - -[source,patch, indent=3, title=deployment.yaml] ----- -include::deployment.yaml[] ----- - -endif::[] - -=== Example: passing arguments to kustomize -:icons: font - -This is an example demonstrating how additional arguments can be passed to the `kustomize build` command. - -ifndef::env-github[] - -[source,yaml, indent=3, title=skaffold-kustomize-args.yaml] ----- -include::skaffold-kustomize-args.yaml[] ----- - -endif::[] diff --git a/examples/kustomize/README.md b/examples/kustomize/README.md new file mode 100644 index 00000000000..efebf3bace4 --- /dev/null +++ b/examples/kustomize/README.md @@ -0,0 +1,3 @@ +### Example: kustomize + +This is an example demonstrating: how skaffold can work with kustomize with the `skaffold deploy` command. diff --git a/integration/examples/microservices/README.adoc b/examples/microservices/README.md similarity index 85% rename from integration/examples/microservices/README.adoc rename to examples/microservices/README.md index 0c6afd3910d..b856c1ed289 100644 --- a/integration/examples/microservices/README.adoc +++ b/examples/microservices/README.md @@ -1,9 +1,4 @@ -=== Example: µSvcs with Skaffold -:icons: font - -ifndef::env-github[] -link:{github-repo-tree}/examples/microservices[see on Github icon:github[]] -endif::[] +### Example: µSvcs with Skaffold In this example: @@ -14,10 +9,10 @@ In this example: In the real world, Kubernetes deployments will consist of multiple applications that work together. In this example, we'll walk through using skaffold to develop and deploy two applications, an exposed "web" frontend which calls an unexposed "app" backend. -**WARNING:** *If you're running this on a cloud cluster, this example will create a service and expose a webserver. -It's highly suggested that you only run this example on a local, private cluster like minikube or Kubernetes in Docker for Desktop.* +**WARNING: If you're running this on a cloud cluster, this example will create a service and expose a webserver. +It's highly suggested that you only run this example on a local, private cluster like minikube or Kubernetes in Docker for Desktop.** -==== Running the example on minikube +#### Running the example on minikube From this directory, run @@ -44,17 +39,19 @@ func handler(w http.ResponseWriter, r *http.Request) { ``` Once you see the log message + ``` [leeroy-app-5b4dfdcbc6-6vf6r leeroy-app] 2018/03/30 06:28:47 leeroy app server ready ``` + Your service will be ready to hit again with -``` +```bash $ curl $(minikube service leeroy-web --url) leeroooooy app!!! ``` -==== Configuration walkthrough +#### Configuration walkthrough Let's walk through the first part of the skaffold.yaml @@ -70,7 +67,6 @@ We're deploying a `leeroy-web` image, which we build in the context of its subdi `leeroy-web` will listen for requests, and then make a simple HTTP call to `leeroy-app` using Kubernetes service discovery and return that result. - In the deploy stanza, we use the glob matching pattern to deploy all YAML and JSON files in the respective Kubernetes manifest directories. ```yaml diff --git a/examples/nodejs/README.adoc b/examples/nodejs/README.adoc deleted file mode 100644 index 09811fd152d..00000000000 --- a/examples/nodejs/README.adoc +++ /dev/null @@ -1,16 +0,0 @@ -=== Example: Node.js with hot-reload -:icons: font - -Simple example based on Node.js demonstrating the file synchronization mode. - -==== Init -`skaffold dev` - -==== Workflow -* Make some changes to `index.js`: -** The file will be synchronized to the cluster -** `nodemon` will restart the application -* Make some changes to `package.json`: -** The full build/push/deploy process will be triggered, fetching dependencies from `npm` - - diff --git a/examples/nodejs/README.md b/examples/nodejs/README.md new file mode 100644 index 00000000000..fae16103a12 --- /dev/null +++ b/examples/nodejs/README.md @@ -0,0 +1,19 @@ +### Example: Node.js with hot-reload + +Simple example based on Node.js demonstrating the file synchronization mode. + +#### Init + +```bash +skaffold dev +``` + +#### Workflow + +* Make some changes to `index.js`: + * The file will be synchronized to the cluster + * `nodemon` will restart the application +* Make some changes to `package.json`: + * The full build/push/deploy process will be triggered, fetching dependencies from `npm` + + diff --git a/examples/profile-patches/README.adoc b/examples/profile-patches/README.md similarity index 66% rename from examples/profile-patches/README.adoc rename to examples/profile-patches/README.md index 20be56b59d2..9435507fa4b 100644 --- a/examples/profile-patches/README.adoc +++ b/examples/profile-patches/README.md @@ -1,23 +1,14 @@ -=== Example: Getting started with a simple go app -:icons: font +### Example: Getting started with a simple go app This is a simple show-case of how Skaffold profiles can be patched. Patched profiles e.g. can be used in development to provide a composable development setup. Here, a "base" service is always started. Two additional services "hello" and "world" can be activated via profiles. -==== Init -Use the `--profile` option to add profiles `skaffold dev --profile hello,world` - -==== Workflow -* Build only the `base-service` when using the main profile -* Build `hello` and/or `world` when specified via `-p` flag. Multiple `-p` flags are supported as well as comma separated values. +#### Init -ifndef::env-github[] -==== link:{github-repo-tree}/examples/profiles[Example files icon:github[]] +Use the `--profile` option to add profiles `skaffold dev --profile hello,world` -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- +#### Workflow -endif::[] +* Build only the `base-service` when using the main profile +* Build `hello` and/or `world` when specified via `-p` flag. Multiple `-p` flags are supported as well as comma separated values. \ No newline at end of file diff --git a/examples/profiles/README.adoc b/examples/profiles/README.md similarity index 62% rename from examples/profiles/README.adoc rename to examples/profiles/README.md index f84bada61f4..ad8ee6eb4d3 100644 --- a/examples/profiles/README.adoc +++ b/examples/profiles/README.md @@ -1,22 +1,13 @@ -=== Example: Getting started with a simple go app -:icons: font +### Example: Getting started with a simple go app This is a simple show-case of Skaffold profiles -==== Init +#### Init + Use the `--profile` option to enable a particular profile `skaffold dev --profile staging-profile` -==== Workflow +#### Workflow + * Build only the `world-service` when using the main profile * Activate `minikube-profile` automatically when the current context is `minikube`. Only build the `hello-service` in that case. * Build both services when the `staging-profile` is used. Override the kube-context to `staging` in that case. - -ifndef::env-github[] -==== link:{github-repo-tree}/examples/profiles[Example files icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -endif::[] diff --git a/examples/react-reload/README.adoc b/examples/react-reload/README.adoc deleted file mode 100644 index c339ea85229..00000000000 --- a/examples/react-reload/README.adoc +++ /dev/null @@ -1,16 +0,0 @@ -=== Example: React app with hot-reload -:icons: font - -Simple React app demonstrating the file synchronization mode in conjunction with webpack hot module reload. - -==== Init -`skaffold dev` - -==== Workflow -* Make some changes to `HelloWorld.js`: -** The file will be synchronized to the cluster -** `webpack` will perform hot module reloading -* Make some changes to `package.json`: -** The full build/push/deploy process will be triggered, fetching dependencies from `npm` - - diff --git a/examples/react-reload/README.md b/examples/react-reload/README.md new file mode 100644 index 00000000000..44c3cb5bea0 --- /dev/null +++ b/examples/react-reload/README.md @@ -0,0 +1,17 @@ +### Example: React app with hot-reload + +Simple React app demonstrating the file synchronization mode in conjunction with webpack hot module reload. + +#### Init + +```bash +skaffold dev +``` + +#### Workflow + +* Make some changes to `HelloWorld.js`: + * The file will be synchronized to the cluster + * `webpack` will perform hot module reloading +* Make some changes to `package.json`: + * The full build/push/deploy process will be triggered, fetching dependencies from `npm` diff --git a/examples/structure-tests/README.adoc b/examples/structure-tests/README.md similarity index 72% rename from examples/structure-tests/README.adoc rename to examples/structure-tests/README.md index a5a8e0625ec..f79cae244e7 100644 --- a/examples/structure-tests/README.adoc +++ b/examples/structure-tests/README.md @@ -1,28 +1,25 @@ -=== Example: Running container-structure-test on built images -:icons: font +### Example: Running container-structure-test on built images This example shows how to run -https://github.com/GoogleContainerTools/container-structure-test[structure tests] +[structure tests](https://github.com/GoogleContainerTools/container-structure-test) on newly built images in your skaffold dev loop. Tests are associated with single artifacts, and one or more test files can be provided. Tests are configured in your `skaffold.yaml` in the `test` stanza, e.g. -[source,yaml] ----- +```yaml test: - image: gcr.io/k8s-skaffold/skaffold-example structureTests: - ./test/* ----- +``` Tests can also be configured through profiles, e.g. -[source,yaml] ----- +```yaml profiles: - name: test test: - image: gcr.io/k8s-skaffold/skaffold-example structureTests: - ./test/profile_structure_test.yaml ----- +``` diff --git a/examples/tagging-with-environment-variables/README.adoc b/examples/tagging-with-environment-variables/README.adoc deleted file mode 100644 index 30703f3071d..00000000000 --- a/examples/tagging-with-environment-variables/README.adoc +++ /dev/null @@ -1,45 +0,0 @@ -=== Example: using the envTemplate tag policy -:icons: font - -This example reuses the image name and uses an environment variable `FOO` to tag the image. -The way you configure it in `skaffold.yaml` is the following build stanza: - -[source,yaml] ----- -build: - artifacts: - - image: gcr.io/k8s-skaffold/skaffold-example - tagPolicy: # <1> - envTemplate: # <1> - template: "{{.IMAGE_NAME}}:{{.FOO}}" # <2> ----- -<1> define tagPolicy to be envTemplate -<2> use https://golang.org/pkg/text/template[go templates] syntax - -The `IMAGE_NAME` variable is built-in and reuses the value defined in the artifacts' `image`. - - -ifndef::env-github[] - - -==== link:{github-repo-tree}/examples/tagging-with-environment-variables[Example files icon:github[]] -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,go, indent=3, title=main.go, syntax=go] ----- -include::main.go[] ----- - -[source,docker, indent=3, title=Dockerfile] ----- -include::Dockerfile[] ----- - -[source,yaml, indent=3, title=k8s-pod.yaml] ----- -include::k8s-pod.yaml[] ----- -endif::[] diff --git a/examples/tagging-with-environment-variables/README.md b/examples/tagging-with-environment-variables/README.md new file mode 100644 index 00000000000..184e26ee842 --- /dev/null +++ b/examples/tagging-with-environment-variables/README.md @@ -0,0 +1,17 @@ +### Example: using the envTemplate tag policy + +This example reuses the image name and uses an environment variable `FOO` to tag the image. +The way you configure it in `skaffold.yaml` is the following build stanza: + +```yaml +build: + artifacts: + - image: gcr.io/k8s-skaffold/skaffold-example + tagPolicy: + envTemplate: + template: "{{.IMAGE_NAME}}:{{.FOO}}" +``` + +1. define `tagPolicy` to be `envTemplate` +2. use [go templates](https://golang.org/pkg/text/template) syntax +3. The `IMAGE_NAME` variable is built-in and reuses the value defined in the artifacts' `image`. \ No newline at end of file diff --git a/integration/examples/bazel/README.adoc b/integration/examples/bazel/README.adoc deleted file mode 100644 index 02d0c4838b4..00000000000 --- a/integration/examples/bazel/README.adoc +++ /dev/null @@ -1,42 +0,0 @@ -=== Example: bazel -:icons: font - -Bazel is one of the supported builders in Skaffold. -The way you configure it in `skaffold.yaml` is the following build stanza: - -[source,yaml] ----- -build: - artifacts: - - image: gcr.io/k8s-skaffold/skaffold-example - context: . <1> - bazel: # <2> - target: //:skaffold_example.tar # <3> ----- -<1> make sure the context contains the bazel files (`WORKSPACE`, `BUILD`) -<2> add bazel to each artifact -<3> specify target - our builder will use this to load to the image to the Docker daemon - -ifndef::env-github[] -==== link:{github-repo-tree}/examples/bazel[Example files icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,go, indent=3, title=main.go, syntax=go] ----- -include::main.go[] ----- - -[source,bazel, indent=3, title=WORKSPACE] ----- -include::WORKSPACE[] ----- - -[source,bazel, indent=3, title=BUILD] ----- -include::BUILD[] ----- -endif::[] diff --git a/integration/examples/bazel/README.md b/integration/examples/bazel/README.md new file mode 100644 index 00000000000..0c31660d138 --- /dev/null +++ b/integration/examples/bazel/README.md @@ -0,0 +1,18 @@ +### Example: bazel + +Bazel is one of the supported builders in Skaffold. + +The way you configure it in `skaffold.yaml` is the following build stanza: + +```yaml +build: + artifacts: + - image: gcr.io/k8s-skaffold/skaffold-example + context: . + bazel: + target: //:skaffold_example.tar +``` + +1. make sure the `context` contains the bazel files (`WORKSPACE`, `BUILD`) +2. add `bazel` section to each artifact +3. specify `target` - our builder will use this to load to the image to the Docker daemon diff --git a/integration/examples/buildpacks/README.md b/integration/examples/buildpacks/README.md new file mode 100644 index 00000000000..87e6f8d132a --- /dev/null +++ b/integration/examples/buildpacks/README.md @@ -0,0 +1,7 @@ +### Example: kaniko + +This is an example demonstrating: + +* **building** a single Go file app built with [Cloud Native Buildpacks](https://buildpacks.io/) +* **tagging** using the default tagPolicy (`gitCommit`) +* **deploying** a single container pod using `kubectl` diff --git a/integration/examples/compose/README.adoc b/integration/examples/compose/README.adoc deleted file mode 100644 index 494c948092f..00000000000 --- a/integration/examples/compose/README.adoc +++ /dev/null @@ -1,10 +0,0 @@ -=== Example: Running skaffold with docker-compose files -:icons: font - -This example provides a simple application set up to run with -https://docs.docker.com/compose/[docker-compose]. -Notice there is no skaffold configuration present: to run this example, -first run `skaffold init --compose-file docker-compose.yaml`, which will -invoke the https://github.com/kubernetes/kompose[kompose] binary to generate -kubernetes manifests based off of the docker-compose configuration, and then run -`skaffold init` to generate the skaffold configuration. diff --git a/integration/examples/compose/README.md b/integration/examples/compose/README.md new file mode 100644 index 00000000000..652de133314 --- /dev/null +++ b/integration/examples/compose/README.md @@ -0,0 +1,15 @@ +### Example: running Skaffold with docker-compose files + +This example provides a simple application set up to run with +[Docker Compose](https://docs.docker.com/compose/). + +Notice there is no `skaffold.yaml` configuration present. +To run this example, use: + +```bash +skaffold init --compose-file docker-compose.yaml +``` + +1. This will invoke the [kompose](https://github.com/kubernetes/kompose) binary to generate +kubernetes manifests based off of the Docker Compose configuration. +2. This will generate the `skaffold.yaml` configuration. diff --git a/integration/examples/custom/README.adoc b/integration/examples/custom/README.md similarity index 55% rename from integration/examples/custom/README.adoc rename to integration/examples/custom/README.md index 6dd401b7bd8..1a8d661adc5 100644 --- a/integration/examples/custom/README.adoc +++ b/integration/examples/custom/README.md @@ -1,27 +1,27 @@ -=== Example: Getting started with buildpacks -:icons: font +### Example: use the custom builder with Cloud Native Buildpacks -This is a simple example based on +This example shows how the custom builder can be used to +build artifacts with Cloud Native Buildpacks. -* *building* a single go file app with buildpacks -* *tagging* using the default tagPolicy (`gitCommit`) -* *deploying* a single container pod using `kubectl` +* **building** a single Go file app with buildpacks +* **tagging** using the default tagPolicy (`gitCommit`) +* **deploying** a single container pod using `kubectl` -## Before you begin +#### Before you begin For this tutorial to work, 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 https://skaffold.dev/docs/getting-started[getting started docs]. +To learn more about how to set up Skaffold and a Kubernetes cluster, see the [getting started docs](https://skaffold.dev/docs/getting-started). To use buildpacks with Skaffold, please install the following additional tools: -* https://buildpacks.io/docs/install-pack/[pack] -* https://docs.docker.com/install/[docker] +* [pack](https://buildpacks.io/docs/install-pack/) +* [docker](https://docs.docker.com/install/) -## Tutorial +#### Tutorial This tutorial will demonstrate how Skaffold can build a simple Hello World Go application with buildpacks and deploy it to a Kubernetes cluster. -First, clone the Skaffold https://github.com/GoogleContainerTools/skaffold[repo] and navigate to the https://github.com/GoogleContainerTools/skaffold/tree/master/examples/buildpacks[buildpacks example] for sample code: +First, clone the Skaffold [repo](https://github.com/GoogleContainerTools/skaffold) and navigate to the [buildpacks example](https://github.com/GoogleContainerTools/skaffold/tree/master/examples/buildpacks) for sample code: ```shell $ git clone https://github.com/GoogleContainerTools/skaffold @@ -54,7 +54,8 @@ build: custom: buildCommand: ./build.sh ``` -For more information about how this works, see the Skaffold custom builder https://skaffold.dev/docs/how-tos/builders/#custom-build-script-run-locally[documentation]. + +For more information about how this works, see the Skaffold custom builder [documentation](https://skaffold.dev/docs/how-tos/builders/#custom-build-script-run-locally). Now, use Skaffold to deploy this application to your Kubernetes cluster: @@ -63,30 +64,12 @@ $ skaffold run --tail --default-repo ``` With this command, Skaffold will build the `skaffold-example` artifact with buildpacks and deploy the application to Kubernetes. -You should be able to see "Hello, World!" printed every second in the Skaffold logs. +You should be able to see *Hello, World!* printed every second in the Skaffold logs. + +#### Cleanup To clean up your Kubernetes cluster, run: ```shell $ skaffold delete ``` - -ifndef::env-github[] -==== link:{github-repo-tree}/examples/buildpacks[Example files icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,go, indent=3, title=main.go, syntax=go] ----- -include::main.go[] ----- - -[source,yaml, indent=3, title=k8s-pod.yaml] ----- -include::k8s-pod.yaml[] ----- - -endif::[] diff --git a/integration/examples/gcb-kaniko/README.adoc b/integration/examples/gcb-kaniko/README.adoc deleted file mode 100644 index f90ed055aa1..00000000000 --- a/integration/examples/gcb-kaniko/README.adoc +++ /dev/null @@ -1,33 +0,0 @@ -=== Example: Getting started with a simple go app -:icons: font - -This is a simple example based on - -* *building* a single go file app and with a multistage `Dockerfile` using https://github.com/GoogleContainerTools/kaniko[kaniko] in Google Cloud Build -* *tagging* using the default tagPolicy (`gitCommit`) -* *deploying* a single container pod using `kubectl` - -ifndef::env-github[] -==== link:{github-repo-tree}/examples/getting-started[Example files icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,go, indent=3, title=main.go, syntax=go] ----- -include::main.go[] ----- - -[source,docker, indent=3, title=Dockerfile] ----- -include::Dockerfile[] ----- - -[source,yaml, indent=3, title=k8s-pod.yaml] ----- -include::k8s-pod.yaml[] ----- - -endif::[] diff --git a/integration/examples/gcb-kaniko/README.md b/integration/examples/gcb-kaniko/README.md new file mode 100644 index 00000000000..f4e65c3c097 --- /dev/null +++ b/integration/examples/gcb-kaniko/README.md @@ -0,0 +1,7 @@ +### Example: Getting started with a simple go app + +This is a simple example based on: + +* **building** a single Go file app and with a multistage `Dockerfile` using [kaniko](https://github.com/GoogleContainerTools/kaniko) in Google Cloud Build +* **tagging** using the default tagPolicy (`gitCommit`) +* **deploying** a single container pod using `kubectl` diff --git a/integration/examples/generate-pipeline/README.adoc b/integration/examples/generate-pipeline/README.md similarity index 73% rename from integration/examples/generate-pipeline/README.adoc rename to integration/examples/generate-pipeline/README.md index ff993154a42..68a6039910d 100644 --- a/integration/examples/generate-pipeline/README.adoc +++ b/integration/examples/generate-pipeline/README.md @@ -1,5 +1,4 @@ -=== Example: Getting started with skaffold and CI/CD using Tekton -:icons: font +### Example: Getting started with skaffold and CI/CD using Tekton This is a simple example to show users how to run the generate-pipeline command @@ -7,15 +6,16 @@ _Please keep in mind that the generate-pipeline command is still a WIP_ Prerequisites: -* Install tekton on your cluster (https://github.com/tektoncd/pipeline/blob/master/docs/install.md) -* Have kaniko secrets setup (https://github.com/GoogleContainerTools/kaniko) +* Install [tekton](https://github.com/tektoncd/pipeline/blob/master/docs/install.md) on your cluster +* Have [kaniko](https://github.com/GoogleContainerTools/kaniko) secrets setup * Container registry must be public * Give your default service account the cluster-admin role (necessary to have pipeline access secrets) ----- + +```shell kubectl create clusterrolebinding serviceaccounts-cluster-admin \ --clusterrole=cluster-admin \ --user=system:serviceaccount:default:default ----- +``` To generate and run a pipeline: diff --git a/integration/examples/getting-started/README.adoc b/integration/examples/getting-started/README.adoc deleted file mode 100644 index ba15fd56e93..00000000000 --- a/integration/examples/getting-started/README.adoc +++ /dev/null @@ -1,33 +0,0 @@ -=== Example: Getting started with a simple go app -:icons: font - -This is a simple example based on - -* *building* a single go file app and with a multistage `Dockerfile` using local docker to build -* *tagging* using the default tagPolicy (`gitCommit`) -* *deploying* a single container pod using `kubectl` - -ifndef::env-github[] -==== link:{github-repo-tree}/examples/getting-started[Example files icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,go, indent=3, title=main.go, syntax=go] ----- -include::main.go[] ----- - -[source,docker, indent=3, title=Dockerfile] ----- -include::Dockerfile[] ----- - -[source,yaml, indent=3, title=k8s-pod.yaml] ----- -include::k8s-pod.yaml[] ----- - -endif::[] diff --git a/integration/examples/getting-started/README.md b/integration/examples/getting-started/README.md new file mode 100644 index 00000000000..a87d20a507b --- /dev/null +++ b/integration/examples/getting-started/README.md @@ -0,0 +1,7 @@ +### Example: Getting started with a simple go app + +This is a simple example based on: + +* **building** a single Go file app and with a multistage `Dockerfile` using local docker to build +* **tagging** using the default tagPolicy (`gitCommit`) +* **deploying** a single container pod using `kubectl` \ No newline at end of file diff --git a/integration/examples/google-cloud-build/README.adoc b/integration/examples/google-cloud-build/README.adoc deleted file mode 100644 index 4b4e8b09266..00000000000 --- a/integration/examples/google-cloud-build/README.adoc +++ /dev/null @@ -1,33 +0,0 @@ -=== Example: Getting started with a simple go app -:icons: font - -This is a simple example based on - -* *building* a single go file app and with a multistage `Dockerfile` using Google Cloud Build -* *tagging* using the default tagPolicy (`gitCommit`) -* *deploying* a single container pod using `kubectl` - -ifndef::env-github[] -==== link:{github-repo-tree}/examples/getting-started[Example files icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,go, indent=3, title=main.go, syntax=go] ----- -include::main.go[] ----- - -[source,docker, indent=3, title=Dockerfile] ----- -include::Dockerfile[] ----- - -[source,yaml, indent=3, title=k8s-pod.yaml] ----- -include::k8s-pod.yaml[] ----- - -endif::[] diff --git a/integration/examples/google-cloud-build/README.md b/integration/examples/google-cloud-build/README.md new file mode 100644 index 00000000000..ba5577be07d --- /dev/null +++ b/integration/examples/google-cloud-build/README.md @@ -0,0 +1,7 @@ +### Example: Getting started with a simple go app + +This is a simple example based on: + +* **building** a single Go file app and with a multistage `Dockerfile` using Google Cloud Build +* **tagging** using the default tagPolicy (`gitCommit`) +* **deploying** a single container pod using `kubectl` diff --git a/integration/examples/helm-deployment-dependencies/README.adoc b/integration/examples/helm-deployment-dependencies/README.md similarity index 71% rename from integration/examples/helm-deployment-dependencies/README.adoc rename to integration/examples/helm-deployment-dependencies/README.md index 9a1cff3e1a1..016bb81c943 100644 --- a/integration/examples/helm-deployment-dependencies/README.adoc +++ b/integration/examples/helm-deployment-dependencies/README.md @@ -1,15 +1,12 @@ -=== Example: helm-dependencies -:icons: font +### Example: deploy helm charts with local dependencies -==== Deploy helm charts with local dependencies - -This example follows the link:{github-repo-tree}/examples/helm-deployment-dependencies[helm] example, but with a local chart as a depenency. +This example follows the [helm](../helm-deployment) example, but with a local chart as a dependency. The `skipBuildDependencies` option is used to skip the `helm dep build` command. This must be disabled for charts with local dependencies. The image can be passed to the subchart using the standard Helm format of `subchart-name.value`. -``` +```yaml deploy: helm: releases: diff --git a/integration/examples/helm-deployment/README.adoc b/integration/examples/helm-deployment/README.md similarity index 78% rename from integration/examples/helm-deployment/README.adoc rename to integration/examples/helm-deployment/README.md index ac728ada731..8b803f93560 100644 --- a/integration/examples/helm-deployment/README.adoc +++ b/integration/examples/helm-deployment/README.md @@ -1,19 +1,13 @@ -=== Example: helm -:icons: font - -ifndef::env-github[] -link:{github-repo-tree}/examples/helm-deployment[see on Github icon:github[]] -endif::[] - -==== Deploy multiple releases with Helm +### Example: deploy multiple releases with Helm You can deploy multiple releases with skaffold, each will need a chartPath, a values file, and namespace. Skaffold can inject intermediate build tags in the the values map in the skaffold.yaml. -Let's walk through the skaffold yaml +Let's walk through the skaffold yaml: We'll be building an image called `skaffold-helm`, and its a dockerfile, so we'll add it to the artifacts. -``` + +```yaml build: artifacts: - image: skaffold-helm @@ -21,7 +15,8 @@ build: Now, we want to deploy this image with helm. We add a new release in the helm part of the deploy stanza. -``` + +```yaml deploy: helm: releases: @@ -35,7 +30,8 @@ deploy: ``` This part tells skaffold to set the `image` parameter of the values file to the built skaffold-helm image and tag. -``` + +```yaml values: image: skaffold-helm ``` diff --git a/integration/examples/hot-reload/README.md b/integration/examples/hot-reload/README.md new file mode 100644 index 00000000000..3fa2da3e6d0 --- /dev/null +++ b/integration/examples/hot-reload/README.md @@ -0,0 +1,18 @@ +### Example: hot-reload with Node and Python + +Application demonstrating the file synchronization mode with both NodeJS and Python. + +#### Init + +```bash +skaffold dev +``` + +#### Workflow + +* Make some changes to `node/src/index.js`: + * The file will be synchronized to the cluster + * `nodemon` will restart the application +* Make some changes to `python/src/app.py`: + * The file will be synchronized to the cluster + * `flask` will restart the application diff --git a/integration/examples/jib-gradle/README.md b/integration/examples/jib-gradle/README.md new file mode 100644 index 00000000000..853459c217d --- /dev/null +++ b/integration/examples/jib-gradle/README.md @@ -0,0 +1,15 @@ +### Example: Jib (Gradle) + +[Jib](https://github.com/GoogleContainerTools/jib) is one of the supported builders in Skaffold. +It builds Docker and OCI images +for your Java applications and is available as plugins for Maven and Gradle. + +The way you configure it in `skaffold.yaml` is the following build stanza: + +```yaml +build: + artifacts: + - image: gcr.io/k8s-skaffold/skaffold-example + context: . + jib: {} +``` diff --git a/examples/jib-multimodule/README.adoc b/integration/examples/jib-multimodule/README.md similarity index 57% rename from examples/jib-multimodule/README.adoc rename to integration/examples/jib-multimodule/README.md index 7dfdcbd5b45..98946823329 100644 --- a/examples/jib-multimodule/README.adoc +++ b/integration/examples/jib-multimodule/README.md @@ -1,8 +1,7 @@ -=== Example: Jib Multi-Module -:icons: font +### Example: Jib Multi-Module -Jib is one of the supported builders in Skaffold. -https://github.com/GoogleContainerTools/jib[Jib] builds Docker and OCI images +[Jib](https://github.com/GoogleContainerTools/jib) is one of the supported builders in Skaffold. +It builds Docker and OCI images for your Java applications and is available as plugins for Maven and Gradle. Sometimes a project is configured to have multiple _modules_ to create several @@ -11,8 +10,7 @@ required. The way you configure it in `skaffold.yaml` is the following build stanza: -[source,yaml] ----- +```yaml build: artifacts: - image: gcr.io/k8s-skaffold/skaffold-jib-1 @@ -29,26 +27,12 @@ build: context: . jib: project: :artifactId ----- +``` There are a few caveats: - - The `jib-maven-plugin` must be either be configured referenced in the - root module of the project. This is easily done through a `pluginManagement` - block. +- The `jib-maven-plugin` must be either be configured referenced in the +root module of the project. This is easily done through a `pluginManagement` +block. - - The artifact modules must have a `jib:xxx` goal bound to the `package` phase. - -ifndef::env-github[] -==== link:{github-repo-tree}/examples/jib[Example files icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,xml, indent=3, title=pom.xml, syntax=xml] ----- -include::pom.xml[] ----- -endif::[] +- The artifact modules must have a `jib:xxx` goal bound to the `package` phase. diff --git a/integration/examples/jib/README.adoc b/integration/examples/jib/README.md similarity index 54% rename from integration/examples/jib/README.adoc rename to integration/examples/jib/README.md index 1c49e6c847a..4ff86e5382e 100644 --- a/integration/examples/jib/README.adoc +++ b/integration/examples/jib/README.md @@ -1,36 +1,20 @@ -=== Example: Jib -:icons: font +### Example: Jib (Maven) -Jib is one of the supported builders in Skaffold. -[Jib](https://github.com/GoogleContainerTools/jib) builds Docker and OCI images +[Jib](https://github.com/GoogleContainerTools/jib) is one of the supported builders in Skaffold. +It builds Docker and OCI images for your Java applications and is available as plugins for Maven and Gradle. The way you configure it in `skaffold.yaml` is the following build stanza: -[source,yaml] ----- +```yaml build: artifacts: - image: gcr.io/k8s-skaffold/skaffold-example context: . jib: {} ----- +``` Please note that this example is for a standalone Maven project, where all dependencies are resolved from outside. The Jib builder requires that the projects are configured to use the Jib plugins for Maven or Gradle. Multi-module builds require a bit additional configuration. - -ifndef::env-github[] -==== link:{github-repo-tree}/examples/jib[Example files icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,xml, indent=3, title=pom.xml, syntax=xml] ----- -include::pom.xml[] ----- -endif::[] diff --git a/integration/examples/kaniko-local/README.adoc b/integration/examples/kaniko-local/README.adoc deleted file mode 100644 index f0eaa62695a..00000000000 --- a/integration/examples/kaniko-local/README.adoc +++ /dev/null @@ -1,34 +0,0 @@ -=== Example: kaniko-local -:icons: font - -This is an example demonstrating - -* *building* a single go file app and with a single stage `Dockerfile` using https://github.com/GoogleContainerTools/kaniko[kaniko] to build on a K8S cluster directly from a local build context -* *tagging* using the default tagPolicy (`gitCommit`) -* *deploying* a single container pod using `kubectl` - -ifndef::env-github[] -==== Example files -link:{github-repo-tree}/examples/kaniko[see on Github icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,go, indent=3, title=main.go, syntax=go] ----- -include::main.go[] ----- - -[source,docker, indent=3, title=Dockerfile] ----- -include::Dockerfile[] ----- - -[source,yaml, indent=3, title=k8s-pod.yaml] ----- -include::k8s-pod.yaml[] ----- - -endif::[] diff --git a/integration/examples/kaniko-local/README.md b/integration/examples/kaniko-local/README.md new file mode 100644 index 00000000000..0e877b5a804 --- /dev/null +++ b/integration/examples/kaniko-local/README.md @@ -0,0 +1,7 @@ +### Example: kaniko-local + +This is an example demonstrating: + +* **building** a single Go file app and with a single stage `Dockerfile` using [kaniko](https://github.com/GoogleContainerTools/kaniko) to build on a K8S cluster directly from a local build context +* **tagging** using the default tagPolicy (`gitCommit`) +* **deploying** a single container pod using `kubectl` diff --git a/integration/examples/kaniko/README.adoc b/integration/examples/kaniko/README.adoc deleted file mode 100644 index 537f94a53a6..00000000000 --- a/integration/examples/kaniko/README.adoc +++ /dev/null @@ -1,34 +0,0 @@ -=== Example: kaniko -:icons: font - -This is an example demonstrating - -* *building* a single go file app and with a single stage `Dockerfile` using https://github.com/GoogleContainerTools/kaniko[kaniko] to build on a K8S cluster -* *tagging* using the default tagPolicy (`gitCommit`) -* *deploying* a single container pod using `kubectl` - -ifndef::env-github[] -==== Example files -link:{github-repo-tree}/examples/kaniko[see on Github icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,go, indent=3, title=main.go, syntax=go] ----- -include::main.go[] ----- - -[source,docker, indent=3, title=Dockerfile] ----- -include::Dockerfile[] ----- - -[source,yaml, indent=3, title=k8s-pod.yaml] ----- -include::k8s-pod.yaml[] ----- - -endif::[] diff --git a/integration/examples/kaniko/README.md b/integration/examples/kaniko/README.md new file mode 100644 index 00000000000..c88f8483535 --- /dev/null +++ b/integration/examples/kaniko/README.md @@ -0,0 +1,7 @@ +### Example: kaniko + +This is an example demonstrating: + +* **building** a single Go file app and with a single stage `Dockerfile` using [kaniko](https://github.com/GoogleContainerTools/kaniko) to build on a K8S cluster +* **tagging** using the default tagPolicy (`gitCommit`) +* **deploying** a single container pod using `kubectl` diff --git a/integration/examples/kustomize/README.adoc b/integration/examples/kustomize/README.adoc deleted file mode 100644 index 8da32c884af..00000000000 --- a/integration/examples/kustomize/README.adoc +++ /dev/null @@ -1,44 +0,0 @@ -=== Example: kustomize -:icons: font - -This is an example demonstrating how skaffold can work with kustomize with the `skaffold deploy` command. - -ifndef::env-github[] -==== Example files -link:{github-repo-tree}/examples/kustomize[see on Github icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,yaml, indent=3, title=kustomization.yaml] ----- -include::kustomization.yaml[] ----- - -[source,patch, indent=3, title=patch.yaml] ----- -include::patch.yaml[] ----- - -[source,patch, indent=3, title=deployment.yaml] ----- -include::deployment.yaml[] ----- - -endif::[] - -=== Example: passing arguments to kustomize -:icons: font - -This is an example demonstrating how additional arguments can be passed to the `kustomize build` command. - -ifndef::env-github[] - -[source,yaml, indent=3, title=skaffold-kustomize-args.yaml] ----- -include::skaffold-kustomize-args.yaml[] ----- - -endif::[] diff --git a/integration/examples/kustomize/README.md b/integration/examples/kustomize/README.md new file mode 100644 index 00000000000..efebf3bace4 --- /dev/null +++ b/integration/examples/kustomize/README.md @@ -0,0 +1,3 @@ +### Example: kustomize + +This is an example demonstrating: how skaffold can work with kustomize with the `skaffold deploy` command. diff --git a/examples/microservices/README.adoc b/integration/examples/microservices/README.md similarity index 85% rename from examples/microservices/README.adoc rename to integration/examples/microservices/README.md index 0c6afd3910d..b856c1ed289 100644 --- a/examples/microservices/README.adoc +++ b/integration/examples/microservices/README.md @@ -1,9 +1,4 @@ -=== Example: µSvcs with Skaffold -:icons: font - -ifndef::env-github[] -link:{github-repo-tree}/examples/microservices[see on Github icon:github[]] -endif::[] +### Example: µSvcs with Skaffold In this example: @@ -14,10 +9,10 @@ In this example: In the real world, Kubernetes deployments will consist of multiple applications that work together. In this example, we'll walk through using skaffold to develop and deploy two applications, an exposed "web" frontend which calls an unexposed "app" backend. -**WARNING:** *If you're running this on a cloud cluster, this example will create a service and expose a webserver. -It's highly suggested that you only run this example on a local, private cluster like minikube or Kubernetes in Docker for Desktop.* +**WARNING: If you're running this on a cloud cluster, this example will create a service and expose a webserver. +It's highly suggested that you only run this example on a local, private cluster like minikube or Kubernetes in Docker for Desktop.** -==== Running the example on minikube +#### Running the example on minikube From this directory, run @@ -44,17 +39,19 @@ func handler(w http.ResponseWriter, r *http.Request) { ``` Once you see the log message + ``` [leeroy-app-5b4dfdcbc6-6vf6r leeroy-app] 2018/03/30 06:28:47 leeroy app server ready ``` + Your service will be ready to hit again with -``` +```bash $ curl $(minikube service leeroy-web --url) leeroooooy app!!! ``` -==== Configuration walkthrough +#### Configuration walkthrough Let's walk through the first part of the skaffold.yaml @@ -70,7 +67,6 @@ We're deploying a `leeroy-web` image, which we build in the context of its subdi `leeroy-web` will listen for requests, and then make a simple HTTP call to `leeroy-app` using Kubernetes service discovery and return that result. - In the deploy stanza, we use the glob matching pattern to deploy all YAML and JSON files in the respective Kubernetes manifest directories. ```yaml diff --git a/integration/examples/nodejs/README.adoc b/integration/examples/nodejs/README.adoc deleted file mode 100644 index 09811fd152d..00000000000 --- a/integration/examples/nodejs/README.adoc +++ /dev/null @@ -1,16 +0,0 @@ -=== Example: Node.js with hot-reload -:icons: font - -Simple example based on Node.js demonstrating the file synchronization mode. - -==== Init -`skaffold dev` - -==== Workflow -* Make some changes to `index.js`: -** The file will be synchronized to the cluster -** `nodemon` will restart the application -* Make some changes to `package.json`: -** The full build/push/deploy process will be triggered, fetching dependencies from `npm` - - diff --git a/integration/examples/nodejs/README.md b/integration/examples/nodejs/README.md new file mode 100644 index 00000000000..fae16103a12 --- /dev/null +++ b/integration/examples/nodejs/README.md @@ -0,0 +1,19 @@ +### Example: Node.js with hot-reload + +Simple example based on Node.js demonstrating the file synchronization mode. + +#### Init + +```bash +skaffold dev +``` + +#### Workflow + +* Make some changes to `index.js`: + * The file will be synchronized to the cluster + * `nodemon` will restart the application +* Make some changes to `package.json`: + * The full build/push/deploy process will be triggered, fetching dependencies from `npm` + + diff --git a/integration/examples/profile-patches/README.adoc b/integration/examples/profile-patches/README.md similarity index 66% rename from integration/examples/profile-patches/README.adoc rename to integration/examples/profile-patches/README.md index 20be56b59d2..9435507fa4b 100644 --- a/integration/examples/profile-patches/README.adoc +++ b/integration/examples/profile-patches/README.md @@ -1,23 +1,14 @@ -=== Example: Getting started with a simple go app -:icons: font +### Example: Getting started with a simple go app This is a simple show-case of how Skaffold profiles can be patched. Patched profiles e.g. can be used in development to provide a composable development setup. Here, a "base" service is always started. Two additional services "hello" and "world" can be activated via profiles. -==== Init -Use the `--profile` option to add profiles `skaffold dev --profile hello,world` - -==== Workflow -* Build only the `base-service` when using the main profile -* Build `hello` and/or `world` when specified via `-p` flag. Multiple `-p` flags are supported as well as comma separated values. +#### Init -ifndef::env-github[] -==== link:{github-repo-tree}/examples/profiles[Example files icon:github[]] +Use the `--profile` option to add profiles `skaffold dev --profile hello,world` -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- +#### Workflow -endif::[] +* Build only the `base-service` when using the main profile +* Build `hello` and/or `world` when specified via `-p` flag. Multiple `-p` flags are supported as well as comma separated values. \ No newline at end of file diff --git a/integration/examples/profiles/README.adoc b/integration/examples/profiles/README.md similarity index 62% rename from integration/examples/profiles/README.adoc rename to integration/examples/profiles/README.md index f84bada61f4..ad8ee6eb4d3 100644 --- a/integration/examples/profiles/README.adoc +++ b/integration/examples/profiles/README.md @@ -1,22 +1,13 @@ -=== Example: Getting started with a simple go app -:icons: font +### Example: Getting started with a simple go app This is a simple show-case of Skaffold profiles -==== Init +#### Init + Use the `--profile` option to enable a particular profile `skaffold dev --profile staging-profile` -==== Workflow +#### Workflow + * Build only the `world-service` when using the main profile * Activate `minikube-profile` automatically when the current context is `minikube`. Only build the `hello-service` in that case. * Build both services when the `staging-profile` is used. Override the kube-context to `staging` in that case. - -ifndef::env-github[] -==== link:{github-repo-tree}/examples/profiles[Example files icon:github[]] - -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -endif::[] diff --git a/integration/examples/react-reload/README.adoc b/integration/examples/react-reload/README.adoc deleted file mode 100644 index c339ea85229..00000000000 --- a/integration/examples/react-reload/README.adoc +++ /dev/null @@ -1,16 +0,0 @@ -=== Example: React app with hot-reload -:icons: font - -Simple React app demonstrating the file synchronization mode in conjunction with webpack hot module reload. - -==== Init -`skaffold dev` - -==== Workflow -* Make some changes to `HelloWorld.js`: -** The file will be synchronized to the cluster -** `webpack` will perform hot module reloading -* Make some changes to `package.json`: -** The full build/push/deploy process will be triggered, fetching dependencies from `npm` - - diff --git a/integration/examples/react-reload/README.md b/integration/examples/react-reload/README.md new file mode 100644 index 00000000000..44c3cb5bea0 --- /dev/null +++ b/integration/examples/react-reload/README.md @@ -0,0 +1,17 @@ +### Example: React app with hot-reload + +Simple React app demonstrating the file synchronization mode in conjunction with webpack hot module reload. + +#### Init + +```bash +skaffold dev +``` + +#### Workflow + +* Make some changes to `HelloWorld.js`: + * The file will be synchronized to the cluster + * `webpack` will perform hot module reloading +* Make some changes to `package.json`: + * The full build/push/deploy process will be triggered, fetching dependencies from `npm` diff --git a/integration/examples/structure-tests/README.adoc b/integration/examples/structure-tests/README.md similarity index 72% rename from integration/examples/structure-tests/README.adoc rename to integration/examples/structure-tests/README.md index a5a8e0625ec..f79cae244e7 100644 --- a/integration/examples/structure-tests/README.adoc +++ b/integration/examples/structure-tests/README.md @@ -1,28 +1,25 @@ -=== Example: Running container-structure-test on built images -:icons: font +### Example: Running container-structure-test on built images This example shows how to run -https://github.com/GoogleContainerTools/container-structure-test[structure tests] +[structure tests](https://github.com/GoogleContainerTools/container-structure-test) on newly built images in your skaffold dev loop. Tests are associated with single artifacts, and one or more test files can be provided. Tests are configured in your `skaffold.yaml` in the `test` stanza, e.g. -[source,yaml] ----- +```yaml test: - image: gcr.io/k8s-skaffold/skaffold-example structureTests: - ./test/* ----- +``` Tests can also be configured through profiles, e.g. -[source,yaml] ----- +```yaml profiles: - name: test test: - image: gcr.io/k8s-skaffold/skaffold-example structureTests: - ./test/profile_structure_test.yaml ----- +``` diff --git a/integration/examples/tagging-with-environment-variables/README.adoc b/integration/examples/tagging-with-environment-variables/README.adoc deleted file mode 100644 index 30703f3071d..00000000000 --- a/integration/examples/tagging-with-environment-variables/README.adoc +++ /dev/null @@ -1,45 +0,0 @@ -=== Example: using the envTemplate tag policy -:icons: font - -This example reuses the image name and uses an environment variable `FOO` to tag the image. -The way you configure it in `skaffold.yaml` is the following build stanza: - -[source,yaml] ----- -build: - artifacts: - - image: gcr.io/k8s-skaffold/skaffold-example - tagPolicy: # <1> - envTemplate: # <1> - template: "{{.IMAGE_NAME}}:{{.FOO}}" # <2> ----- -<1> define tagPolicy to be envTemplate -<2> use https://golang.org/pkg/text/template[go templates] syntax - -The `IMAGE_NAME` variable is built-in and reuses the value defined in the artifacts' `image`. - - -ifndef::env-github[] - - -==== link:{github-repo-tree}/examples/tagging-with-environment-variables[Example files icon:github[]] -[source,yaml, indent=3, title=skaffold.yaml] ----- -include::skaffold.yaml[] ----- - -[source,go, indent=3, title=main.go, syntax=go] ----- -include::main.go[] ----- - -[source,docker, indent=3, title=Dockerfile] ----- -include::Dockerfile[] ----- - -[source,yaml, indent=3, title=k8s-pod.yaml] ----- -include::k8s-pod.yaml[] ----- -endif::[] diff --git a/integration/examples/tagging-with-environment-variables/README.md b/integration/examples/tagging-with-environment-variables/README.md new file mode 100644 index 00000000000..184e26ee842 --- /dev/null +++ b/integration/examples/tagging-with-environment-variables/README.md @@ -0,0 +1,17 @@ +### Example: using the envTemplate tag policy + +This example reuses the image name and uses an environment variable `FOO` to tag the image. +The way you configure it in `skaffold.yaml` is the following build stanza: + +```yaml +build: + artifacts: + - image: gcr.io/k8s-skaffold/skaffold-example + tagPolicy: + envTemplate: + template: "{{.IMAGE_NAME}}:{{.FOO}}" +``` + +1. define `tagPolicy` to be `envTemplate` +2. use [go templates](https://golang.org/pkg/text/template) syntax +3. The `IMAGE_NAME` variable is built-in and reuses the value defined in the artifacts' `image`. \ No newline at end of file