udpate doc, add examples

README.md

@@ -257,6 +257,13 @@ filters:
 The pipeline means it will forward traffic to 3 backend endpoints, using the
 `roundRobin` load balance policy.
 
+You can also create them using `egctl create httpproxy` command.
+```bash
+egctl create httpproxy demo --port 10080 \ 
+ --rule="/pipeline=http:https://127.0.0.1:9095,http:https://127.0.0.1:9096,http:https://127.0.0.1:9097"
+```
+this command will create `HTTPServer` `demo-server` and `Pipeline` `demo-pipeline-0` which work exactly same to `server-demo` and `pipeline-demo`. See more about [`egctl create httpproxy`](./doc/egctl-cheat-sheet.md#create-httpproxy).
+
 Additionally, we provide a [dashboard](https://cloud.megaease.com) that
 streamlines the aforementioned steps, this intuitive tool can help you create,
 manage HTTPServers, Pipelines and other Easegress configuration.

cmd/client/commandv2/create/createhttpproxy.go

@@ -36,7 +36,8 @@
  "github.com/spf13/cobra"
 )
 
+// CreateHTTPProxyOptions are the options to create a HTTPProxy.
 type CreateHTTPProxyOptions struct {
  Name string
  Port int
  Rules []string
@@ -55,13 +56,38 @@
 
 var createHTTPProxyOptions = &CreateHTTPProxyOptions{}
 
+var createHTTPProxyExamples = `# General case
+egctl create httpproxy NAME --port PORT \ 
+ --rule HOST/PATH=ENDPOINT1,ENDPOINT2 \
+ [--rule HOST/PATH=ENDPOINT1,ENDPOINT2] \
+ [--tls] \
+ [--auto-cert] \
+ [--ca-cert-file CA_CERT_FILE] \
+ [--cert-file CERT_FILE] \
+ [--key-file KEY_FILE]
+
+# Create a HTTPServer (with port 10080) and corresponding Pipelines to direct 
+# request with path "/bar" to "http:https://127.0.0.1:8080" and "http:https://127.0.0.1:8081" and 
+# request with path "/foo" to "http:https://127.0.0.1:8082".
+egctl create httpproxy demo --port 10080 \
+ --rule="/bar=http:https://127.0.0.1:8080,http:https://127.0.0.1:8081" \
+ --rule="/foo=http:https://127.0.0.1:8082"
+
+# Create a HTTPServer (with port 10081) and corresponding Pipelines to direct request 
+# with path prefix "foo.com/prefix" to "http:https://127.0.0.1:8083".
+egctl create httpproxy demo2 --port 10081 \
+ --rule="foo.com/prefix*=http:https://127.0.0.1:8083"
+`
+
+// CreateHTTPProxyCmd returns create command of HTTPProxy.
 func CreateHTTPProxyCmd() *cobra.Command {
  o := createHTTPProxyOptions
 
  cmd := &cobra.Command{
- Use: "httpproxy NAME",
- Short: "Create a HTTPServer and corresponding Pipelines with a specific name",
- Args: createHTTPProxyArgs,
+ Use: "httpproxy NAME",
+ Short: "Create a HTTPServer and corresponding Pipelines with a specific name",
+ Args: createHTTPProxyArgs,
+ Example: general.CreateMultiLineExample(createHTTPProxyExamples),
  Run: func(cmd *cobra.Command, args []string) {
  err := createHTTPProxyRun(cmd, args)
  if err != nil {
@@ -121,24 +147,28 @@
  return nil
 }
 
+// HTTPServerSpec is the spec of HTTPServer.
 type HTTPServerSpec struct {
  Name string `json:"name"`
  Kind string `json:"kind"`
 
  httpserver.Spec `json:",inline"`
 }
 
+// PipelineSpec is the spec of Pipeline.
 type PipelineSpec struct {
  Name string `json:"name"`
  Kind string `json:"kind"`
 
  pipeline.Spec `json:",inline"`
 }
 
+// Complete completes all the required options.
 func (o *CreateHTTPProxyOptions) Complete(args []string) {
  o.Name = args[0]
 }
 
+// Parse parses all the optional options.
 func (o *CreateHTTPProxyOptions) Parse() error {
  // parse rules
  rules := []*CreateHTTPProxyRule{}
@@ -192,6 +222,7 @@
  return fmt.Sprintf("%s-pipeline-%d", o.Name, id)
 }
 
+// Translate translates CreateHTTPProxyOptions to HTTPServerSpec and PipelineSpec.
 func (o *CreateHTTPProxyOptions) Translate() (*HTTPServerSpec, []*PipelineSpec) {
  hs := &HTTPServerSpec{
  Name: o.getServerName(),
@@ -343,7 +374,8 @@
  }, nil
 }
 
+// CreateHTTPProxyRule is the rule of HTTPProxy.
 type CreateHTTPProxyRule struct {
  Host string
  Path string
  PathPrefix string

cmd/client/commandv2/logs.go

@@ -31,11 +31,18 @@ import (
 func LogsCmd() *cobra.Command {
  var n int
  var follow bool
+ examples := []general.Example{
+ {Desc: "Print the most recent 500 logs by default.", Command: "egctl logs"},
+ {Desc: "Print the most recent 100 logs.", Command: "egctl logs --tail 100"},
+ {Desc: "Print all logs.", Command: "egctl logs --tail -1"},
+ {Desc: "Print the most recent 500 logs and streaming the log.", Command: "egctl logs -f"},
+ }
 
  cmd := &cobra.Command{
- Use: "logs",
- Short: "Print the logs of Easegress server",
- Args: cobra.NoArgs,
+ Use: "logs",
+ Short: "Print the logs of Easegress server",
+ Args: cobra.NoArgs,
+ Example: createMultiExample(examples),
  Run: func(cmd *cobra.Command, args []string) {
  query := fmt.Sprintf("?tail=%d&follow=%v", n, follow)
  p := general.LogsURL + query

cmd/client/general/print.go

@@ -266,6 +266,15 @@ func CreateMultiExample(examples []Example) string {
  return output
 }
 
+// CreateMultiLineExample creates cobra example by using multiple lines.
+func CreateMultiLineExample(example string) string {
+ lines := strings.Split(example, "\n")
+ for i, line := range lines {
+ lines[i] = " " + line
+ }
+ return strings.Join(lines, "\n")
+}
+
 // GenerateExampleFromChild generates cobra example from child commands.
 func GenerateExampleFromChild(cmd *cobra.Command) {
  if len(cmd.Commands()) == 0 {

doc/egctl-cheat-sheet.md

@@ -4,7 +4,7 @@
 
 Easegress manifests are defined using YAML. They can be identified by the file extensions `.yaml` or `.yml`. You can create resources using either the `egctl create` or `egctl apply` commands. To view all available resources along with their supported actions, use the `egctl api-resources` command.
 
-```
+```bash
 cat globalfilter.yaml | egctl create -f - # create GlobalFilter resource from stdin
 cat httpserver-new.yaml | egctl apply -f - # create HTTPServer resource from stdin
 
@@ -16,9 +16,73 @@ egctl apply -f ./cdk-demo.yaml # create CustomDataKind resource
 egctl create -f ./custom-data-demo.yaml # create CustomData resource
 ```
 
-## Viewing and finding resources 
+## Create HTTPProxy
+`egctl create httpproxy` is used to create `HTTPServer` and corresponding `Pipelines` quickly.
+
+```bash
+egctl create httpproxy NAME --port PORT \ 
+ --rule HOST/PATH=ENDPOINT1,ENDPOINT2 \
+ [--rule HOST/PATH=ENDPOINT1,ENDPOINT2] \
+ [--tls] \
+ [--auto-cert] \
+ [--ca-cert-file CA_CERT_FILE] \
+ [--cert-file CERT_FILE] \
+ [--key-file KEY_FILE]
+```
+
+For example: 
 
+```bash
+# Create a HTTPServer (with port 10080) and corresponding Pipelines to direct 
+# request with path "/bar" to "http:https://127.0.0.1:8080" and "http:https://127.0.0.1:8081" and 
+# request with path "/foo" to "http:https://127.0.0.1:8082".
+egctl create httpproxy demo --port 10080 \
+ --rule="/bar=http:https://127.0.0.1:8080,http:https://127.0.0.1:8081" \
+ --rule="/foo=http:https://127.0.0.1:8082"
 ```
+
+this equals to 
+```yaml
+kind: HTTPServer
+name: demo-server
+port: 10080
+https: false
+rules:
+ - paths:
+ - path: /bar
+ backend: demo-pipeline-0
+ - path: /foo
+ backend: demo-pipeline-1
+
+---
+name: demo-pipeline-0
+kind: Pipeline
+filters:
+ - name: proxy
+ kind: Proxy
+ pools:
+ - servers:
+ - url: http:https://127.0.0.1:8080
+ - url: http:https://127.0.0.1:8081
+ loadBalance:
+ policy: roundRobin
+
+---
+name: demo-pipeline-1
+kind: Pipeline
+filters:
+ - name: proxy
+ kind: Proxy
+ pools:
+ - servers:
+ - url: http:https://127.0.0.1:8082
+ loadBalance:
+ policy: roundRobin
+```
+
+## Viewing and finding resources 
+
+```bash
 egctl get all # view all resources
 egctl get httpserver httpserver-demo # find HTTPServer resources with name "httpserver-demo"
 
@@ -33,28 +97,32 @@ egctl describe pipeline pipeline-demo # describe Pipeline resource with name "p
 ```
 
 ## Updating resources
-```
+```bash
 egctl apply -f httpserver-demo-version2.yaml # update HTTPServer resource
 egctl apply -f cdk-demo2.yaml # udpate CustomDataKind resource
 ```
 
 ## Editing resources
-```
+```bash
 egctl edit httpserver httpserver-demo # edit httpserver with name httpserver-demo
 egctl edit customdata cdk-demo # batch edit custom data with kind cdk-demo
 egctl edit customdata cdk-demo data1 # edit custom data data1 of kind cdk-demo
 ```
 The default editor for `egctl edit` is `vi`. To change it, update the `EGCTL_EDITOR` environment variable.
 
 ## Deleting resources
-```
+```bash
 egctl delete httpserver httpserver-demo # delete HTTPServer resource with name "httpserver-demo"
 egctl delete httpserver --all # delete all HTTPServer resources
 egctl delete customdatakind cdk-demo cdk-kind # delete CustomDataKind resources named "cdk-demo" and "cdk-kind"
 ```
 
 ## Other commands
-```
+```bash
+egctl logs # print easegress-server logs
+egctl logs --tail 100 # print most recent 100 logs
+egctl logs -f # print logs as stream
+
 egctl api-resources # view all available resources 
 egctl completion zsh # generate completion script for zsh
 egctl health # check easegress health
@@ -131,7 +199,7 @@ cluster:
 client-ca-file: "/tmp/certs/ca.crt"
 ```
 
-```
+```bash
 egctl config current-context # display the current context in use by egctl
 egctl config get-contexts # view all available contexts
 egctl config use-context <name> # update the current-context field in the .egctlrc file to <name>