Project: Easegress (Orchestration & Management / API Gateway)
File: 2.1.egctl-Usage.md

`egctl` is a command-line tool designed for managing Easegress resources, allowing you to create, update, edit, or delete them with ease. 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 egctl apply -f ./pipeline-demo.yaml # create Pipeline resource egctl create -f ./httpserver-demo.yaml # create HTTPServer resource egctl apply -f ./cdk-demo.yaml # create CustomDataKind resource egctl create -f ./custom-data-demo.yaml # create CustomData resource ``` `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 CACERTFILE] \ [--cert-file CERT_FILE] \ [--key-file KEY_FILE] \ [--auto-cert-email EMAIL] \ [--auto-cert-domain-name DOMAIN_NAME] \ [--dns-provider KEY=VALUE] \ [--dns-provider KEY2=VALUE2] ``` For example: ```bash egctl create httpproxy demo --port 10080 \ --rule="/bar=http://127.0.0.1:8080,http://127.0.0.1:8081" \ --rule="/foo=http://127.0.0.1:8082" ``` this equals to ```yaml kind: HTTPServer name: demo port: 10080 https: false rules: paths: path: /bar backend: demo-0 path: /foo backend: demo-1 name: demo-0 kind: Pipeline filters: name: proxy kind: Proxy pools: servers: url: http://127.0.0.1:8080 url: http://127.0.0.1:8081 loadBalance: policy: roundRobin name: demo-1 kind: Pipeline filters: name: proxy kind: Proxy pools: servers: url: http://127.0.0.1:8082 loadBalance: policy: roundRobin ``` You can use the `egctl create httpproxy` command to create or update an `AutoCertManager`. Below is an example command and its equivalent YAML configuration. For example: ```bash egctl create httpproxy demo2 --port 10081 \ --rule="/bar=http://127.0.0.1:8083" \ --auto-cert \ --auto-cert-email someone@megaease.com \ --auto-cert-domain-name="*.foo.com" \ --dns-provider name=dnspod \ --dns-provider zone=megaease.com \ --dns-provider="apiToken=<tokenvalue>" ``` Parameters: `auto-cert-email`: Required for creating a new `AutoCertManager`. If an `AutoCertManager` exists, this updates its email field. `auto-cert-domain-name` and `dns-provider`: Specify the domain in the `AutoCertManager` config. This either appends to or updates the domains field of `AutoCertManager`. Equivalent YAML Configuration ```yaml kind: AutoCertManager name: AutoCertManager email: someone@megaease.com domains: name: "*.megaease.com" dnsProvider: name: dnspod zone: megaease.com apiToken: <token value> ``` ```bash egctl get all # view all resources egctl get httpserver httpserver-demo # find HTTPServer resources with name "httpserver-demo" egctl get member # view all easegress nodes egctl get member eg-default-name # find easegress node with name "eg-default-name" egctl get customdatakind # view all CustomDataKind resources egctl get customdata cdk-demo # find CustomDataKind resource with name "cdk-demo" egctl describe httpserver # describe all HTTPServer resource egctl describe pipeline

# describe Pipeline resource with name "pipeline-demo" ``` In Easegress, when using `IngressController`, `MeshController`, or `GatewayController`, resources such as `HTTPServers` and `Pipelines` are created in separate namespaces to prevent conflicts. To access these resources, you can utilize the `--namespace` or `--all-namespaces` argument. The use of these arguments is relevant only when employing `IngressController`, `MeshController`, or `GatewayController`. Easegress does not support creating resources in different namespaces by using apis or `egctl` command. ```bash egctl get all --all-namespaces # view all resources in all namespace. egctl get all --namespace default # view all resources in default namespace. egctl describe pipeline --all-namespaces # describe pipeline resources in all namespace. egctl describe httpserver demo --namespace default # describe httpserver demo in default namespace. ``` ```bash egctl apply -f httpserver-demo-version2.yaml # update HTTPServer resource egctl apply -f cdk-demo2.yaml # udpate CustomDataKind resource ``` ```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. ```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" ``` ```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 egctl profile info # show location of profile files egctl profile start cpu ./cpu-profile # start the CPU profile and store the output in the ./cpu-profile file egctl profile stop # stop profile ``` By default, `egctl` searches for a file named `.egctlrc` in the `$HOME` directory. Here's an example of a `.egctlrc` file. ```yaml kind: Config current-context: context-default contexts: context: cluster: cluster-default user: user-default name: context-default clusters: cluster: server: localhost:2381 certificate-authority: "/tmp/certs/ca.crt" certificate-authority-data: "xxxx" name: cluster-default users: name: user-default user: username: user123 password: password client-certificate: "/tmp/certs/client.crt" client-key: "/tmp/certs/client.key" ``` To utilize basic authentication with `username` and `password`, add the following segment to the Easegress configuration YAML file: ```yaml name: easegress-1 cluster: listen-peer-urls: http://localhost:2380 ... ... basic-auth: user123: password admin: admin username: password ``` To verify the client certificate, incorporate the following section into the Easegress configuration YAML file: ```yaml name: easegress-1 cluster: listen-peer-urls: http://localhost:2380 ... ... 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> egctl config view # display the contents of the configuration file ```