Merge pull request #1882 from balopat/more_profile_docs

more docs for profiles

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
 

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" %}}

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

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

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",

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"`
 }