Merge branch 'master' into issue338

CHANGELOG.adoc

@@ -58,6 +58,10 @@
 | Add documentation for traffic splitting and tagging targets
 | https://github.com/knative/client/pull/331[#331]
 
+| 🎁
+| Add --service-account flag
+| https://github.com/knative/client/pull/401[#401]
+
 |===
 
 ## v0.2.0 (2019-07-10)

README.md

@@ -1,7 +1,6 @@
 # Knative Client
 
-This section outlines best practices for the Knative developer experience, is a reference for Knative CLI
-implementation, and a reference for Knative client libraries.
+This section outlines best practices for the Knative developer experience. It is a reference for Knative CLI implementation, and a reference for Knative client libraries.
 
 The goals of the Knative Client are to:
 
@@ -16,7 +15,6 @@ The goals of the Knative Client are to:
 Start with the [user's guide](docs/README.md) to learn more. You can read about common use cases, get detailed documentation on each command, and learn how to extend the `kn` CLI. For more information, access the following links:
 
 * [User's guide](docs/README.md)
-* [Basic workflows](docs/workflows.md) (use cases)
 * [Generated documentation](docs/cmd/kn.md)
 
 **Bash auto completion:**

docs/README.md

@@ -30,9 +30,7 @@ You'll need a `kubectl`-style config file to connect to your cluster.
  * Instructions for Red Hat [OpenShift](https://docs.openshift.com/container-platform/4.1/cli_reference/administrator-cli-commands.html#create-kubeconfig).
  * Or contact your cluster administrator.
 
-`kn` will pick up your `kubectl` config file in the default location of
-`$HOME/.kube/config`. You can specify an alternate kubeconfig connection file
-with `--kubeconfig`, or the env var `$KUBECONFIG`, for any command.
+`kn` will pick up your `kubectl` config file in the default location of `$HOME/.kube/config`. You can specify an alternate kubeconfig connection file with `--kubeconfig`, or the env var `$KUBECONFIG`, for any command.
 
 ## Kn Config
 
@@ -57,69 +55,22 @@ cat ~/.kn/config.yaml
 lookupPluginsInPath: true
 pluginsdir: ~/.kn/plugins
 ```
+----------------------------------------------------------
 
 ## Commands
 
-See the [generated documentation](cmd/kn.md)
+* See the [generated documentation](cmd/kn.md) 
+* See the documentation on [managing `kn`](operations/management.md)
 
-### Service Management
 
-A Knative service is the embodiment of a serverless workload. It is generally in the form of a collection of containers running in a group of pods, in the underlying Kubernetes cluster. Each Knative service associates with a collection of revisions, which represent the evolution of that service.
+## Plugins
 
-With the Kn CLI a user can [`list`](cmd/kn_service_list.md), [`create`](cmd/kn_service_create.md), [`delete`](cmd/kn_service_delete.md), and [`update`](cmd/kn_service_update.md) Knative services. The [detail reference](cmd/kn_service.md) of each sub-command under the [`service`](cmd/kn_service.md) command shows the options and flags for this group of commands.
+Kn supports plugins, which allow you to extend the functionality of your `kn` installation with custom commands as well as shared commands that are not part of the core distribution of `kn`. See the [plugins documentation](plugins/README.md) for more information.
 
-Examples:
 
-```bash
-# Create a new service from an image
-
-kn service create mysvc --env KEY1=VALUE1 --env KEY2=VALUE2 --image dev.local/ns/image:latest
-```
-
-You are able to also specify the requests and limits of both CPU and memory when creating a service. See [`service create`](cmd/kn_service_create.md) command reference for additional details.
-
-```bash
-# List existing services in the 'default' namespace of your cluster
-
-kn service list
-```
-
-You can also list services from all namespaces or a specific namespace using flags: `--all-namespaces` and `--namespace mynamespace`. See [`service list`](cmd/kn_service_list.md) command reference for additional details.
-
-### Revision Management
-
-A Knative revision is a "snapshot" of the specification of a service. For instance, when a Knative service is created with the environment variable `FOO=bar` a revision is added to the service. Afterwards, when the environment variable is changed to `baz` or additional variables are added, a new revision is created. When the image that the service is running is changed to a new digest, a new revision is created.
-
-With the [`revision`](cmd/kn_revision.md) command group you can [list](cmd/kn_revision_list.md) and [describe](cmd/kn_revision_describe.md) the current revisions on a service.
-
-Examples:
-
-```bash
-# Listing a service's revision
-
-kn revision list --service srvc # CHECK this since current command does not have --service flag
-```
-
-### Plugins
-
-Kn supports plugins, which allow you to extend the functionality of your Kn installation with custom commands as well as shared commands that are not part of the core distribution of Kn. 
-
-Plugins follow a similar architecture to [kubectl plugins](https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/) with some small differences. One key difference is that Kn plugins can either live in your `PATH` or in a chosen and specified directory. [Kn plugins](plugins.md) shows how to install and create new plugins as well as giving some examples and best practices.
-
-To see what plugins are installed on your machine, you can use the [`plugin`](cmd/kn_plugin.md) command group's [`list`](cmd/kn_plugin_list.md) command.
-
-### Utilities
-
-These are commands that provide some useful information to the user.
-
-* The `kn help` command displays a list of the commands with helpful information.
-* The [`kn version`](cmd/kn_version.md) command will display the current version of the `kn` build including date and Git commit revision.
-* The `kn completion` command will output a BASH completion script for `kn` to allow command completions with tabs.
-
-### Common Flags
+## More information on `kn`:
 
-For every Kn command you can use these optional common additional flags:
+* [Workflows](workflows/README.md)
+* [Operations](operations/README.md)
+* [Traffic Splitting](traffic/README.md)
 
-* `-h` or `--help` to display specific help for that command
-* `--config string` which specifies the Kn config file (default is $HOME/.kn.yaml)
-* `--kubeconfig string` which specifies the kubectl config file (default is $HOME/.kube/config)

docs/cmd/kn_plugin.md

@@ -4,9 +4,10 @@ Plugin command group
 
 ### Synopsis
 
-Provides utilities for interacting and managing with kn plugins.
+Provides utilities for interacting and managing with `kn` plugins.
+
+Plugins provide extended functionality that is not part of the core `kn` command-line distribution.
 
-Plugins provide extended functionality that is not part of the core kn command-line distribution.
 Please refer to the documentation and examples for more information about how write your own plugins.
 
 ```
@@ -33,4 +34,3 @@ kn plugin [flags]
 
 * [kn](kn.md)	 - Knative client
 * [kn plugin list](kn_plugin_list.md)	 - List plugins
-

docs/cmd/kn_revision_delete.md

@@ -22,7 +22,7 @@ kn revision delete NAME [flags]
 
 ```
   -h, --help               help for delete
-  -n, --namespace string   List the requested object(s) in given namespace.
+  -n, --namespace string   Specify the namespace to operate in.
 ```
 
 ### Options inherited from parent commands

docs/cmd/kn_revision_describe.md

@@ -15,7 +15,7 @@ kn revision describe NAME [flags]
 ```
       --allow-missing-template-keys   If true, ignore any errors in templates when a field or map key is missing in the template. Only applies to golang and jsonpath output formats. (default true)
   -h, --help                          help for describe
-  -n, --namespace string              List the requested object(s) in given namespace.
+  -n, --namespace string              Specify the namespace to operate in.
   -o, --output string                 Output format. One of: json|yaml|name|go-template|go-template-file|template|templatefile|jsonpath|jsonpath-file. (default "yaml")
       --template string               Template string or path to template file to use when -o=go-template, -o=go-template-file. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview].
 ```

docs/cmd/kn_revision_list.md

@@ -33,7 +33,7 @@ kn revision list [name] [flags]
   -A, --all-namespaces                If present, list the requested object(s) across all namespaces. Namespace in current context is ignored even if specified with --namespace.
       --allow-missing-template-keys   If true, ignore any errors in templates when a field or map key is missing in the template. Only applies to golang and jsonpath output formats. (default true)
   -h, --help                          help for list
-  -n, --namespace string              List the requested object(s) in given namespace.
+  -n, --namespace string              Specify the namespace to operate in.
       --no-headers                    When using the default output format, don't print headers (default: print headers).
   -o, --output string                 Output format. One of: json|yaml|name|go-template|go-template-file|template|templatefile|jsonpath|jsonpath-file.
   -s, --service string                Service name

docs/cmd/kn_route_describe.md

@@ -15,7 +15,7 @@ kn route describe NAME [flags]
 ```
       --allow-missing-template-keys   If true, ignore any errors in templates when a field or map key is missing in the template. Only applies to golang and jsonpath output formats. (default true)
   -h, --help                          help for describe
-  -n, --namespace string              List the requested object(s) in given namespace.
+  -n, --namespace string              Specify the namespace to operate in.
   -o, --output string                 Output format. One of: json|yaml|name|go-template|go-template-file|template|templatefile|jsonpath|jsonpath-file. (default "yaml")
       --template string               Template string or path to template file to use when -o=go-template, -o=go-template-file. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview].
 ```

docs/cmd/kn_route_list.md

@@ -30,7 +30,7 @@ kn route list NAME [flags]
   -A, --all-namespaces                If present, list the requested object(s) across all namespaces. Namespace in current context is ignored even if specified with --namespace.
       --allow-missing-template-keys   If true, ignore any errors in templates when a field or map key is missing in the template. Only applies to golang and jsonpath output formats. (default true)
   -h, --help                          help for list
-  -n, --namespace string              List the requested object(s) in given namespace.
+  -n, --namespace string              Specify the namespace to operate in.
       --no-headers                    When using the default output format, don't print headers (default: print headers).
   -o, --output string                 Output format. One of: json|yaml|name|go-template|go-template-file|template|templatefile|jsonpath|jsonpath-file.
       --template string               Template string or path to template file to use when -o=go-template, -o=go-template-file. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview].

docs/cmd/kn_service_create.md

@@ -52,12 +52,13 @@ kn service create NAME --image IMAGE [flags]
       --lock-to-digest           keep the running image for the service constant when not explicitly specifying the image. (--no-lock-to-digest pulls the image tag afresh with each new revision) (default true)
       --max-scale int            Maximal number of replicas.
       --min-scale int            Minimal number of replicas.
-  -n, --namespace string         List the requested object(s) in given namespace.
+  -n, --namespace string         Specify the namespace to operate in.
       --no-lock-to-digest        do not keep the running image for the service constant when not explicitly specifying the image. (--no-lock-to-digest pulls the image tag afresh with each new revision)
   -p, --port int32               The port where application listens on.
       --requests-cpu string      The requested CPU (e.g., 250m).
       --requests-memory string   The requested memory (e.g., 64Mi).
       --revision-name string     The revision name to set. Must start with the service name and a dash as a prefix. Empty revision name will result in the server generating a name for the revision. Accepts golang templates, allowing {{.Service}} for the service name, {{.Generation}} for the generation, and {{.Random [n]}} for n random consonants. (default "{{.Service}}-{{.Random 5}}-{{.Generation}}")
+      --service-account string   Service account name to set. Empty service account name will result to clear the service account.
       --wait-timeout int         Seconds to wait before giving up on waiting for service to be ready. (default 60)
 ```
 

docs/cmd/kn_service_delete.md

@@ -25,7 +25,7 @@ kn service delete NAME [flags]
 
 ```
   -h, --help               help for delete
-  -n, --namespace string   List the requested object(s) in given namespace.
+  -n, --namespace string   Specify the namespace to operate in.
 ```
 
 ### Options inherited from parent commands

docs/cmd/kn_service_describe.md

@@ -15,7 +15,7 @@ kn service describe NAME [flags]
 ```
       --allow-missing-template-keys   If true, ignore any errors in templates when a field or map key is missing in the template. Only applies to golang and jsonpath output formats. (default true)
   -h, --help                          help for describe
-  -n, --namespace string              List the requested object(s) in given namespace.
+  -n, --namespace string              Specify the namespace to operate in.
   -o, --output string                 Output format. One of: json|yaml|name|go-template|go-template-file|template|templatefile|jsonpath|jsonpath-file.
       --template string               Template string or path to template file to use when -o=go-template, -o=go-template-file. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview].
   -v, --verbose                       More output.

docs/cmd/kn_service_list.md

@@ -30,7 +30,7 @@ kn service list [name] [flags]
   -A, --all-namespaces                If present, list the requested object(s) across all namespaces. Namespace in current context is ignored even if specified with --namespace.
       --allow-missing-template-keys   If true, ignore any errors in templates when a field or map key is missing in the template. Only applies to golang and jsonpath output formats. (default true)
   -h, --help                          help for list
-  -n, --namespace string              List the requested object(s) in given namespace.
+  -n, --namespace string              Specify the namespace to operate in.
       --no-headers                    When using the default output format, don't print headers (default: print headers).
   -o, --output string                 Output format. One of: json|yaml|name|go-template|go-template-file|template|templatefile|jsonpath|jsonpath-file.
       --template string               Template string or path to template file to use when -o=go-template, -o=go-template-file. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview].

