From 25fc031236c5d8b47d288fe4da9979e1c497a487 Mon Sep 17 00:00:00 2001 From: balopat Date: Tue, 26 Mar 2019 18:51:43 -0700 Subject: [PATCH] more docs for profiles --- deploy/docs/local-preview.sh | 2 +- .../en/docs/how-tos/profiles/_index.md | 66 +++++++++++++++---- .../en/samples/profiles/activations.yaml | 16 +++++ docs/content/en/samples/profiles/patches.yaml | 17 +++++ docs/content/en/schemas/v1beta8.json | 4 +- pkg/skaffold/schema/latest/config.go | 2 + 6 files changed, 91 insertions(+), 16 deletions(-) create mode 100644 docs/content/en/samples/profiles/activations.yaml create mode 100644 docs/content/en/samples/profiles/patches.yaml diff --git a/deploy/docs/local-preview.sh b/deploy/docs/local-preview.sh index bded5165988..fbb264ca375 100755 --- a/deploy/docs/local-preview.sh +++ b/deploy/docs/local-preview.sh @@ -22,7 +22,7 @@ readonly DOCS_DIR="${CURRENT_DIR}/docs" MOUNTS="-v ${CURRENT_DIR}/.git:/app/.git:ro" MOUNTS="${MOUNTS} -v ${DOCS_DIR}/config.toml:/app/docs/config.toml:ro" -for dir in $(find ${DOCS_DIR} -type dir -mindepth 1 -maxdepth 1 | grep -v themes | grep -v public | grep -v resources | grep -v node_modules); do +for dir in $(find ${DOCS_DIR} -mindepth 1 -maxdepth 1 -type d | grep -v themes | grep -v public | grep -v resources | grep -v node_modules); do MOUNTS="${MOUNTS} -v $dir:/app/docs/$(basename $dir):ro" done diff --git a/docs/content/en/docs/how-tos/profiles/_index.md b/docs/content/en/docs/how-tos/profiles/_index.md index 010afedd371..ec373f347ff 100644 --- a/docs/content/en/docs/how-tos/profiles/_index.md +++ b/docs/content/en/docs/how-tos/profiles/_index.md @@ -16,32 +16,59 @@ For a detailed discussion on Skaffold configuration, see ## Profiles (`profiles`) -Each profile has four parts: +Each profile has six parts: * Name (`name`): The name of the profile * Build configuration (`build`) * Test configuration (`test`) * Deploy configuration (`deploy`) +* Patches (`patches`) +* Activation (`activation`) -Once activated, the specified `build`, `test` and `deploy` configuration -in the profile will override the `build`, `test` and `deploy` sections declared -in `skaffold.yaml`. The `build`, `test` and `deploy` configuration in the `profiles` +Once a profile is activated, the specified `build`, `test` and `deploy` configuration +in it will replace the `build`, `test` and `deploy` sections declared +in the main section of `skaffold.yaml`. The `build`, `test` and `deploy` configuration in the `profiles` section use the same syntax as the `build`, `test` and `deploy` sections of `skaffold.yaml`; for more information, see [Builders](/docs/how-tos/builders), -[Testers](/docs/how-tos/testers), and [Deployers](/docs/how-tos/deployers). +[Testers](/docs/how-tos/testers), [Deployers](/docs/how-tos/deployers) and you can always refer to + [skaffold.yaml reference](/docs/references/yaml/) for an overview of the syntax. + Alternatively, you can override the main configuration with finer grained control using `patches`. -### Activation -You can activate profiles with the `-p` (`--profile`) parameter in the +### Activation + +You can activate a profile two ways: CLI flag or skaffold.yaml activations. + +**CLI flag**: You can activate profiles with the `-p` (`--profile`) parameter in the `skaffold dev` and `skaffold run` commands. + ```bash + skaffold run -p [PROFILE] + ``` + +**Activations in skaffold.yaml**: You can auto-activate a profile based on + +* kubecontext +* environment variable value +* skaffold command (dev/run/build/deploy) + +A profile is auto-activated if any one of the activations under it are triggered. +An activation is triggered if all of the criteria (`env`, `kubeContext`, `command`) are triggered. + + +In the example below: + + * `profile1` is activated if `MAGIC_VAR` is 42 + * `profile2` is activated if `MAGIC_VAR` is 1337 or we are running `skaffold dev` while kubecontext is set to `minikube`. + +{{% readfile file="samples/profiles/activations.yaml" %}} -```bash -skaffold run -p [PROFILE] -``` -### Example +### Override via replacement -The following example, showcases a `skaffold.yaml` with one profile, `gcb`, +The `build`, `test` and `deploy` sections defined in the profile will completely replace the main configuration. +The default values are the same in profiles as in the main config. + +The following example showcases a `skaffold.yaml` with one profile named `gcb`, for building with Google Cloud Build: {{% readfile file="samples/profiles/profiles.yaml" %}} @@ -56,6 +83,19 @@ However, if you run Skaffold with the following command: skaffold dev -p gcb ``` -Skaffold will switch to Google Cloud Build for building artifacts. Note that +Skaffold will switch to Google Cloud Build for building artifacts. + +Note that since the `gcb` profile does not specify a deploy configuration, Skaffold will continue using `kubectl` for deployments. + + +### Override via patches + +Patches are a more verbose way of overriding your config, but they provide a powerful, fine-grained way +to override individual values in your yaml config. They are based on [JSON Patch](http://jsonpatch.com/) under the hood. + +In the example below instead of overriding the whole `build` section, the `dev` profile specifically +defines a different Dockerfile to use for the first artifact. + +{{% readfile file="samples/profiles/patches.yaml" %}} diff --git a/docs/content/en/samples/profiles/activations.yaml b/docs/content/en/samples/profiles/activations.yaml new file mode 100644 index 00000000000..b1f8d1fd06c --- /dev/null +++ b/docs/content/en/samples/profiles/activations.yaml @@ -0,0 +1,16 @@ +build: + artifacts: + - image: gcr.io/k8s-skaffold/skaffold-example +deploy: + kubectl: + manifests: + - k8s-pod +profiles: +- name: profile1 + activation: + - env: MAGIC_VAR=42 +- name: profile2 + activation: + - env: MAGIC_VAR=1337 + - kubeContext: minikube + command: dev diff --git a/docs/content/en/samples/profiles/patches.yaml b/docs/content/en/samples/profiles/patches.yaml new file mode 100644 index 00000000000..07061d161a4 --- /dev/null +++ b/docs/content/en/samples/profiles/patches.yaml @@ -0,0 +1,17 @@ +build: + artifacts: + - image: gcr.io/k8s-skaffold/skaffold-example + docker: + dockerfile: Dockerfile + - image: gcr.io/k8s-skaffold/skaffold2 + - image: gcr.io/k8s-skaffold/skaffold3 +deploy: + kubectl: + manifests: + - k8s-pod +profiles: + - name: dev + patches: + - op: replace + path: /build/artifacts/0/docker/dockerfile + value: Dockerfile_dev diff --git a/docs/content/en/schemas/v1beta8.json b/docs/content/en/schemas/v1beta8.json index a8d353a4637..f93c16490f8 100755 --- a/docs/content/en/schemas/v1beta8.json +++ b/docs/content/en/schemas/v1beta8.json @@ -1541,8 +1541,8 @@ "$ref": "#/definitions/Activation" }, "type": "array", - "description": "criteria by which a profile can be auto-activated.", - "x-intellij-html-description": "criteria by which a profile can be auto-activated." + "description": "criteria by which a profile can be auto-activated. The profile is auto-activated if any one of the activations are triggered. An activation is triggered if all of the criteria (env, kubeContext, command) are triggered.", + "x-intellij-html-description": "criteria by which a profile can be auto-activated. The profile is auto-activated if any one of the activations are triggered. An activation is triggered if all of the criteria (env, kubeContext, command) are triggered." }, "build": { "$ref": "#/definitions/BuildConfig", diff --git a/pkg/skaffold/schema/latest/config.go b/pkg/skaffold/schema/latest/config.go index 6c555aa4c46..86d077bf1ea 100644 --- a/pkg/skaffold/schema/latest/config.go +++ b/pkg/skaffold/schema/latest/config.go @@ -492,6 +492,8 @@ type Profile struct { Patches []JSONPatch `yaml:"patches,omitempty"` // Activation criteria by which a profile can be auto-activated. + // The profile is auto-activated if any one of the activations are triggered. + // An activation is triggered if all of the criteria (env, kubeContext, command) are triggered. Activation []Activation `yaml:"activation,omitempty"` }