egctl Usage

egctl is a command-line tool designed for managing Easegress resources, allowing you to create, update, edit, or delete them with ease.

Creating resources

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.

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

Create HTTPProxy

egctl create httpproxy is used to create HTTPServer and corresponding Pipelines quickly.

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:

---
title: Create a HTTPServer (with port 10080) and corresponding Pipelines to direct
linkTitle: Create a HTTPServer (with port 10080) and corresponding Pipelines to direct
weight: 1
---
---
title: request with path "/bar" to "http://127.0.0.1:8080" and "http://127.0.0.1:8081" and
linkTitle: request with path "/bar" to "http://127.0.0.1:8080" and "http://127.0.0.1:8081" and
weight: 1
---
---
title: request with path "/foo" to "http://127.0.0.1:8082".
linkTitle: request with path "/foo" to "http://127.0.0.1:8082".
weight: 1
---
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

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

Viewing and finding resources

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 pipeline-demo  # describe Pipeline resource with name "pipeline-demo"

Updating resources

egctl apply -f httpserver-demo-version2.yaml  # update HTTPServer resource
egctl apply -f cdk-demo2.yaml                 # udpate CustomDataKind resource

Editing resources

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

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

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

Config & Security

By default, egctl searches for a file named .egctlrc in the $HOME directory. Here’s an example of a .egctlrc file.

kind: Config

---
title: current used context.
linkTitle: current used context.
weight: 1
---
current-context: context-default

---
title: "contexts" section contains "user" and "cluster" information, which informs egctl about which "user" should be used to access a specific "cluster".
linkTitle: "contexts" section contains "user" and "cluster" information, which informs egctl about which "user" should be used to access a specific "cluster".
weight: 1
---
contexts:
  - context:
      cluster: cluster-default
      user: user-default
    name: context-default

---
title: "clusters" section contains information about the "cluster".
linkTitle: "clusters" section contains information about the "cluster".
weight: 1
---
---
title: "server" specifies the host address that egctl should access.
linkTitle: "server" specifies the host address that egctl should access.
weight: 1
---
---
title: "certificate-authority" or "certificate-authority-data" contain the root certificate authority that the client uses to verify server certificates.
linkTitle: "certificate-authority" or "certificate-authority-data" contain the root certificate authority that the client uses to verify server certificates.
weight: 1
---
clusters:
  - cluster:
      server: localhost:2381
      certificate-authority: "/tmp/certs/ca.crt" 
      certificate-authority-data: "xxxx"
    name: cluster-default

---
title: "users" section contains "user" information.
linkTitle: "users" section contains "user" information.
weight: 1
---
---
title: "username" and "password" are used for basic authentication.
linkTitle: "username" and "password" are used for basic authentication.
weight: 1
---
---
title: either the pair ("client-key", "client-certificate") or the pair ("client-key-data", "client-certificate-data") contains the client certificate.
linkTitle: either the pair ("client-key", "client-certificate") or the pair ("client-key-data", "client-certificate-data") contains the client certificate.
weight: 1
---
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:

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:

name: easegress-1
cluster:
  listen-peer-urls:
  - http://localhost:2380
  ...
...
---
title: providing a non-empty client-ca-file will force the server to verify the client certificate.
linkTitle: providing a non-empty client-ca-file will force the server to verify the client certificate.
weight: 1
---
client-ca-file: "/tmp/certs/ca.crt"

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