docs/cmd/kn_service_update.md

@@ -50,12 +50,13 @@ kn service update NAME [flags]
       --lock-to-digest           keep the running image for the service constant when not explicitly specifying the image. (--no-lock-to-digest pulls the image tag afresh with each new revision) (default true)
       --max-scale int            Maximal number of replicas.
       --min-scale int            Minimal number of replicas.
-  -n, --namespace string         List the requested object(s) in given namespace.
+  -n, --namespace string         Specify the namespace to operate in.
       --no-lock-to-digest        do not keep the running image for the service constant when not explicitly specifying the image. (--no-lock-to-digest pulls the image tag afresh with each new revision)
   -p, --port int32               The port where application listens on.
       --requests-cpu string      The requested CPU (e.g., 250m).
       --requests-memory string   The requested memory (e.g., 64Mi).
       --revision-name string     The revision name to set. Must start with the service name and a dash as a prefix. Empty revision name will result in the server generating a name for the revision. Accepts golang templates, allowing {{.Service}} for the service name, {{.Generation}} for the generation, and {{.Random [n]}} for n random consonants. (default "{{.Service}}-{{.Random 5}}-{{.Generation}}")
+      --service-account string   Service account name to set. Empty service account name will result to clear the service account.
       --tag strings              Set tag (format: --tag revisionRef=tagName) where revisionRef can be a revision or '@latest' string representing latest ready revision. This flag can be specified multiple times.
       --traffic strings          Set traffic distribution (format: --traffic revisionRef=percent) where revisionRef can be a revision or a tag or '@latest' string representing latest ready revision. This flag can be given multiple times with percent summing up to 100%.
       --untag strings            Untag revision (format: --untag tagName). This flag can be spcified multiple times.

