Skip to content

Commit

Permalink
update README (#686)
Browse files Browse the repository at this point in the history 
* update README

* fix grammar

* add architecture.pptx
  • Loading branch information
@localvar
localvar committed Jul 5, 2022
1 parent 8d2c6c8 commit 2294c49
Show file tree
Hide file tree
Showing 6 changed files with 280 additions and 124 deletions.
225 changes: 158 additions & 67 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,9 @@
- [Setting up Easegress](#setting-up-easegress)
- [Create an HTTPServer and Pipeline](#create-an-httpserver-and-pipeline)
- [Test](#test)
- [More Filters](#more-filters)
- [Add Another Pipeline](#add-another-pipeline)
- [Update the HTTPServer](#update-the-httpserver)
- [Test the RSS Pipeline](#test-the-rss-pipeline)
- [Documentation](#documentation)
- [Roadmap](#roadmap)
- [Community](#community)
Expand Down Expand Up @@ -131,11 +133,17 @@ For full list, see [Cookbook](./doc/README.md#1-cookbook--how-to-guide).

## Getting Started

The basic common usage of Easegress is to quickly set up proxy for the backend servers. We split it into multiple simple steps to illustrate the essential concepts and operations.
The basic usage of Easegress is to quickly set up a proxy for the backend
servers. In this section, we will first set up a reverse proxy, and then
demonstrate the API orchestration feature by including more components in the
configuration, we will also show the essential concepts and operations of
Easegress.

### Setting up Easegress

We can download the latest or history binaries from the [release page](https://github.com/megaease/easegress/releases). The following shell script will do:
We can download the latest or history binaries from the
[release page](https://github.com/megaease/easegress/releases). The following
shell script will:

- Download and extract the latest binaries to `./easegress` folder
- Install the Easegress Systemd service.
Expand All @@ -144,7 +152,7 @@ We can download the latest or history binaries from the [release page](https://g
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/megaease/easegress/main/scripts/install.sh)"
```

or if we can install Easegress from source code:
or we can install Easegress from source code:

```bash
git clone https://github.com/megaease/easegress && cd easegress
Expand All @@ -161,27 +169,31 @@ Then we can add the binary directory to the `PATH` and execute the server:
```bash
$ export PATH=${PATH}:$(pwd)/bin/
$ easegress-server
2021-11-26T16:10:08.419+08:00 INFO cluster/config.go:172 etcd config: init-cluster:eg-default-name=http:https://localhost:2380 cluster-state:new force-new-cluster:false
2021-11-26T16:10:09.515+08:00 INFO cluster/cluster.go:400 client connect with endpoints: [http:https://localhost:2380]
2021-11-26T16:10:09.516+08:00 INFO cluster/cluster.go:413 client is ready
2021-11-26T16:10:09.608+08:00 INFO cluster/cluster.go:692 server is ready
2021-11-26T16:10:09.649+08:00 INFO cluster/cluster.go:546 lease is ready (grant new one: b6a7d5b4b68ff07)
2021-11-26T16:10:09.649+08:00 INFO cluster/cluster.go:219 cluster is ready
2021-11-26T16:10:09.669+08:00 INFO supervisor/supervisor.go:137 create TrafficController
2021-11-26T16:10:09.67+08:00 INFO supervisor/supervisor.go:137 create RawConfigTrafficController
2021-11-26T16:10:09.67+08:00 INFO supervisor/supervisor.go:137 create ServiceRegistry
2021-11-26T16:10:09.671+08:00 INFO supervisor/supervisor.go:137 create StatusSyncController
2021-11-26T16:10:09.671+08:00 INFO cluster/cluster.go:586 session is ready
2021-11-26T16:10:09.671+08:00 INFO api/api.go:73 register api group admin
2021-11-26T16:10:09.671+08:00 INFO api/server.go:78 api server running in localhost:2381
2021-11-26T16:10:14.673+08:00 INFO cluster/member.go:223 self ID changed from 0 to 689e371e88f78b6a
2021-11-26T16:10:14.674+08:00 INFO cluster/member.go:157 store clusterMembers: eg-default-name(689e371e88f78b6a)=http:https://localhost:2380
2021-11-26T16:10:14.674+08:00 INFO cluster/member.go:158 store knownMembers : eg-default-name(689e371e88f78b6a)=http:https://localhost:2380
2022-07-04T13:47:36.579+08:00 INFO cluster/config.go:106 etcd config: advertise-client-urls: [{Scheme:http Opaque: User: Host:localhost:2379 Path: RawPath: ForceQuery:false RawQuery: Fragment: RawFragment:}] advertise-peer-urls: [{Scheme:http Opaque: User: Host:localhost:2380 Path: RawPath: ForceQuery:false RawQuery: Fragment: RawFragment:}] init-cluster: eg-default-name=http:https://localhost:2380 cluster-state: new force-new-cluster: false
2022-07-04T13:47:37.516+08:00 INFO cluster/cluster.go:332 client connect with endpoints: [http:https://localhost:2380]
2022-07-04T13:47:37.521+08:00 INFO cluster/cluster.go:346 client is ready
2022-07-04T13:47:37.529+08:00 INFO cluster/cluster.go:638 server is ready
2022-07-04T13:47:37.534+08:00 INFO cluster/cluster.go:498 lease is ready (grant new one: b6a81c7bffb1a07)
2022-07-04T13:47:37.534+08:00 INFO cluster/cluster.go:218 cluster is ready
2022-07-04T13:47:37.541+08:00 INFO supervisor/supervisor.go:137 create TrafficController
2022-07-04T13:47:37.542+08:00 INFO supervisor/supervisor.go:137 create RawConfigTrafficController
2022-07-04T13:47:37.544+08:00 INFO supervisor/supervisor.go:137 create ServiceRegistry
2022-07-04T13:47:37.544+08:00 INFO supervisor/supervisor.go:137 create StatusSyncController
2022-07-04T13:47:37.544+08:00 INFO statussynccontroller/statussynccontroller.go:139 StatusUpdateMaxBatchSize is 20
2022-07-04T13:47:37.544+08:00 INFO cluster/cluster.go:538 session is ready
2022-07-04T13:47:37.545+08:00 INFO api/api.go:73 register api group admin
2022-07-04T13:47:37.545+08:00 INFO api/server.go:86 api server running in localhost:2381
```

The default target of Makefile is to compile two binary into the directory `bin/`. `bin/easegress-server` is the server-side binary, `bin/egctl` is the client-side binary. We could add it to the `$PATH` for simplifying the following commands.
The default target of Makefile is to compile two binary into the `bin`
directory. `bin/easegress-server` is the server-side binary, `bin/egctl` is the
client-side binary. We could add it to the `$PATH` to simplify the following
commands.

We could run `easegress-server` without specifying any arguments, which launch itself by opening default ports 2379, 2380, 2381. Of course, we can change them in the config file or command arguments that are explained well in `easegress-server --help`.
We could run `easegress-server` without specifying any arguments, which launch
itself by opening default ports 2379, 2380, and 2381. We can change them in the
configuration file or command-line arguments that are explained well in
`easegress-server --help`.

```bash
$ egctl member list | grep "cluster-role"
Expand All @@ -195,11 +207,13 @@ $ egctl member list | grep "id"
id: 689e371e88f78b6a
```

After launching successfully, we could check the status of the one-node cluster. It shows the static options and dynamic status of heartbeat and etcd.
After launching successfully, we could check the status of the one-node
cluster. It shows the static options and dynamic status of heartbeat and etcd.

### Create an HTTPServer and Pipeline

Now let's create an HTTPServer listening on port 10080 to handle the HTTP traffic.
Now let's create an HTTPServer listening on port 10080 to handle the HTTP
traffic.

```bash
$ echo '
Expand All @@ -214,7 +228,9 @@ rules:
backend: pipeline-demo' | egctl object create
```

The rules of routers above mean that it will lead the traffic with the prefix `/pipeline` to the pipeline `pipeline-demo`, which will be created below. If we `curl` it before created, it will return 503.
The rules above mean it will forward the traffic with the prefix `/pipeline` to
the `pipeline-demo` pipeline because the pipeline hasn't been created yet,
we will get 503 if we `curl` it now. Next, let's create the pipeline.

```bash
$ echo '
Expand All @@ -234,17 +250,19 @@ filters:
policy: roundRobin' | egctl object create
```

The pipeline means it will do proxy for 3 backend endpoints in load balance policy `roundRobin`.
The pipeline means it will forward traffic to 3 backend endpoints, using the
`roundRobin` load balance policy.

### Test

Now you can use some HTTP clients such as `curl` to test the feature:
Now you can use an HTTP clients, such as `curl`, to test the feature:

```bash
curl -v http:https://127.0.0.1:10080/pipeline
```

If you are not set up some applications to handle the 9095, 9096, and 9097 in the localhost, it will return 503 too. We prepare a simple service to let us test handily, the example shows:
If you haven't set up backend services on ports 9095, 9096, and 9097 of the
localhost, it returns 503 too. We provide a simple service for this:

```bash
$ go run example/backend-service/mirror/mirror.go & # Running in background
Expand All @@ -257,61 +275,134 @@ Header: map[Accept:[*/*] Accept-Encoding:[gzip] Content-Type:[application/x-www-
Body : Hello, Easegress
```
### More Filters
### Add Another Pipeline
Now we want to add more features to the pipeline, then we could add kinds of filters to the pipeline. For example, we want validation and request adaptation for the `pipeline-demo`.
Now let's add another pipeline, it will get the address of an RSS feed from the
request, read the RSS feed, build the article list into a Slack message, and
then send it to Slack. But before creating the pipeline, please follow [this
document](https://api.slack.com/messaging/webhooks) to create your own Slack
webhook URL and replace the one in the below command with it.
<p align="center">
<img src="./doc/imgs/pipeline-demo.png" width=240>
<img src="./doc/imgs/rss-pipeline.png" width=480>
</p>
```bash
$ cat pipeline-demo.yaml
name: pipeline-demo
$ echo '
name: rss-pipeline
kind: Pipeline
flow:
- filter: validator
jumpIf: { invalid: END }
- filter: requestAdaptor
- filter: proxy
- filter: validator
- filter: buildRssRequest
namespace: rss
- filter: sendRssRequest
namespace: rss
- filter: decompressResponse
namespace: rss
- filter: buildSlackRequest
namespace: slack
- filter: sendSlackRequest
namespace: slack
- filter: buildResponse
filters:
- name: validator
kind: Validator
headers:
Content-Type:
values:
- application/json
- name: requestAdaptor
kind: RequestAdaptor
header:
set:
X-Adapt-Key: goodplan
- name: proxy
kind: Proxy
pools:
- servers:
- url: http:https://127.0.0.1:9095
- url: http:https://127.0.0.1:9096
- url: http:https://127.0.0.1:9097
loadBalance:
policy: roundRobin
- name: validator
kind: Validator
headers:
"X-Rss-Url":
regexp: ^https?:https://.+$
- name: buildRssRequest
kind: RequestBuilder
template: |
url: /developers/feed2json/convert?url={{index (index .requests.DEFAULT.Header "X-Rss-Url") 0 | urlquery}}
- name: sendRssRequest
kind: Proxy
pools:
- loadBalance:
policy: roundRobin
servers:
- url: https://www.toptal.com
compression:
minLength: 4096
- name: buildSlackRequest
kind: RequestBuilder
template: |
method: POST
url: /services/T0XXXXXXXXX/B0YYYYYYY/ZZZZZZZZZZZZZZZZZZZZ # This the Slack webhook address, please change it to your own.
body: |
{
"text": "Recent posts - {{.responses.rss.JSONBody.title}}",
"blocks": [{
"type": "section",
"text": {
"type": "plain_text",
"text": "Recent posts - {{.responses.rss.JSONBody.title}}"
}
}, {
"type": "section",
"text": {
"type": "mrkdwn",
"text": "{{range $index, $item := .responses.rss.JSONBody.items}}• <{{$item.url}}|{{$item.title}}>\n{{end}}"
}}]
}
- name: sendSlackRequest
kind: Proxy
pools:
- loadBalance:
policy: roundRobin
servers:
- url: https://hooks.slack.com
compression:
minLength: 4096
- name: decompressResponse
kind: ResponseAdaptor
decompress: gzip
- name: buildResponse
kind: ResponseBuilder
template: |
statusCode: 200
body: RSS feed has been sent to Slack successfully.' | egctl object create
```

### Update the HTTPServer

Now let's update the HTTPServer to forward the traffic with prefix `/rss` to
the new pipeline.
$ egctl object update -f pipeline-demo.yaml
```bash
$ echo '
kind: HTTPServer
name: server-demo
port: 10080
keepAlive: true
https: false
rules:
- paths:
- pathPrefix: /rss # +
backend: rss-pipeline # +
- pathPrefix: /pipeline
backend: pipeline-demo' | egctl object update
```
After updating the pipeline, the original `curl -v http:https://127.0.0.1:10080/pipeline` will get 400 because of the validating. So we changed it to satisfy the limitation:
### Test the RSS Pipeline
Execute the below command, your slack will receive the article list of the RSS
feed.
```bash
$ curl http:https://127.0.0.1:10080/pipeline -H 'Content-Type: application/json' -d '{"message": "Hello, Easegress"}'
Your Request
===============
Method: POST
URL : /pipeline
Header: map[Accept:[*/*] Accept-Encoding:[gzip] Content-Type:[application/json] User-Agent:[curl/7.64.1] X-Adapt-Key:[goodplan]]
Body : {"message": "Hello, Easegress"}
$ curl -H X-Rss-Url:https://hnrss.org/newest?count=5 http:https://127.0.0.1:8080/rss
```
We can also see Easegress send one more header `X-Adapt-Key: goodplan` to the mirror service.
Please note the maximum message size Slack allowed is about 3K, so you will
need to limit the number of articles returned by the RSS feed of some
sites(e.g. Hack News).
## Documentation
Expand Down
Loading

0 comments on commit 2294c49

Please sign in to comment.