Restructure Docs (#421)

knative · Sep 30, 2019 · ffbf684 · ffbf684
1 parent 7a813be
commit ffbf684
Show file tree

Hide file tree

Showing 15 changed files with 210 additions and 154 deletions.
diff --git a/README.md b/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:**

diff --git a/docs/README.md b/docs/README.md
@@ -30,72 +30,24 @@ 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.
 
-## Commands
-
-See the [generated documentation](cmd/kn.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.
-
-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.
-
-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. 
+## Commands
 
-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.
+* See the [generated documentation](cmd/kn.md) 
+* See the documentation on [managing `kn`](operations/management.md)
 
-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
+## Plugins
 
-These are commands that provide some useful information to the user.
+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.
 
-* 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)
diff --git a/docs/cmd/kn_plugin.md b/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
-
diff --git a/docs/operations/README.md b/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)
diff --git a/docs/operations/autoscaling.md b/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. 
diff --git a/docs/plugins.md → docs/operations/labeling.md b/docs/plugins.md → docs/operations/labeling.md
diff --git a/docs/operations/management.md b/docs/operations/management.md
@@ -0,0 +1,57 @@
+# Management Commands
+
+## 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.
+
+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.
+
+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
+```
+
+## 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
+
+For every Kn command you can use these optional common additional flags:
+
+* `-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)
diff --git a/docs/operations/others.md b/docs/operations/others.md
@@ -0,0 +1 @@
+TODO
diff --git a/docs/operations/resources.md b/docs/operations/resources.md
@@ -0,0 +1 @@
+TODO
diff --git a/docs/plugins/README.md b/docs/plugins/README.md
@@ -0,0 +1,11 @@
+# `kn` Plugins
+
+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](https://github.com/knative/client/tree/master/docs/cmd/kn_plugin.md) shows how to install and create new plugins as well as gives some examples and best practices.
+
+To see what plugins are installed on your machine, you can use the [`plugin`](https://github.com/knative/client/tree/master/docs/cmd/kn_plugin.md) command group's [`list`](https://github.com/knative/client/tree/master/docs/cmd/kn_plugin_list.md) command.
+
+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 on how to write your own plugins.
+
+* [kn plugin](../cmd/kn_plugin.md)	 - Plugin command group
diff --git a/docs/traffic/README.md b/docs/traffic/README.md
@@ -0,0 +1,8 @@
+# Traffic Splitting
+
+kn can help you control which revisions get traffic in your Knative Service.
+
+A Knative Service has a traffic mapping, which is a mapping of revisions of the Service to percent amounts of traffic, along with the ability to create unique URLs for particular revisions. It also has the ability to assign traffic to the latest Revision, which can change as new revisions are created.
+
+* [Traffic Operations](revisions.md)
+* [Examples](examples.md)
diff --git a/docs/traffic/examples.md b/docs/traffic/examples.md
@@ -0,0 +1,66 @@
+# Traffic Splitting Examples
+
+1. Tag revisions `echo-v1` and `echo-v2` as `stable` and `staging` respectively:
+```
+kn service update svc --tag echo-v1=stable --tag echo-v2=staging
+```
+
+2. Ramp up/down revision `echo-v3` to `20%`, adjusting other traffic to accommodate:
+```
+kn service update svc --traffic echo-v3=20 --traffic echo-v2=80
+```
+
+3. Give revision `echo-v3` tag `candidate`, without otherwise changing any traffic split:
+```
+kn service update svc --tag echo-v3=candidate
+```
+
+4. Give `echo-v3` tag `candidate`, and `2%` of traffic adjusting other traffic to go to revision `echo-v2`:
+```
+kn service update svc --tag echo-v3=candidate --traffic candidate=2 --traffic echo-v2=98
+```
+
+6. Update tag for `echo-v3` from `candidate` to `current`:
+```
+kn service update svc --untag candidate --tag echo-v3=current
+```
+
+7. Remove tag `current` from `echo-v3`:
+```
+kn service update svc --untag current
+```
+
+8. Remove `echo-v3` having no tag(s) entirely, adjusting `echo-v2` to fill up:
+```
+kn service update svc --traffic echo-v2=100    # a target having no-tags or no-traffic gets removed
+```
+
+9. Remove `echo-v1` and its tag `old` from the traffic assignments entirely:
+```
+kn service update svc --untag old --traffic echo-v1=0
+```
+
+10. Tag revision `echo-v1` with `stable` as well as `current`, and `50-50%` traffic split to each:
+```
+kn service update svc --tag echo-v1=stable,echo-v2=current --traffic stable=50,current=50
+```
+
+11. Revert all the traffic to the latest ready revision of service:
+```
+kn service update svc --traffic @latest=100
+```
+
+12. Tag latest ready revision of service as `current`:
+```
+kn service update svc --tag @latest=current
+```
+
+13. Update tag for `echo-v4` to `testing` and assign all traffic to it:
+```
+kn service update svc --untag oldv4 --tag echo-v4=testing --traffic testing=100
+```
+
+14. Update `latest` tag of `echo-v1` with `old` tag, give `latest` to `echo-v2`:
+```
+kn service update svc --untag latest --tag echo-v1=old --tag echo-v2=latest
+```