|
| 1 | +Installation |
| 2 | +============ |
| 3 | + |
| 4 | +Contents: |
| 5 | + |
| 6 | +- [Requirements](#requirements) |
| 7 | + * [Platform](#platform) |
| 8 | + * [Docker](#docker) |
| 9 | + * [EventHorizon](#eventhorizon) |
| 10 | +- [AWS IAM config](#aws-iam-config) |
| 11 | + * [EventHorizon](#eventhorizon-1) |
| 12 | + * [Lambda functions](#lambda-functions) |
| 13 | + * [S3 static website deployment](#s3-static-website-deployment) |
| 14 | +- [Config required pre-start](#config-required-pre-start) |
| 15 | + * [A note about Docker service discovery](#a-note-about-docker-service-discovery) |
| 16 | +- [Runtime config](#runtime-config) |
| 17 | +- [Start Edgerouter](#start-edgerouter) |
| 18 | + |
| 19 | + |
| 20 | +Requirements |
| 21 | +------------ |
| 22 | + |
| 23 | +### Platform |
| 24 | + |
| 25 | +Edgerouter requires Linux amd64. Other platforms could easily be supported but I haven't |
| 26 | +had the need so I haven't added cross compilation support yet. |
| 27 | + |
| 28 | + |
| 29 | +### Docker |
| 30 | + |
| 31 | +Usage via Docker is recommended. It'd be easy to add Systemd unit so you can run it as a |
| 32 | +bare binary, but I haven't had a need for it. |
| 33 | + |
| 34 | + |
| 35 | +### EventHorizon |
| 36 | + |
| 37 | +Edgerouter requires [EventHorizon](https://github.com/function61/eventhorizon). Edgerouter |
| 38 | +uses it for: |
| 39 | + |
| 40 | +- CertBus (**required**) |
| 41 | +- Service discovery (**optional**) |
| 42 | + |
| 43 | +You must have |
| 44 | +gone through its [Installation guide](https://github.com/function61/eventhorizon#installation). |
| 45 | + |
| 46 | + |
| 47 | +AWS IAM config |
| 48 | +-------------- |
| 49 | + |
| 50 | +You should have a dedicated user in IAM for Edgerouter's use. A good name could be `edgerouter`. |
| 51 | + |
| 52 | +### EventHorizon |
| 53 | + |
| 54 | +Your Edgerouter user needs to have permissions for EventHorizon |
| 55 | +(these are explained in EventHorizon's installation): |
| 56 | + |
| 57 | +- `EventHorizon-read` permission is enough if you have separate user (perhaps `edgerouter-manager`?) for |
| 58 | + changing service discovery configs. |
| 59 | +- Otherwise you need `EventHorizon-readwrite` permission |
| 60 | + |
| 61 | + |
| 62 | +### Lambda functions |
| 63 | + |
| 64 | +If you plan to use Edgerouter to proxy Lambda functions - let's say your functions are |
| 65 | +`FunctionA` and `FunctionB`, you need an inline policy that looks like this: |
| 66 | + |
| 67 | +```json |
| 68 | +{ |
| 69 | + "Version": "2012-10-17", |
| 70 | + "Statement": [ |
| 71 | + { |
| 72 | + "Sid": "edgeroterInvocableLambdas", |
| 73 | + "Effect": "Allow", |
| 74 | + "Action": "lambda:InvokeFunction", |
| 75 | + "Resource": [ |
| 76 | + "arn:aws:lambda:us-east-1:123456789011:function:FunctionA", |
| 77 | + "arn:aws:lambda:us-east-1:123456789011:function:FunctionB" |
| 78 | + ] |
| 79 | + } |
| 80 | + ] |
| 81 | +} |
| 82 | +``` |
| 83 | + |
| 84 | +NOTE: replace `123456789011` with your account id! |
| 85 | + |
| 86 | +(Pro-tip: you can replace `us-east-1` with `*` if you use multiple Lambda regions and you |
| 87 | +want to make it easier to write these policies) |
| 88 | + |
| 89 | + |
| 90 | +### S3 static website deployment |
| 91 | + |
| 92 | +For the user that deploys static websites to S3 (`edgerouter-manager` OR `edgerouter`), |
| 93 | +you need an inline policy like this (NOTE: replace `yourorg-staticwebsites` with your bucket name): |
| 94 | + |
| 95 | +```json |
| 96 | +{ |
| 97 | + "Version": "2012-10-17", |
| 98 | + "Statement": [ |
| 99 | + { |
| 100 | + "Sid": "deployStaticWebsites", |
| 101 | + "Effect": "Allow", |
| 102 | + "Action": [ |
| 103 | + "s3:PutObject", |
| 104 | + "s3:DeleteObject", |
| 105 | + "s3:PutObjectAcl" |
| 106 | + ], |
| 107 | + "Resource": [ |
| 108 | + "arn:aws:s3:::yourorg-staticwebsites/*" |
| 109 | + ] |
| 110 | + } |
| 111 | + ] |
| 112 | +} |
| 113 | +``` |
| 114 | + |
| 115 | + |
| 116 | +Config required pre-start |
| 117 | +------------------------- |
| 118 | + |
| 119 | +Before starting Edgerouter, you need to assemble the following ENV variables to start |
| 120 | +it with. |
| 121 | + |
| 122 | +Configuration is driven by the following ENV variables: |
| 123 | + |
| 124 | +- EventHorizon access: CertBus + service discovery of static applications |
| 125 | + * `AWS_ACCESS_KEY_ID` |
| 126 | + * `AWS_SECRET_ACCESS_KEY` |
| 127 | + * `CERTBUS_CLIENT_PRIVKEY`, base64 encoded PEM encoded ("----- BEGIN ... -----") private key |
| 128 | + * `EVENTHORIZON_TENANT`, example: prod:1 |
| 129 | +- Docker service discovery (**optional**) |
| 130 | + * `DOCKER_CLIENTCERT`, base64 encoded PEM encoded ("----- BEGIN ... -----") cert |
| 131 | + * `DOCKER_CLIENTCERT_KEY`, base64 encoded PEM encoded ("----- BEGIN ... -----") private key |
| 132 | + * `DOCKER_URL`, example: https://dockersockproxy:4431 |
| 133 | + * `NETWORK_NAME`, example: fn61 |
| 134 | + |
| 135 | +### A note about Docker service discovery |
| 136 | + |
| 137 | +If you're using Docker Swarm with multiple nodes, you probably need to run |
| 138 | +[dockersockproxy](https://github.com/function61/dockersockproxy) (or similar) with a |
| 139 | +deployment constraint to the Swarm manager node because for the Docker service discovery |
| 140 | +to see all Swarm tasks' IPs we need to query the Swarm manager node. |
| 141 | + |
| 142 | +If you're running a single node, you can probably just mount the Docker socket into |
| 143 | +Edgerouter's container and set `DOCKER_URL=unix:///var/run/docker.sock`. In this case you |
| 144 | +don't need `DOCKER_CLIENTCERT` or `DOCKER_CLIENTCERT_KEY`. |
| 145 | + |
| 146 | + |
| 147 | +Runtime config |
| 148 | +-------------- |
| 149 | + |
| 150 | +Most of the runtime config in Edgerouter is controllable by its dynamic service discovery |
| 151 | +mechanism. Those changes are updated to each Edgerouter node (if you have a cluster, this |
| 152 | +is important). Read the rest of the docs to become familiar with the mechanism. |
| 153 | + |
| 154 | + |
| 155 | +Start Edgerouter |
| 156 | +---------------- |
| 157 | + |
| 158 | +You are now ready to start. Use your favourite mechanism to start Docker containers. You |
| 159 | +can find the image name and the latest version tag from the repo's README. Just remember |
| 160 | +to pass the pre-start ENVs from this guide. |
| 161 | + |
| 162 | +Example Docker config (ran in Docker Swarm): |
| 163 | + |
| 164 | +```yaml |
| 165 | +version: "3.5" |
| 166 | +services: |
| 167 | + edgerouter: |
| 168 | + deploy: |
| 169 | + update_config: |
| 170 | + parallelism: 1 |
| 171 | + order: start-first |
| 172 | + resources: |
| 173 | + limits: |
| 174 | + memory: "100663296" |
| 175 | + environment: |
| 176 | + AWS_ACCESS_KEY_ID: ... |
| 177 | + AWS_SECRET_ACCESS_KEY: ... |
| 178 | + CERTBUS_CLIENT_PRIVKEY: ... |
| 179 | + DOCKER_CLIENTCERT: ... |
| 180 | + DOCKER_CLIENTCERT_KEY: ... |
| 181 | + DOCKER_URL: https://dockersockproxy:4431 |
| 182 | + EVENTHORIZON_TENANT: prod:1 |
| 183 | + LOGGER_SUPPRESS_TIMESTAMPS: "1" |
| 184 | + NETWORK_NAME: fn61 |
| 185 | + image: fn61/edgerouter:PUT_VERSION_TAG_HERE |
| 186 | + networks: |
| 187 | + default: null |
| 188 | + ports: |
| 189 | + - mode: ingress |
| 190 | + target: 80 |
| 191 | + published: 80 |
| 192 | + protocol: tcp |
| 193 | + - mode: ingress |
| 194 | + target: 443 |
| 195 | + published: 443 |
| 196 | + protocol: tcp |
| 197 | +networks: |
| 198 | + default: |
| 199 | + external: |
| 200 | + name: fn61 |
| 201 | +``` |
0 commit comments