Skip to content

Commit

Permalink
Merge pull request #1599 from dgageot/improve-doc
Browse files Browse the repository at this point in the history 
Improve documentation
  • Loading branch information
@dgageot
dgageot authored Feb 5, 2019
2 parents 09ee966 + b4bf9c3 commit 36782cc
Show file tree
Hide file tree
Showing 16 changed files with 132 additions and 126 deletions.
1 change: 0 additions & 1 deletion docs/content/en/docs/_index.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@

---
title: "Skaffold Documentation"
linkTitle: "Documentation"
Expand Down
51 changes: 29 additions & 22 deletions docs/content/en/docs/concepts/_index.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@

---
title: "Concepts"
linkTitle: "Concepts"
Expand All @@ -8,7 +7,6 @@ weight: 80
This document discusses some concepts that can help you develop a deep
understanding of Skaffold.


## Configuration of the Skaffold pipeline (skaffold.yaml)

You can configure Skaffold with the Skaffold configuration file,
Expand All @@ -22,9 +20,9 @@ read the configuration file from the current directory.
| ---------- | ------------|
| `apiVersion` | The Skaffold API version you would like to use. The current API version is {{< skaffold-version >}}. |
| `kind` | The Skaffold configuration file has the kind `Config`. |
| `build` | Specifies how Skaffold should build artifacts. You have control over what tool Skaffold can use, how Skaffold tags artifacts and how Skaffold pushes artifacts. Skaffold supports using local Docker daemon, Google Cloud Build, Kaniko, or Bazel to build artifacts. See [Builders](/docs/how-tos/builders) and [Taggers](/docs/how-tos/taggers) for more information. |
| `test` | Specifies how Skaffold should test artifacts. Skaffold supports [container-structure-tests](https://github.com/GoogleContainerTools/container-structure-test) to test built artifacts. See [Testers](/docs/how-tos/testers) for more information. |
| `deploy` | Specifies how Skaffold should deploy artifacts. Skaffold supports using `kubectl`, Helm, or kustomize to deploy artifacts. See [Deployers](/docs/how-tos/deployers) for more information. |
| `build` | Specifies how Skaffold builds artifacts. You have control over what tool Skaffold can use, how Skaffold tags artifacts and how Skaffold pushes artifacts. Skaffold supports using local Docker daemon, Google Cloud Build, Kaniko, or Bazel to build artifacts. See [Builders](/docs/how-tos/builders) and [Taggers](/docs/how-tos/taggers) for more information. |
| `test` | Specifies how Skaffold tests artifacts. Skaffold supports [container-structure-tests](https://github.com/GoogleContainerTools/container-structure-test) to test built artifacts. See [Testers](/docs/how-tos/testers) for more information. |
| `deploy` | Specifies how Skaffold deploys artifacts. Skaffold supports using `kubectl`, `helm`, or `kustomize` to deploy artifacts. See [Deployers](/docs/how-tos/deployers) for more information. |
| `profiles`| Profile is a set of settings that, when activated, overrides the current configuration. You can use Profile to override the `build`, `test` and `deploy` sections. |

You can learn more about the syntax of `skaffold.yaml` at
Expand All @@ -33,6 +31,7 @@ You can learn more about the syntax of `skaffold.yaml` at
## Global configuration (~/.skaffold/config)

Some context specific settings can be configured in a global configuration file, defaulting to `~/.skaffold/config`. Options can be configured globally or for specific contexts.

The options are:

| Option | Type | Description |
Expand All @@ -41,7 +40,8 @@ The options are:
| `local-cluster` | boolean | If true, do not try to push images after building. By default, contexts with names `docker-for-desktop`, `docker-desktop`, or `minikube` are treated as local. |

For example, to treat any context as local by default:
```

```bash
skaffold config set --global local-cluster true
```

Expand All @@ -68,16 +68,22 @@ This way you can grab a Skaffold project and just `skaffold run` it to deploy to
The way to achieve this is the `default-repo` functionality:

1. Via `default-repo` flag

skaffold dev --default-repo <myrepo>


```bash
skaffold dev --default-repo <myrepo>
```

1. Via `SKAFFOLD_DEFAULT_REPO` environment variable

SKAFFOLD_DEFAULT_REPO=<myrepo> skaffold dev
```bash
SKAFFOLD_DEFAULT_REPO=<myrepo> skaffold dev
```

1. Via Skaffold's global config

skaffold config set default-repo <myrepo>
```bash
skaffold config set default-repo <myrepo>
```
If Skaffold doesn't find `default-repo`, there is no automated image name rewriting.

Expand All @@ -94,15 +100,16 @@ Automated image name rewriting strategies are determined based on the default-re
default-repo: aws_account_id.dkr.ecr.region.amazonaws.com
rewritten image: aws_account_id.dkr.ecr.region.amazonaws.com/gcr_io_k8s-skaffold_skaffold-example1
```
* default-repo begins with "gcr.io" (special case - as GCR allows for infinite deep image repo names)
* **strategy**: concat unless prefix matches
* **example1**: prefix doesn't match:

````
```
original image: gcr.io/k8s-skaffold/skaffold-example1
default-repo: gcr.io/myproject/myimage
rewritten image: gcr.io/myproject/myimage/gcr.io/k8s-skaffold/skaffold-example1
````
```
* **example2**: prefix matches:

```
Expand All @@ -120,28 +127,28 @@ Automated image name rewriting strategies are determined based on the default-re

## Architecture

Skaffold has is designed with pluggability in mind:
Skaffold is designed with pluggability in mind:

![architecture](/images/architecture.png)

The architecture allows you to use Skaffold with the tool you prefer. Skaffold
provides built-in support for the following tools:

* Build
* **Build**
* Dockerfile locally, in-cluster with kaniko or using Google Cloud Build
* Bazel locally
* Jib Maven and Jib Gradle locally or using Google Cloud Build
* Test
* **Test**
* [container-structure-test](https://github.com/GoogleContainerTools/container-structure-test)
* Deploy
* Kubernetes Command-Line Interface (`kubectl`)
* Helm
* kustomize
* Taggers
* **Tag**
* Git tagger
* Sha256 tagger
* Env Template tagger
* DateTime tagger
* **Deploy**
* Kubernetes Command-Line Interface (`kubectl`)
* [Helm](https://helm.sh/)
* [kustomize](https://github.com/kubernetes-sigs/kustomize)

And you can combine the tools as you see fit in Skaffold. For experimental
projects, you may want to use local Docker daemon for building artifacts, and
Expand Down
32 changes: 14 additions & 18 deletions docs/content/en/docs/getting-started/_index.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@

---
title: "Getting Started"
linkTitle: "Getting Started"
Expand All @@ -7,31 +6,31 @@ weight: 10

This document showcases how to get started with Skaffold using [Docker](https://www.docker.com/)
and Kubernetes command-line tool, [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
Aside from Docker and kubectl, Skaffold also supports a variety of other tools
Aside from `Docker` and `kubectl`, Skaffold also supports a variety of other tools
and workflows; see [How-to Guides](/docs/how-tos) and [Tutorials](/docs/tutorials) for
more information.

In this quickstart, you will:

* Install Skaffold
* Download a sample go app
* Use `skaffold dev` to build and deploy your app every time your code changes
* Use `skaffold run` to build and deploy your app once, on demand
* Install Skaffold,
* Download a sample go app,
* Use `skaffold dev` to build and deploy your app every time your code changes,
* Use `skaffold run` to build and deploy your app once, on demand.

## Before you begin

* [Install Docker](https://www.docker.com/get-started)
* [Install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
* Configure kubectl to connect to a Kubernetes cluster. You can use
* Configure `kubectl` to connect to a Kubernetes cluster. You can use
* any Kubernetes platform with Skaffold; see [Picking the Right Solution](https://kubernetes.io/docs/setup/pick-right-solution/)
from Kubernetes documentation for instructions on choosing the
right platfrom.
* [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/)
is a hosted Kubernetes solution. To set up kubectl with Google Kubernetes Engine,
is a hosted Kubernetes solution. To set up `kubectl` with Google Kubernetes Engine,
see [Kubernetes Engine Quickstart](https://cloud.google.com/kubernetes-engine/docs/quickstart).
* [Minikube](https://kubernetes.io/docs/setup/minikube/) is
a local Kubernetes solution best for development and testing. To set up
kubectl with Minikube, see [Installing Minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/).</p>
`kubectl` with Minikube, see [Installing Minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/).</p>

{{< alert title="Note" >}}
If you use a non-local solution, your Docker client needs to be configured
Expand Down Expand Up @@ -70,7 +69,6 @@ chmod +x skaffold
sudo mv skaffold /usr/local/bin
```


{{% /tab %}}

{{% tab "MACOS" %}}
Expand Down Expand Up @@ -109,7 +107,6 @@ sudo mv skaffold /usr/local/bin
```
{{% /tab %}}


{{% tab "WINDOWS" %}}

### Chocolatey
Expand All @@ -128,29 +125,29 @@ For the latest **bleeding edge** build, download and place it in your `PATH`:

https://storage.googleapis.com/skaffold/builds/latest/skaffold-windows-amd64.exe


{{% /tab %}}
{{% /tabs %}}

## Downloading the sample app

1. Clone the Skaffold repository:

```
```bash
git clone https://github.com/GoogleContainerTools/skaffold
```

1. Change to the `examples/getting-started` directory.

```
```bash
cd examples/getting-started
```

## `skaffold dev`: Build and deploy your app every time your code changes

Run command `skaffold dev` to build and deploy your app continuously. You should
see some outputs similar to the following entries:

```bash
```
Starting build...
Found [minikube] context, using local docker daemon.
Sending build context to Docker daemon 6.144kB
Expand Down Expand Up @@ -194,7 +191,6 @@ workflow, which, in this example, is
For skaffold dev, if `imagePullPolicy` is set to `Always` in your Kubernetes manifest, it will expect the image to exist in a remote registry.
{{< /alert >}}

Let's re-trigger the workflow just by a single code change!
Update `main.go` as follows:
Expand All @@ -218,7 +214,7 @@ The moment you save the file, Skaffold will repeat the workflow described in
`skaffold.yaml` and eventually re-deploy your application. Once the pipeline
is completed, you should see updated outputs in the terminal:

```bash
```
[getting-started] Hello Skaffold!
```

Expand Down
21 changes: 10 additions & 11 deletions docs/content/en/docs/how-tos/_index.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,16 @@

---
title: "How-to Guides"
linkTitle: "How-to Guides"
weight: 30
---

| Skaffold Workflow |
|----------|
| [Builders](/docs/how-tos/builders) |
| [Testers](/docs/how-tos/testers) |
| [Deployers](/docs/how-tos/deployers) |
| [Taggers](/docs/how-tos/taggers) |
| [File sync](/docs/how-tos/filesync) |
| [Port forwarding](/docs/how-tos/portforward) |
| [Profiles](/docs/how-tos/profiles) |
| [Templated fields](/docs/how-tos/templating) |
| Skaffold Workflow | |
|----------|---|
| [Builders](/docs/how-tos/builders) | How Docker images are built |
| [Testers](/docs/how-tos/testers) | How images are tested |
| [Taggers](/docs/how-tos/taggers) | How images are tagged |
| [Deployers](/docs/how-tos/deployers) | How your app is deployed to a Kubernetes cluster |
| [File sync](/docs/how-tos/filesync) | File sync for files that don’t require full rebuild |
| [Port forwarding](/docs/how-tos/portforward) | Port forwarding from pods |
| [Profiles](/docs/how-tos/profiles) | Define configurations for different contexts |
| [Templated fields](/docs/how-tos/templating) | Adjust configuration with environment variables |
72 changes: 41 additions & 31 deletions docs/content/en/docs/how-tos/builders/_index.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@

---
title: "Builders"
linkTitle: "Builders"
Expand All @@ -16,7 +15,7 @@ Skaffold supports the following tools to build your image:
* Bazel locally
* [Jib](https://github.com/GoogleContainerTools/jib) Maven and Gradle projects locally
* [Jib](https://github.com/GoogleContainerTools/jib) Maven and Gradle projects remotely with [Google Cloud Build](https://cloud.google.com/cloud-build/docs/)

The `build` section in the Skaffold configuration file, `skaffold.yaml`,
controls how Skaffold builds artifacts. To use a specific tool for building
artifacts, add the value representing the tool and options for using the tool
Expand All @@ -39,13 +38,15 @@ successfully built, Skaffold will push the Docker
images to the remote registry. You can choose to skip this step.

To use the local Docker daemon, add build type `local` to the `build` section
of `skaffold.yaml`. The `local` type offers the following options:
of `skaffold.yaml`.

|Option|Description|
|-----|-----|
|`push`| OPTIONAL. Should images be pushed to a registry. Default value is `false` for local clusters, `true` for remote clusters. |
|`useDockerCLI`| OPTIONAL. Uses Docker command-line interface instead of Docker Engine APIs. Default value is `false`. |
|`useBuildkit`| OPTIONAL. Uses BuildKit to build Docker images. Default value is `false`. |
The `local` type offers the following options:

| Option | Description | Default |
|---------------|-------------|---------|
| `push` | Should images be pushed to a registry | `false` for local clusters, `true` for remote clusters. |
| `useDockerCLI`| Uses `docker` command-line interface instead of Docker Engine APIs | `false` |
| `useBuildkit` | Uses BuildKit to build Docker images | `false` |

The following `build` section, for example, instructs Skaffold to build a
Docker image `gcr.io/k8s-skaffold/example` with the local Docker daemon:
Expand All @@ -65,18 +66,19 @@ be saved to the specified remote registry, such as
[Google Container Registry](https://cloud.google.com/container-registry/).

To use Google Cloud Build, add build type `googleCloudBuild` to the `build`
section of `skaffold.yaml`. The `googleCloudBuild` type offers the following
options:

|Option|Description|
|-----|-----|
|`projectId`| <b>REQUIRED</b> The ID of your Google Cloud Platform Project. |
|`diskSizeGb`| OPTIONAL. The disk size of the VM that runs the build. See [Cloud Build API Reference: Build Options](https://cloud.google.com/cloud-build/docs/api/reference/rest/v1/projects.builds#buildoptions) for more information. |
|`machineType`| OPTIONAL. The type of the VM that runs the build. See [Cloud Build API Reference: Build Options](https://cloud.google.com/cloud-build/docs/api/reference/rest/v1/projects.builds#buildoptions) for more information. |
|`timeOut`| OPTIONAL. The amount of time (in seconds) that this build should be allowed to run. See [Cloud Build API Reference: Resource/Build](https://cloud.google.com/cloud-build/docs/api/reference/rest/v1/projects.builds#resource-build) for more information. |
|`dockerImage`| OPTIONAL. The name of the image that will run a docker build. See [Cloud builders](https://cloud.google.com/cloud-build/docs/cloud-builders) for more information. Default value is `gcr.io/cloud-builders/docker`. |
|`gradleImage`| OPTIONAL. The name of the image that will run a gradle build. See [Cloud builders](https://cloud.google.com/cloud-build/docs/cloud-builders) for more information. Default value is `gcr.io/cloud-builders/gradle`. |
|`mavenImage`| OPTIONAL. The name of the image that will run a maven build. See [Cloud builders](https://cloud.google.com/cloud-build/docs/cloud-builders) for more information. Default value is `gcr.io/cloud-builders/mvn`. |
section of `skaffold.yaml`.

The `googleCloudBuild` type offers the following options:

| Option | Description | Default |
|---------------|-------------|---------|
| `projectId` | **Required** The ID of your Google Cloud Platform Project | |
| `diskSizeGb` | The disk size of the VM that runs the build. See [Cloud Build API Reference: Build Options](https://cloud.google.com/cloud-build/docs/api/reference/rest/v1/projects.builds#buildoptions) for more information | |
| `machineType` | The type of the VM that runs the build. See [Cloud Build API Reference: Build Options](https://cloud.google.com/cloud-build/docs/api/reference/rest/v1/projects.builds#buildoptions) for more information | |
| `timeOut` | The amount of time (in seconds) that this build should be allowed to run. See [Cloud Build API Reference: Resource/Build](https://cloud.google.com/cloud-build/docs/api/reference/rest/v1/projects.builds#resource-build) for more information. | |
| `dockerImage` | The name of the image that will run a docker build. See [Cloud builders](https://cloud.google.com/cloud-build/docs/cloud-builders) for more information | `gcr.io/cloud-builders/docker` |
| `gradleImage` | The name of the image that will run a gradle build. See [Cloud builders](https://cloud.google.com/cloud-build/docs/cloud-builders) for more information | `gcr.io/cloud-builders/gradle` |
| `mavenImage` | The name of the image that will run a maven build. See [Cloud builders](https://cloud.google.com/cloud-build/docs/cloud-builders) for more information | `gcr.io/cloud-builders/mvn` |

The following `build` section, for example, instructs Skaffold to build a
Docker image `gcr.io/k8s-skaffold/example` with Google Cloud Build:
Expand All @@ -93,15 +95,17 @@ that cannot easily or securely run a Docker daemon.
Skaffold can help build artifacts in a Kubernetes cluster using the Kaniko
image; after the artifacts are built, kaniko can push them to remote registries.
To use Kaniko, add build type `kaniko` to the `build` section of
`skaffold.yaml`. The `kaniko` type offers the following options:
`skaffold.yaml`.

The `kaniko` type offers the following options:

|Option|Description|
|-----|-----|
|`buildContext`| OPTIONAL. The Kaniko build context. See [Kaniko Documentation: Using Kaniko](https://github.com/GoogleContainerTools/kaniko#using-kaniko) for more information. |
|`pullSecret`| OPTIONAL. The path to the secret key file. See [Kaniko Documentation: Running Kaniko in a Kubernetes cluster](https://github.com/GoogleContainerTools/kaniko#running-kaniko-in-a-kubernetes-cluster) for more information. |
|`pullSecretName`| OPTIONAL. The name of the Kubernetes secret for pulling the files from the build context and pushing the final image. See [Kaniko Documentation: Running Kaniko in a Kubernetes cluster](https://github.com/GoogleContainerTools/kaniko#running-kaniko-in-a-kubernetes-cluster) for more information. Default value is `kaniko-secret`. |
|`namespace`| OPTIONAL. The Kubernetes namespace. Default value is the current namespace in Kubernetes configuration. |
|`timeout`| OPTIONAL. The amount of time (in seconds) that this build should be allowed to run. Default value is 20 minutes (`20m`). |
| Option | Description | Default |
|-----------------|-------------|---------|
| `buildContext` | The Kaniko build context: `gcsBucket` or `localDir` | `localDir` |
| `pullSecret` | The path to the secret key file. See [Kaniko Documentation: Running Kaniko in a Kubernetes cluster](https://github.com/GoogleContainerTools/kaniko#running-kaniko-in-a-kubernetes-cluster) for more information | |
| `pullSecretName`| The name of the Kubernetes secret for pulling the files from the build context and pushing the final image | `kaniko-secret` |
| `namespace` | The Kubernetes namespace | Current namespace in Kubernetes configuration |
| `timeout` | The amount of time (in seconds) that this build should be allowed to run | 20 minutes (`20m`) |

The following `build` section, for example, instructs Skaffold to build a
Docker image `gcr.io/k8s-skaffold/example` with Kaniko:
Expand All @@ -123,11 +127,17 @@ extensible build system.

Skaffold can help build artifacts using Bazel; after Bazel finishes building
container images, they will be loaded into the local Docker daemon. To use
Bazel, add `workspace` and `bazel` fields to each artifact you specify in the
Bazel, `bazel` field to each artifact you specify in the
`artifacts` part of the `build` section, and use the build type `local`.
`context` should be a path containing the bazel files
(`WORKSPACE` and `BUILD`); The `bazel` field should have a `target`
specification, which Skaffold will use to load the image to the Docker daemon.
(`WORKSPACE` and `BUILD`).

The `bazel` type offers the following options:

| Option | Description |
|-----------|-------------|
| `target` | **Required** The `bazel build` target to run |
| `args` | Additional args to pass to `bazel build` |

The following `build` section, for example, instructs Skaffold to build a
Docker image `gcr.io/k8s-skaffold/example` with Bazel:
Expand Down
Loading

0 comments on commit 36782cc

Please sign in to comment.