mirror of https://github.com/knative/client.git
Copy-edit documentation, and make user guide start with installation. (#125)
* Copy edit docs and add getting-started section. * Remove hash * list to get * list to get
This commit is contained in:
Naomi Seyfer
Knative Prow Robot
parent
e0f4f51e67
commit
a4242b3bb5
13
README.md
13
README.md
|
|
@ -3,7 +3,13 @@
|
|||
Knative developer experience best practices, reference Knative CLI
|
||||
implementation, and reference Knative client libraries.
|
||||
|
||||
If you are interested in contributing, see the Knative community [contribution guide](https://www.knative.dev/contributing/) and [DEVELOPMENT.md](./DEVELOPMENT.md).
|
||||
Goals:
|
||||
|
||||
1. Follow closely the Knative [serving](https://github.com/knative/serving) and [eventing](https://github.com/knative/eventing) APIs
|
||||
2. Be scriptable to allow users to create different Knative workflows
|
||||
3. Expose useful Golang packages to allow integration into other programs or CLIs or plugins
|
||||
4. Use consistent verbs, nouns, and flags for various commands
|
||||
5. Be easily extended via a plugin mechanism (similar to Kubectl) to allow for experimentations and customization
|
||||
|
||||
# Docs
|
||||
|
||||
|
|
@ -12,7 +18,6 @@ Start with the [user's guide](docs/README.md) and from there you can can read ab
|
|||
* [User's guide](docs/README.md)
|
||||
* [Basic workflows](docs/workflows.md) (use cases)
|
||||
* [Generated documentation](docs/cmd/kn.md)
|
||||
* [Plugins](docs/plugins.md) motivation and guide
|
||||
|
||||
**Bash auto completion:**
|
||||
|
||||
|
|
@ -26,10 +31,10 @@ Use TAB to list available sub-commands
|
|||
|
||||
```sh
|
||||
$ kn <TAB>
|
||||
completion revision service
|
||||
completion revision service version
|
||||
|
||||
$ kn revision <TAB>
|
||||
describe list
|
||||
describe get
|
||||
```
|
||||
|
||||
# Developers
|
||||
|
|
|
|||
|
|
@ -1,30 +1,46 @@
|
|||
# Kn
|
||||
# kn
|
||||
|
||||
Kn is the Knative command line interface (CLI).
|
||||
`kn` is the Knative command line interface (CLI).
|
||||
|
||||
It is designed with the goals of:
|
||||
## Getting Started
|
||||
|
||||
1. Following closely the Knative [serving](https://github.com/knative/serving) and [eventing](https://github.com/knative/eventing) APIs
|
||||
2. Being scriptable to allow users to create different Knative workflows
|
||||
3. Exposing useful Golang packages to allow integration into other programs or CLIs or plugins
|
||||
4. Use consistent verbs, nouns, and flags that it exposes for each set (groups or categories) of commands
|
||||
5. To be easily extended via a plugin mechanism (similar to Kubectl) to allow for experimentations and customization
|
||||
### Installing `kn`
|
||||
|
||||
## Command Families
|
||||
You can grab the latest nightly binary executable for:
|
||||
* [Max OS X](https://storage.cloud.google.com/knative-nightly/client/latest/kn-darwin-amd64)
|
||||
* [Linix AMD 64](https://storage.googleapis.com/knative-nightly/client/latest/kn-linux-amd64)
|
||||
* [Windows AMD 64](https://storage.googleapis.com/knative-nightly/client/latest/kn-windows-amd64.exe)
|
||||
|
||||
Most Kn commands typically fall into one of a few categories:
|
||||
Put it on your system path, and make sure it's executable.
|
||||
|
||||
| Type | Used For | Description |
|
||||
|----------------------|--------------------------------|-------------------------------------------------------------------|
|
||||
| Service Management | Managing Kn services | List, create, update, and delete a Kn service |
|
||||
| Revision Management | Managing Kn service revisions | List, create, update, and delete the revision(s) of a Kn service |
|
||||
| Miscellaneous | Collection of utility commands | Show version of Kn, help, plugin list, and other useful commands |
|
||||
Alternately, check out the client repository, and type:
|
||||
|
||||
## Service Management
|
||||
```bash
|
||||
go install ./cmd/kn
|
||||
```
|
||||
|
||||
### Connecting to your cluster
|
||||
|
||||
You'll need a `kubectl`-style config file to connect to your cluster.
|
||||
* Starting [minikube](https://github.com/kubernetes/minikube) writes this file
|
||||
(or gives you an appropriate context in an existing config file)
|
||||
* Instructions for Google [GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl)
|
||||
* Instructions for Amazon [EKS](https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html)
|
||||
* 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.
|
||||
|
||||
## Commands
|
||||
|
||||
See the [generated documentation.](cmd/kn.md)
|
||||
|
||||
### Service Management
|
||||
|
||||
A Knative service is the embodiment of a serverless workload. 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 represents 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` command](cmd/kn_service.md) shows the options and flags for this group of commands.
|
||||
With the Kn CLI a user can list/[`get`](cmd/kn_service_get.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` command](cmd/kn_service.md) shows the options and flags for this group of commands.
|
||||
|
||||
Examples:
|
||||
|
||||
|
|
@ -39,45 +55,37 @@ You are able to also specify the requests and limits of both CPU and memory when
|
|||
```bash
|
||||
# List existing services in the 'default' namespace of your cluster
|
||||
|
||||
kn service list
|
||||
kn service get
|
||||
```
|
||||
|
||||
You can also list services from all namespaces or specific namespace using flags: `--all-namespaces` and `--namespace mynamespace`. See [`service list` command](cmd/kn_service_list.md) reference for additional details.
|
||||
You can also list services from all namespaces or specific namespace using flags: `--all-namespaces` and `--namespace mynamespace`. See [`service get` command](cmd/kn_service_get.md) reference for additional details.
|
||||
|
||||
## Revision Management
|
||||
### Revision Management
|
||||
|
||||
A Knative revision is a change to the specification of a service. For instance, when a Knative service is created with environment variable `FOO=bar` a revision is added to the service. When later the environment variable is changed to `baz` or additional variables are added, a new revision is created. [What other changes can create revisions?]
|
||||
A Knative revision is a "snapshot" of the specification of a service. For instance, when a Knative service is created with environment variable `FOO=bar` a revision is added to the service. When later the environment variable is changed to `baz` or additional variables are added, a new revision is created. When the image the service is running is changed to a new digest, a new revision is created.
|
||||
|
||||
With the [`revision` command group](cmd/kn_revision.md) you can [list](cmd/kn_revision_list.md) and [describe](cmd/kn_revision_describe.md) the current revisions on a service.
|
||||
With the [`revision` command group](cmd/kn_revision.md) you can list/[get](cmd/kn_revision_get.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
|
||||
kn revision get --service srvc # CHECK this since current command does not have --service flag
|
||||
```
|
||||
|
||||
## Miscellaneous
|
||||
|
||||
This is a grab all category for commands that do not fit into the previous categories. We can divide this into two.
|
||||
|
||||
### 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` command](cmd/kn_version.md) will display the current version of the Kn build including date and Git commit revision.
|
||||
* The [`kn completion` command](cmd/kn_completion.md) will output a BASH completion script for Kn to allow command completions with tabs.
|
||||
* The [`kn version` command](cmd/kn_version.md) will display the current version of the `kn` build including date and Git commit revision.
|
||||
* The [`kn completion` command](cmd/kn_completion.md) will output a BASH completion script for `kn` to allow command completions with tabs.
|
||||
|
||||
### Plugins
|
||||
|
||||
[Plugins](plugins.md) are an experimental feature to allow users to extend and customize the Kn CLI.
|
||||
|
||||
## Common Flags
|
||||
### 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)
|
||||
* `--kubeconfig string` which specifies the kubectl config file (default is $HOME/.kube/config)
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ kn revision get [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 get
|
||||
-n, --namespace string List the requested object(s) in given namespace.
|
||||
-o, --output string Output format. One of: json|yaml|name|go-template-file|templatefile|template|go-template|jsonpath|jsonpath-file.
|
||||
-o, --output string Output format. One of: json|yaml|name|template|go-template|go-template-file|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].
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -19,12 +19,25 @@ kn service create NAME --image IMAGE [flags]
|
|||
|
||||
# Create a service with multiple environment variables
|
||||
kn service create mysvc --env KEY1=VALUE1 --env KEY2=VALUE2 --image dev.local/ns/image:latest
|
||||
|
||||
# Create or replace a service 's1' with image dev.local/ns/image:v2 using --force flag
|
||||
# if service 's1' doesn't exist, it's just a normal create operation
|
||||
kn service create --force s1 --image dev.local/ns/image:v2
|
||||
|
||||
# Create or replace environment variables of service 's1' using --force flag
|
||||
kn service create --force s1 --env KEY1=NEW_VALUE1 --env NEW_KEY2=NEW_VALUE2 --image dev.local/ns/image:v1
|
||||
|
||||
# Create or replace default resources of a service 's1' using --force flag
|
||||
# (earlier configured resource requests and limits will be replaced with default)
|
||||
# (earlier configured environment variables will be cleared too if any)
|
||||
kn service create --force s1 --image dev.local/ns/image:v1
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-e, --env stringArray Environment variable to set. NAME=value; you may provide this flag any number of times to set multiple environment variables.
|
||||
--force Create service forcefully, replaces existing service if any.
|
||||
-h, --help help for create
|
||||
--image string Image to run.
|
||||
--limits-cpu string The limits on the requested CPU (e.g., 1000m).
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ kn service get [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 get
|
||||
-n, --namespace string List the requested object(s) in given namespace.
|
||||
-o, --output string Output format. One of: json|yaml|name|go-template-file|templatefile|template|go-template|jsonpath|jsonpath-file.
|
||||
-o, --output string Output format. One of: json|yaml|name|template|go-template|go-template-file|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].
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ The purpose of this section of the Kn documentation is to list common workflows
|
|||
|
||||
In this basic worflow we show the CRUD (create, read, update, delete) operations on a service. We use a well known [simple Hello World service](https://github.com/knative/docs/tree/master/docs/serving/samples/hello-world/helloworld-go) that reads the environment variable `TARGET` and prints it as output.
|
||||
|
||||
* **Create a service from image in `default` namespace**
|
||||
* **Create a service in the `default` namespace from an image**
|
||||
|
||||
```bash
|
||||
kn service create hello --image gcr.io/knative-samples/helloworld-go --env TARGET=Knative
|
||||
|
|
@ -103,4 +103,4 @@ You can then verify that the 'hello' service is deleted by trying to `get` it ag
|
|||
```bash
|
||||
kn service get hello
|
||||
No resources found.
|
||||
```
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue