garage/doc/book/src/cookbook/gateways.md

# Gateways

Gateways allow you to expose Garage endpoints (S3 API and websites) without storing data on the node.

## Benefits

You can configure Garage as a gateway on all nodes that will consume your S3 API, it will provide you the following benefits:

  - **It removes 1 or 2 network RTT** Instead of (querying your reverse proxy then) querying a random node of the cluster that will forward your request to the nodes effectively storing the data, your local gateway will directly knows which node to query. 

  - **It ease server management** Instead of tracking in your reverse proxy and DNS what are the current Garage nodes, your gateway being part of the cluster keeps this information for you. In your software, you will always specify `http://localhost:3900`.

  - **It simplifies security** Instead of having to maintain and renew a TLS certificate, you leverage the Secret Handshake protocol we use for our cluster. The S3 API protocol will be in plain text but limited to your local machine.

## Limitations

Currently it will not work with minio client. Follow issue [#64](https://git.deuxfleurs.fr/Deuxfleurs/garage/issues/64) for more information.

## Spawn a Gateway

The instructions are similar to a regular node, the only option that is different is while configuring the node, you must set the `--gateway` parameter:

```bash
garage layout assign --gateway --tag gw1 <node_id>
garage layout show    # review the changes you are making
garage layout apply   # once satisfied, apply the changes
```

Then use `http://localhost:3900` when a S3 endpoint is required:

```bash
aws --endpoint-url http://127.0.0.1:3900 s3 ls
```

If a newly added gateway node seems to not be working, do a full table resync to ensure that bucket and key list are correctly propagated:

```bash
garage repair -a --yes tables
```
Add documentation about Gateways 2021-11-04 14:25:20 +00:00			`# Gateways`

			`Gateways allow you to expose Garage endpoints (S3 API and websites) without storing data on the node.`

			`## Benefits`

			`You can configure Garage as a gateway on all nodes that will consume your S3 API, it will provide you the following benefits:`

			`- It removes 1 or 2 network RTT Instead of (querying your reverse proxy then) querying a random node of the cluster that will forward your request to the nodes effectively storing the data, your local gateway will directly knows which node to query.`

			- It ease server management Instead of tracking in your reverse proxy and DNS what are the current Garage nodes, your gateway being part of the cluster keeps this information for you. In your software, you will always specify `http://localhost:3900`.

			`- It simplifies security Instead of having to maintain and renew a TLS certificate, you leverage the Secret Handshake protocol we use for our cluster. The S3 API protocol will be in plain text but limited to your local machine.`

			`## Limitations`

			`Currently it will not work with minio client. Follow issue [#64](https://git.deuxfleurs.fr/Deuxfleurs/garage/issues/64) for more information.`

			`## Spawn a Gateway`

			The instructions are similar to a regular node, the only option that is different is while configuring the node, you must set the `--gateway` parameter:

			```bash
Improve how node roles are assigned in Garage - change the terminology: the network configuration becomes the role table, the configuration of a nodes becomes a node's role - the modification of the role table takes place in two steps: first, changes are staged in a CRDT data structure. Then, once the user is happy with the changes, they can commit them all at once (or revert them). - update documentation - fix tests - implement smarter partition assignation algorithm This patch breaks the format of the network configuration: when migrating, the cluster will be in a state where no roles are assigned. All roles must be re-assigned and commited at once. This migration should not pose an issue. 2021-11-09 11:24:04 +00:00			`garage layout assign --gateway --tag gw1 <node_id>`
			`garage layout show # review the changes you are making`
			`garage layout apply # once satisfied, apply the changes`
Add documentation about Gateways 2021-11-04 14:25:20 +00:00			```

			Then use `http://localhost:3900` when a S3 endpoint is required:

			```bash
			`aws --endpoint-url http://127.0.0.1:3900 s3 ls`
			```
Improve how node roles are assigned in Garage - change the terminology: the network configuration becomes the role table, the configuration of a nodes becomes a node's role - the modification of the role table takes place in two steps: first, changes are staged in a CRDT data structure. Then, once the user is happy with the changes, they can commit them all at once (or revert them). - update documentation - fix tests - implement smarter partition assignation algorithm This patch breaks the format of the network configuration: when migrating, the cluster will be in a state where no roles are assigned. All roles must be re-assigned and commited at once. This migration should not pose an issue. 2021-11-09 11:24:04 +00:00
			`If a newly added gateway node seems to not be working, do a full table resync to ensure that bucket and key list are correctly propagated:`

			```bash
			`garage repair -a --yes tables`
			```