aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--doc/book/cookbook/reverse-proxy.md3
-rw-r--r--doc/book/reference-manual/admin-api.md90
-rw-r--r--src/api/admin/api_server.rs47
-rw-r--r--src/api/admin/router.rs6
-rw-r--r--src/garage/tests/s3/website.rs47
5 files changed, 157 insertions, 36 deletions
diff --git a/doc/book/cookbook/reverse-proxy.md b/doc/book/cookbook/reverse-proxy.md
index bacac2ef..b715193e 100644
--- a/doc/book/cookbook/reverse-proxy.md
+++ b/doc/book/cookbook/reverse-proxy.md
@@ -469,3 +469,6 @@ https:// {
reverse_proxy localhost:3902 192.168.1.2:3902 example.tld:3902
}
```
+
+More information on how this endpoint is implemented in Garage is available
+in the [Admin API Reference](@/documentation/reference-manual/admin-api.md) page.
diff --git a/doc/book/reference-manual/admin-api.md b/doc/book/reference-manual/admin-api.md
index 363bc886..6932ac60 100644
--- a/doc/book/reference-manual/admin-api.md
+++ b/doc/book/reference-manual/admin-api.md
@@ -39,11 +39,95 @@ Authorization: Bearer <token>
## Administration API endpoints
-### Metrics-related endpoints
-
-#### Metrics `GET /metrics`
+### Metrics `GET /metrics`
Returns internal Garage metrics in Prometheus format.
+The metrics are directly documented when returned by the API.
+
+**Example:**
+
+```
+$ curl -i http://localhost:3903/metrics
+HTTP/1.1 200 OK
+content-type: text/plain; version=0.0.4
+content-length: 12145
+date: Tue, 08 Aug 2023 07:25:05 GMT
+
+# HELP api_admin_error_counter Number of API calls to the various Admin API endpoints that resulted in errors
+# TYPE api_admin_error_counter counter
+api_admin_error_counter{api_endpoint="CheckWebsiteEnabled",status_code="400"} 1
+api_admin_error_counter{api_endpoint="CheckWebsiteEnabled",status_code="404"} 3
+# HELP api_admin_request_counter Number of API calls to the various Admin API endpoints
+# TYPE api_admin_request_counter counter
+api_admin_request_counter{api_endpoint="CheckWebsiteEnabled"} 7
+api_admin_request_counter{api_endpoint="Health"} 3
+# HELP api_admin_request_duration Duration of API calls to the various Admin API endpoints
+...
+```
+
+### Health `GET /health`
+
+Returns `200 OK` if enough nodes are up to have a quorum (ie. serve requests),
+otherwise returns `503 Service Unavailable`.
+
+**Example:**
+
+```
+$ curl -i http://localhost:3903/health
+HTTP/1.1 200 OK
+content-type: text/plain
+content-length: 102
+date: Tue, 08 Aug 2023 07:22:38 GMT
+
+Garage is fully operational
+Consult the full health check API endpoint at /v0/health for more details
+```
+
+### On-demand TLS `GET /check`
+
+To prevent abuses for on-demand TLS, Caddy developpers have specified an endpoint that can be queried by the reverse proxy
+to know if a given domain is allowed to get a certificate. Garage implements this endpoints to tell if a given domain is handled by Garage or is garbage.
+
+Garage responds with the following logic:
+ - If the domain matches the pattern `<bucket-name>.<s3_api.root_domain>`, returns 200 OK
+ - If the domain matches the pattern `<bucket-name>.<s3_web.root_domain>` and website is configured for `<bucket>`, returns 200 OK
+ - If the domain matches the pattern `<bucket-name>` and website is configured for `<bucket>`, returns 200 OK
+ - Otherwise, returns 404 Not Found, 400 Bad Request or 5xx requests.
+
+*Note 1: because in the path-style URL mode, there is only one domain that is not known by Garage, hence it is not supported by this API endpoint.
+You must manually declare the domain in your reverse-proxy. Idem for K2V.*
+
+*Note 2: buckets in a user's namespace are not supported yet by this endpoint. This is a limitation of this endpoint currently.*
+
+**Example:** Suppose a Garage instance configured with `s3_api.root_domain = .s3.garage.localhost` and `s3_web.root_domain = .web.garage.localhost`.
+
+With a private `media` bucket (name in the global namespace, website is disabled), the endpoint will feature the following behavior:
+
+```
+$ curl -so /dev/null -w "%{http_code}" http://localhost:3903/check?domain=media.s3.garage.localhost
+200
+$ curl -so /dev/null -w "%{http_code}" http://localhost:3903/check?domain=media
+400
+$ curl -so /dev/null -w "%{http_code}" http://localhost:3903/check?domain=media.web.garage.localhost
+400
+```
+
+With a public `example.com` bucket (name in the global namespace, website is activated), the endpoint will feature the following behavior:
+
+```
+$ curl -so /dev/null -w "%{http_code}" http://localhost:3903/check?domain=example.com.s3.garage.localhost
+200
+$ curl -so /dev/null -w "%{http_code}" http://localhost:3903/check?domain=example.com
+200
+$ curl -so /dev/null -w "%{http_code}" http://localhost:3903/check?domain=example.com.web.garage.localhost
+200
+```
+
+
+**References:**
+ - [Using On-Demand TLS](https://caddyserver.com/docs/automatic-https#using-on-demand-tls)
+ - [Add option for a backend check to approve use of on-demand TLS](https://github.com/caddyserver/caddy/pull/1939)
+ - [Serving tens of thousands of domains over HTTPS with Caddy](https://caddy.community/t/serving-tens-of-thousands-of-domains-over-https-with-caddy/11179)
### Cluster operations
diff --git a/src/api/admin/api_server.rs b/src/api/admin/api_server.rs
index b0dfdfb7..8bf467dc 100644
--- a/src/api/admin/api_server.rs
+++ b/src/api/admin/api_server.rs
@@ -26,6 +26,7 @@ use crate::admin::cluster::*;
use crate::admin::error::*;
use crate::admin::key::*;
use crate::admin::router::{Authorization, Endpoint};
+use crate::helpers::host_to_bucket;
pub struct AdminApiServer {
garage: Arc<Garage>,
@@ -78,10 +79,7 @@ impl AdminApiServer {
.body(Body::empty())?)
}
- async fn handle_check_website_enabled(
- &self,
- req: Request<Body>,
- ) -> Result<Response<Body>, Error> {
+ async fn handle_check_domain(&self, req: Request<Body>) -> Result<Response<Body>, Error> {
let query_params: HashMap<String, String> = req
.uri()
.query()
@@ -102,12 +100,43 @@ impl AdminApiServer {
.get("domain")
.ok_or_internal_error("Could not parse domain query string")?;
+ // Resolve bucket from domain name, inferring if the website must be activated for the
+ // domain to be valid.
+ let (bucket_name, must_check_website) = if let Some(bname) = self
+ .garage
+ .config
+ .s3_api
+ .root_domain
+ .as_ref()
+ .and_then(|rd| host_to_bucket(domain, rd))
+ {
+ (bname.to_string(), false)
+ } else if let Some(bname) = self
+ .garage
+ .config
+ .s3_web
+ .as_ref()
+ .and_then(|sw| host_to_bucket(domain, sw.root_domain.as_str()))
+ {
+ (bname.to_string(), true)
+ } else {
+ (domain.to_string(), true)
+ };
+
let bucket_id = self
.garage
.bucket_helper()
- .resolve_global_bucket_name(domain)
+ .resolve_global_bucket_name(&bucket_name)
.await?
- .ok_or(HelperError::NoSuchBucket(domain.to_string()))?;
+ .ok_or(HelperError::NoSuchBucket(bucket_name.to_string()))?;
+
+ if !must_check_website {
+ return Ok(Response::builder()
+ .status(StatusCode::OK)
+ .body(Body::from(format!(
+ "Domain '{domain}' is managed by Garage"
+ )))?);
+ }
let bucket = self
.garage
@@ -123,11 +152,11 @@ impl AdminApiServer {
Ok(Response::builder()
.status(StatusCode::OK)
.body(Body::from(format!(
- "Bucket '{domain}' is authorized for website hosting"
+ "Domain '{domain}' is managed by Garage"
)))?)
}
None => Err(Error::bad_request(format!(
- "Bucket '{domain}' is not authorized for website hosting"
+ "Domain '{domain}' is not managed by Garage"
))),
}
}
@@ -229,7 +258,7 @@ impl ApiHandler for AdminApiServer {
match endpoint {
Endpoint::Options => self.handle_options(&req),
- Endpoint::CheckWebsiteEnabled => self.handle_check_website_enabled(req).await,
+ Endpoint::CheckDomain => self.handle_check_domain(req).await,
Endpoint::Health => self.handle_health(),
Endpoint::Metrics => self.handle_metrics(),
Endpoint::GetClusterStatus => handle_get_cluster_status(&self.garage).await,
diff --git a/src/api/admin/router.rs b/src/api/admin/router.rs
index 0dcb1546..0225f18b 100644
--- a/src/api/admin/router.rs
+++ b/src/api/admin/router.rs
@@ -17,7 +17,7 @@ router_match! {@func
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Endpoint {
Options,
- CheckWebsiteEnabled,
+ CheckDomain,
Health,
Metrics,
GetClusterStatus,
@@ -92,7 +92,7 @@ impl Endpoint {
let res = router_match!(@gen_path_parser (req.method(), path, query) [
OPTIONS _ => Options,
- GET "/check" => CheckWebsiteEnabled,
+ GET "/check" => CheckDomain,
GET "/health" => Health,
GET "/metrics" => Metrics,
GET "/v0/status" => GetClusterStatus,
@@ -138,7 +138,7 @@ impl Endpoint {
pub fn authorization_type(&self) -> Authorization {
match self {
Self::Health => Authorization::None,
- Self::CheckWebsiteEnabled => Authorization::None,
+ Self::CheckDomain => Authorization::None,
Self::Metrics => Authorization::MetricsToken,
_ => Authorization::AdminToken,
}
diff --git a/src/garage/tests/s3/website.rs b/src/garage/tests/s3/website.rs
index ab9b12b9..7c2b0deb 100644
--- a/src/garage/tests/s3/website.rs
+++ b/src/garage/tests/s3/website.rs
@@ -72,7 +72,7 @@ async fn test_website() {
res_body,
json!({
"code": "InvalidRequest",
- "message": "Bad request: Bucket 'my-website' is not authorized for website hosting",
+ "message": "Bad request: Domain 'my-website' is not managed by Garage",
"region": "garage-integ-test",
"path": "/check",
})
@@ -91,24 +91,29 @@ async fn test_website() {
BODY.as_ref()
);
- let admin_req = || {
- Request::builder()
- .method("GET")
- .uri(format!(
- "http://127.0.0.1:{0}/check?domain={1}",
- ctx.garage.admin_port,
- BCKT_NAME.to_string()
- ))
- .body(Body::empty())
- .unwrap()
- };
-
- let mut admin_resp = client.request(admin_req()).await.unwrap();
- assert_eq!(admin_resp.status(), StatusCode::OK);
- assert_eq!(
- to_bytes(admin_resp.body_mut()).await.unwrap().as_ref(),
- format!("Bucket '{BCKT_NAME}' is authorized for website hosting").as_bytes()
- );
+ for bname in [
+ BCKT_NAME.to_string(),
+ format!("{BCKT_NAME}.web.garage"),
+ format!("{BCKT_NAME}.s3.garage"),
+ ] {
+ let admin_req = || {
+ Request::builder()
+ .method("GET")
+ .uri(format!(
+ "http://127.0.0.1:{0}/check?domain={1}",
+ ctx.garage.admin_port, bname
+ ))
+ .body(Body::empty())
+ .unwrap()
+ };
+
+ let mut admin_resp = client.request(admin_req()).await.unwrap();
+ assert_eq!(admin_resp.status(), StatusCode::OK);
+ assert_eq!(
+ to_bytes(admin_resp.body_mut()).await.unwrap().as_ref(),
+ format!("Domain '{bname}' is managed by Garage").as_bytes()
+ );
+ }
ctx.garage
.command()
@@ -142,7 +147,7 @@ async fn test_website() {
res_body,
json!({
"code": "InvalidRequest",
- "message": "Bad request: Bucket 'my-website' is not authorized for website hosting",
+ "message": "Bad request: Domain 'my-website' is not managed by Garage",
"region": "garage-integ-test",
"path": "/check",
})
@@ -397,7 +402,7 @@ async fn test_website_s3_api() {
}
#[tokio::test]
-async fn test_website_check_website_enabled() {
+async fn test_website_check_domain() {
let ctx = common::context();
let client = Client::new();
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-06 01:48:19 +0000