egctl Usage

July 25, 2025 ยท View on GitHub

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] \
 [--auto-cert-email EMAIL] \
 [--auto-cert-domain-name DOMAIN_NAME] \
 [--dns-provider KEY=VALUE] \
 [--dns-provider KEY2=VALUE2]

For example:

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

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:

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

kind: AutoCertManager
name: AutoCertManager
email: someone@megaease.com
domains:
  - name: "*.megaease.com"
    dnsProvider:
      name: dnspod
      zone: megaease.com
      apiToken: <token value>

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"

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.

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.

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 ai enable                        # enable AI Gateway feature

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

# current used context.
current-context: context-default

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

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

# "users" section contains "user" information.
# "username" and "password" are used for basic authentication.
# either the pair ("client-key", "client-certificate") or the pair ("client-key-data", "client-certificate-data") contains the client certificate.
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
  ...
...
# providing a non-empty client-ca-file will force the server to verify the client certificate.
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