docs/operations/README.md

@@ -0,0 +1,8 @@
+# Operations
+
+
+* [Autoscaling](autoscaling.md)
+* [Labeling](labeling.md)
+* [Management](management.md)
+* [Resources](resources.md)
+* [All others](others.md)

docs/operations/autoscaling.md

@@ -0,0 +1,19 @@
+# Autoscaling
+
+The Knative Pod Autoscaler (KPA), provides fast, request-based autoscaling capabilities. To correctly configure autoscaling to zero for revisions, you must modify its paramenters.
+
+`target` defines how many concurrent requests are wanted at a given time (soft limit) and is the recommended configuration for autoscaling in Knative.
+
+The `minScale` and `maxScale` annotations can be used to configure the minimum and maximum number of pods that can serve applications.
+
+You can access autoscaling capabilities by using `kn` to modify Knative services without editing YAML files directly.
+
+Use the `service create` and `service update` commands with the appropriate flags to configure the autoscaling behavior.
+
+
+ Flag | Description|
+:------|:-----------|
+| `--concurrency-limit int`| Hard limit of concurrent requests to be processed by a single replica.
+| `--concurrency-target int`| Recommendation for when to scale up based on the concurrent number of incoming requests. Defaults to `--concurrency-limit`.
+| `--max-scale int`| Maximum number of replicas.
+| `--min-scale int`| Minimum number of replicas.