From bd6485565e78c0bbb9ee830c4e5b114c6248dc97 Mon Sep 17 00:00:00 2001 From: Roberto Hidalgo Date: Mon, 8 May 2023 19:29:47 -0600 Subject: allow additional ServiceMeta, docs --- doc/book/reference-manual/configuration.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) (limited to 'doc/book/reference-manual') diff --git a/doc/book/reference-manual/configuration.md b/doc/book/reference-manual/configuration.md index 38062bab..348a352a 100644 --- a/doc/book/reference-manual/configuration.md +++ b/doc/book/reference-manual/configuration.md @@ -42,6 +42,17 @@ client_cert = "/etc/consul/consul-client.crt" client_key = "/etc/consul/consul-key.crt" tls_skip_verify = false +[consul_service_discovery] +consul_http_addr = "https://127.0.0.1:8501" +consul_http_token = "abcdef-01234-56789" +service_name = "garage" +ca_cert = "/etc/consul/consul-ca.crt" +tls_skip_verify = false +# tags to add to the published service +tags = [ "dns-enabled" ] +# additional service meta to send along registration +meta = { dns-acl = "allow trusted" } + [kubernetes_discovery] namespace = "garage" service_name = "garage-daemon" @@ -201,7 +212,7 @@ Garage supports the following replication modes: that should probably never be used. Note that in modes `2` and `3`, -if at least the same number of zones are available, an arbitrary number of failures in +if at least the same number of zones are available, an arbitrary number of failures in any given zone is tolerated as copies of data will be spread over several zones. **Make sure `replication_mode` is the same in the configuration files of all nodes. @@ -245,7 +256,7 @@ Values between `1` (faster compression) and `19` (smaller file) are standard com levels for zstd. From `20` to `22`, compression levels are referred as "ultra" and must be used with extra care as it will use lot of memory. A value of `0` will let zstd choose a default value (currently `3`). Finally, zstd has also compression designed to be faster -than default compression levels, they range from `-1` (smaller file) to `-99` (faster +than default compression levels, they range from `-1` (smaller file) to `-99` (faster compression). If you do not specify a `compression_level` entry, Garage will set it to `1` for you. With -- cgit v1.2.3 From fd7dbea5b86ed8757e76e1114e2154538c5a3c16 Mon Sep 17 00:00:00 2001 From: Roberto Hidalgo Date: Wed, 10 May 2023 13:20:39 -0600 Subject: follow feedback, fold into existing feature --- doc/book/reference-manual/configuration.md | 45 +++++++++++++++++++++++------- 1 file changed, 35 insertions(+), 10 deletions(-) (limited to 'doc/book/reference-manual') diff --git a/doc/book/reference-manual/configuration.md b/doc/book/reference-manual/configuration.md index 348a352a..819a5b88 100644 --- a/doc/book/reference-manual/configuration.md +++ b/doc/book/reference-manual/configuration.md @@ -35,24 +35,19 @@ bootstrap_peers = [ [consul_discovery] +mode = "node" consul_http_addr = "http://127.0.0.1:8500" service_name = "garage-daemon" ca_cert = "/etc/consul/consul-ca.crt" client_cert = "/etc/consul/consul-client.crt" client_key = "/etc/consul/consul-key.crt" +# for `service` mode, unset client_cert and client_key, and optionally enable `consul_http_token` +# consul_http_token = "abcdef-01234-56789" tls_skip_verify = false - -[consul_service_discovery] -consul_http_addr = "https://127.0.0.1:8501" -consul_http_token = "abcdef-01234-56789" -service_name = "garage" -ca_cert = "/etc/consul/consul-ca.crt" -tls_skip_verify = false -# tags to add to the published service tags = [ "dns-enabled" ] -# additional service meta to send along registration meta = { dns-acl = "allow trusted" } + [kubernetes_discovery] namespace = "garage" service_name = "garage-daemon" @@ -323,6 +318,12 @@ Garage supports discovering other nodes of the cluster using Consul. For this to work correctly, nodes need to know their IP address by which they can be reached by other nodes of the cluster, which should be set in `rpc_public_addr`. +### `mode` + +Two modes of service discovery are supported: `node` and `service`. `node`, the default will register a service using +the `/v1/catalog` endpoints and mTLS (if `client_cert` and `client_key` are provided). `service` mode uses the +`v1/agent` endpoints instead, where an optional `consul_http_token` may be provided. + ### `consul_http_addr` and `service_name` The `consul_http_addr` parameter should be set to the full HTTP(S) address of the Consul server. @@ -334,7 +335,8 @@ RPC ports are announced. ### `client_cert`, `client_key` -TLS client certificate and client key to use when communicating with Consul over TLS. Both are mandatory when doing so. +`node` mode only. TLS client certificate and client key to use when communicating with Consul over TLS. +Both are mandatory when doing so. ### `ca_cert` @@ -345,6 +347,29 @@ TLS CA certificate to use when communicating with Consul over TLS. Skip server hostname verification in TLS handshake. `ca_cert` is ignored when this is set. +### `consul_http_token` + +`service` mode only. Uses the provided token for communication with Consul. The policy assigned to this token +should at least have these rules: + +```hcl +// the `service_name` specified above +service "garage" { + policy = "write" +} + +service_prefix "" { + policy = "read" +} + +node_prefix "" { + policy = "read" +} +``` + +### `tags` and `meta` + +Additional list of tags and map of service meta to add during service registration. ## The `[kubernetes_discovery]` section -- cgit v1.2.3 From 6b69404f1a53b927b4ce3cabdbb41f58e832a963 Mon Sep 17 00:00:00 2001 From: Roberto Hidalgo Date: Wed, 10 May 2023 20:11:14 -0600 Subject: rename mode to consul_http_api --- doc/book/reference-manual/configuration.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) (limited to 'doc/book/reference-manual') diff --git a/doc/book/reference-manual/configuration.md b/doc/book/reference-manual/configuration.md index 819a5b88..50921824 100644 --- a/doc/book/reference-manual/configuration.md +++ b/doc/book/reference-manual/configuration.md @@ -318,16 +318,16 @@ Garage supports discovering other nodes of the cluster using Consul. For this to work correctly, nodes need to know their IP address by which they can be reached by other nodes of the cluster, which should be set in `rpc_public_addr`. -### `mode` - -Two modes of service discovery are supported: `node` and `service`. `node`, the default will register a service using -the `/v1/catalog` endpoints and mTLS (if `client_cert` and `client_key` are provided). `service` mode uses the -`v1/agent` endpoints instead, where an optional `consul_http_token` may be provided. - ### `consul_http_addr` and `service_name` The `consul_http_addr` parameter should be set to the full HTTP(S) address of the Consul server. +### `consul_http_api` + +Two APIs for service registration are supported: `catalog` and `agent`. `catalog`, the default, will register a service using +the `/v1/catalog` endpoints and mTLS (if `client_cert` and `client_key` are provided). The `agent` API uses the +`v1/agent` endpoints instead, where an optional `consul_http_token` may be provided. + ### `service_name` `service_name` should be set to the service name under which Garage's @@ -335,8 +335,8 @@ RPC ports are announced. ### `client_cert`, `client_key` -`node` mode only. TLS client certificate and client key to use when communicating with Consul over TLS. -Both are mandatory when doing so. +TLS client certificate and client key to use when communicating with Consul over TLS. Both are mandatory when doing so. +Only available when `consul_http_api = "catalog"`. ### `ca_cert` @@ -349,8 +349,8 @@ Skip server hostname verification in TLS handshake. ### `consul_http_token` -`service` mode only. Uses the provided token for communication with Consul. The policy assigned to this token -should at least have these rules: +Uses the provided token for communication with Consul. Only available when `consul_http_api = "agent"`. +The policy assigned to this token should at least have these rules: ```hcl // the `service_name` specified above -- cgit v1.2.3 From b7705041268e49f2a5ba9a719372048f85c3de83 Mon Sep 17 00:00:00 2001 From: Roberto Hidalgo Date: Mon, 15 May 2023 16:15:56 -0600 Subject: simplify code according to feedback --- doc/book/reference-manual/configuration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc/book/reference-manual') diff --git a/doc/book/reference-manual/configuration.md b/doc/book/reference-manual/configuration.md index 50921824..2fdfce8f 100644 --- a/doc/book/reference-manual/configuration.md +++ b/doc/book/reference-manual/configuration.md @@ -35,14 +35,14 @@ bootstrap_peers = [ [consul_discovery] -mode = "node" +api = "catalog" consul_http_addr = "http://127.0.0.1:8500" service_name = "garage-daemon" ca_cert = "/etc/consul/consul-ca.crt" client_cert = "/etc/consul/consul-client.crt" client_key = "/etc/consul/consul-key.crt" -# for `service` mode, unset client_cert and client_key, and optionally enable `consul_http_token` -# consul_http_token = "abcdef-01234-56789" +# for `catalog` API mode, unset client_cert and client_key, and optionally enable `token` +# token = "abcdef-01234-56789" tls_skip_verify = false tags = [ "dns-enabled" ] meta = { dns-acl = "allow trusted" } -- cgit v1.2.3 From 2d46d24d06849584e751ffcf6842b4d3016b6f77 Mon Sep 17 00:00:00 2001 From: Roberto Hidalgo Date: Mon, 15 May 2023 20:02:28 -0600 Subject: update docs --- doc/book/reference-manual/configuration.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'doc/book/reference-manual') diff --git a/doc/book/reference-manual/configuration.md b/doc/book/reference-manual/configuration.md index 2fdfce8f..5322b755 100644 --- a/doc/book/reference-manual/configuration.md +++ b/doc/book/reference-manual/configuration.md @@ -322,10 +322,10 @@ reached by other nodes of the cluster, which should be set in `rpc_public_addr`. The `consul_http_addr` parameter should be set to the full HTTP(S) address of the Consul server. -### `consul_http_api` +### `api` Two APIs for service registration are supported: `catalog` and `agent`. `catalog`, the default, will register a service using -the `/v1/catalog` endpoints and mTLS (if `client_cert` and `client_key` are provided). The `agent` API uses the +the `/v1/catalog` endpoints, enabling mTLS if `client_cert` and `client_key` are provided. The `agent` API uses the `v1/agent` endpoints instead, where an optional `consul_http_token` may be provided. ### `service_name` @@ -336,7 +336,7 @@ RPC ports are announced. ### `client_cert`, `client_key` TLS client certificate and client key to use when communicating with Consul over TLS. Both are mandatory when doing so. -Only available when `consul_http_api = "catalog"`. +Only available when `api = "catalog"`. ### `ca_cert` @@ -347,9 +347,9 @@ TLS CA certificate to use when communicating with Consul over TLS. Skip server hostname verification in TLS handshake. `ca_cert` is ignored when this is set. -### `consul_http_token` +### `token` -Uses the provided token for communication with Consul. Only available when `consul_http_api = "agent"`. +Uses the provided token for communication with Consul. Only available when `api = "agent"`. The policy assigned to this token should at least have these rules: ```hcl -- cgit v1.2.3 From 32ad4538eec9e844edab7e04e03dee9d594ec8fb Mon Sep 17 00:00:00 2001 From: Roberto Hidalgo Date: Mon, 22 May 2023 08:47:06 -0600 Subject: fix references to old config names --- doc/book/reference-manual/configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/book/reference-manual') diff --git a/doc/book/reference-manual/configuration.md b/doc/book/reference-manual/configuration.md index 5322b755..20a79aa6 100644 --- a/doc/book/reference-manual/configuration.md +++ b/doc/book/reference-manual/configuration.md @@ -41,7 +41,7 @@ service_name = "garage-daemon" ca_cert = "/etc/consul/consul-ca.crt" client_cert = "/etc/consul/consul-client.crt" client_key = "/etc/consul/consul-key.crt" -# for `catalog` API mode, unset client_cert and client_key, and optionally enable `token` +# for `agent` API mode, unset client_cert and client_key, and optionally enable `token` # token = "abcdef-01234-56789" tls_skip_verify = false tags = [ "dns-enabled" ] @@ -326,7 +326,7 @@ The `consul_http_addr` parameter should be set to the full HTTP(S) address of th Two APIs for service registration are supported: `catalog` and `agent`. `catalog`, the default, will register a service using the `/v1/catalog` endpoints, enabling mTLS if `client_cert` and `client_key` are provided. The `agent` API uses the -`v1/agent` endpoints instead, where an optional `consul_http_token` may be provided. +`v1/agent` endpoints instead, where an optional `token` may be provided. ### `service_name` -- cgit v1.2.3