Core, AWS, REST: Promote the S3 signing endpoint to the main spec#15112
Core, AWS, REST: Promote the S3 signing endpoint to the main spec#15112adutra wants to merge 17 commits intoapache:mainfrom
Conversation
ad95a85 to
f3fc095
Compare
open-api/rest-catalog-open-api.yaml
Outdated
| 5XX: | ||
| $ref: '#/components/responses/ServerErrorResponse' | ||
|
|
||
| /v1/{prefix}/namespaces/{namespace}/tables/{table}/sign/{provider}: |
There was a problem hiding this comment.
{provide} why do we need that ? a table would ideally be in one object store ? if there are multiple thats fine too, i believe we give absolute path of the uri right ?
There was a problem hiding this comment.
I added this, because if/when a catalog server eventually has remote signing available for more than one object storage provider (say, S3 and Azure), it would be good if the server could determine how exactly to sign the request. Without this path parameter, the server would need to apply some heuristics to determine the right object store provider, and hence how to sign the request.
There was a problem hiding this comment.
the server would need to apply some heuristics to determine the right object store provider
didn't get this part, we give the path we want to be signed from client to server as part of payload of this request right ? can't we extract that from there (Are you concerned with s3 / s3a / s3n semantics ?)
There was a problem hiding this comment.
It's not that easy.
As an example, a request to sign looks like the one below for S3:
PUT /warehouse/db/sales_table/data/date=2024-05/00022-44-55.parquet HTTP/1.1
Host: my-datalake.s3.us-east-1.amazonaws.com
Date: Fri, 24 May 2024 12:45:00 GMT
Content-Length: 134217728
Content-Type: application/octet-stream
A similar request to GCP would look like:
POST /upload/storage/v1/b/my-datalake-bucket/o?uploadType=media&name=warehouse/db/sales/data/file.parquet HTTP/1.1
Host: storage.googleapis.com
Date: Fri, 24 May 2024 12:45:00 GMT
Content-Length: 134217728
Content-Type: application/octet-stream
And for Azure:
PATCH /my-container/warehouse/db/sales/data/file.parquet?action=append&position=0 HTTP/1.1
Host: my-datalake.dfs.core.windows.net
x-ms-date: Fri, 24 May 2024 12:45:00 GMT
x-ms-version: 2023-11-03
Content-Length: 134217728
Content-Type: application/octet-stream
The question is: how do you know the object storage provider so that the server can pick the right signing algorithm? The only (heuristic) way is to inspect the Host header, but that's brittle. It's much simpler if the client tells the server what object storage provider to use.
There was a problem hiding this comment.
I am taking of sign request from IRC client to IRC server, i believe what you are showing is IRC server to object store sign ? am i missing something
like IRC client will do a post to /v1/{prefix}/namespaces/{namespace}/tables/{table}/sign with uri as param
https://github.com/apache/iceberg/pull/15112/changes#diff-02549ca620d020dc9ead80088cc14e311e12a69651fa8d394cd41a4308debb2eR4725
i think this would an absolute path right ? s3:////table/data/a.parquet
There was a problem hiding this comment.
OK, I'm fine with that. Let's remove the provider parameter. @singhpk234 would that work for you?
There was a problem hiding this comment.
+1 from end too to keep the provider in the body of the request rather in the URL !
There was a problem hiding this comment.
Thanks a lot for working on this, @alaturqua.
I’m leaning toward option 3 since it covers more use cases without requiring a mandatory provider in the path. The catalog implementation can still decide how to behave based on whether provider is present or whether it can reliably infer it from the input uri.
When the provider is explicitly provided, I think the catalog should honor it. Making it optional also keeps things backward compatible while leaving room for more complex scenarios, like supporting multiple storage providers.
3. Include the provider parameter in the request body
a. the client impl is responsible for generating it
b. must be optional for backwards compatibility
There was a problem hiding this comment.
OK let me implement option 3 then. Thank you all for the feedback!
There was a problem hiding this comment.
Option 3 implemented, FYI.
open-api/rest-catalog-open-api.yaml
Outdated
|
|
||
| If remote signing for a specific storage provider is enabled, clients must respect the following configurations when creating a remote signer client: | ||
| - `signer.uri`: the base URI of the remote signer endpoint. Optional; if absent, defaults to the catalog's base URI. | ||
| - `signer.endpoint`: the path of the remote signer endpoint. Required. Should be concatenated with `signer.uri` to form the complete URI. |
There was a problem hiding this comment.
It's complicated 😄
The signer client impl uses org.apache.iceberg.rest.RESTUtil#resolveEndpoint to perform the concatenation of signer.uri and signer.endpoint.
So, signer.endpoint could also be an absolute URL, in which case, signer.uri would be ignored.
I will try to come up with a better wording.
There was a problem hiding this comment.
Rephrased, lmk what you think!
| allOf: | ||
| - $ref: '#/components/schemas/Expression' | ||
|
|
||
| MultiValuedMap: |
There was a problem hiding this comment.
I believe this is S3Headers eq section in the s3 signer spec ? can we say like ObjectStoreProviderHeader ?
There was a problem hiding this comment.
I went for a more generic name because there is nothing specific to remote signing here. This component could perfectly be used for something else in the spec.
| - `s3.secret-access-key`: secret for credentials that provide access to data in S3 | ||
| - `s3.session-token`: if present, this value should be used for as the session token | ||
| - `s3.remote-signing-enabled`: if `true` remote signing should be performed as described in the `s3-signer-open-api.yaml` specification | ||
| - `s3.remote-signing-enabled`: if `true` remote signing should be performed as described in the `RemoteSignRequest` schema section of this spec document. |
There was a problem hiding this comment.
FYI I chose to keep this property specific to S3. I think that even if the signer endpoint is now generic, enablement should be performed for each specific object storage.
There was a problem hiding this comment.
you can actually do google GCS cloud access via its s3 gateway; same signing algorithm, just a few different settings to change listing version, endpoint, &c
| public String baseSignerUri() { | ||
| return properties().getOrDefault(S3_SIGNER_URI, properties().get(CatalogProperties.URI)); | ||
| return properties() | ||
| .getOrDefault(CatalogProperties.SIGNER_URI, properties().get(CatalogProperties.URI)); |
There was a problem hiding this comment.
isn't this breaking existing behavior where one could have provided the s3.signer.uri but now we don't read that property anymore and rely on signer.uri. The same for the endpoint
There was a problem hiding this comment.
I don't think so, since the new client introduced in 1.11 is resilient to older servers.
Let's break this into concrete situations:
| Server | Client | Signer config | Resulting URI | Result |
|---|---|---|---|---|
| 1.10 | 1.11 | s3.signer.uri=... s3.signer.endpoint=... | s3.signer.uri + s3.signer.endpoint | ✅ |
| 1.10 | 1.11 | s3.signer.uri=... | s3.signer.uri + default endpoint | ✅ |
| 1.10 | 1.11 | s3.signer.endpoint=... | catalog URI + s3.signer.endpoint | ✅ |
| 1.10 | 1.11 | (empty) | catalog URI + default endpoint | ✅ |
| 1.11 | 1.10 | signer.uri=... signer.endpoint=... s3.signer.uri=... s3.signer.endpoint=... | s3.signer.uri + s3.signer.endpoint | ✅ |
| 1.11 | 1.10 | signer.endpoint=... s3.signer.endpoint=... | catalog URI + s3.signer.endpoint | ✅ |
| 1.11 | 1.10 | signer.uri=... signer.endpoint=... | catalog URI + default endpoint | ❌ |
| 1.11 | 1.10 | signer.endpoint=... | catalog URI + default endpoint | ❌ |
So in summary:
- 1.11 Clients won't break older servers.
- 1.11 Servers won't break older clients iif they include both
signer.*ands3.signer.*properties for backwards compatibility (which they all should do).
However, once support for the deprecated s3.signer.* properties is removed (1.12), newer clients would break older servers (<= 1.10). If that's concerning, we could e.g. wait a few more minor releases before removal.
There was a problem hiding this comment.
shouldn't we be reading S3_SIGNER_URI first and only then fall back to CatalogProperties.SIGNER_URI and then to CatalogProperties.URI?
There was a problem hiding this comment.
You are right, I planned for it and forgot to implement 🤦♂️
There was a problem hiding this comment.
Fixed, and also added a unit test to verify the precedence behavior.
| * @deprecated since 1.11.0, will be removed in 1.12.0; use {@link CatalogProperties#SIGNER_URI} | ||
| * instead. | ||
| */ | ||
| @Deprecated public static final String S3_SIGNER_URI = CatalogProperties.SIGNER_URI; |
There was a problem hiding this comment.
I don't think we can just change the value here as that would break backwards compatibility
| "true", | ||
| CatalogProperties.URI, | ||
| uri, | ||
| CatalogProperties.SIGNER_ENDPOINT, |
There was a problem hiding this comment.
this wasn't needed before but is needed now, which indicates that this is a breaking change for users?
There was a problem hiding this comment.
For now it's not required, but it will become required in a future release (1.12 or later).
There is a check + warning here:
I proactively updated the tests so that they don't break when we make this property required.
|
|
||
| paths: | ||
|
|
||
| /v1/aws/s3/sign: |
There was a problem hiding this comment.
I don't think we would want to remove this spec yet. We should probably first deprecate it
| } | ||
| } | ||
|
|
||
| public static class RemoteSignRequestSerializer<T extends RemoteSignRequest> |
There was a problem hiding this comment.
these all should probably just be package-private and not public
| gen.writeEndArray(); | ||
| } | ||
| gen.writeEndObject(); | ||
| public static void headersToJson( |
There was a problem hiding this comment.
not sure whether we need to make this one and the one below public
| default: | ||
| throw new UnsupportedOperationException("Unsupported grant_type: " + grantType); | ||
| protected void validateSignRequest(RemoteSignRequest request) { | ||
| if ("POST".equalsIgnoreCase(request.method()) && request.uri().getQuery().contains("delete")) { |
There was a problem hiding this comment.
minor : should we use rest constants instead of raw string for "POST" ?
There was a problem hiding this comment.
Sorry I went back to raw strings because org.apache.iceberg.rest.HttpMethod is missing constants for PUT, OPTIONS, etc. which was causing integration tests to fail.
open-api/rest-catalog-open-api.yaml
Outdated
| 5XX: | ||
| $ref: '#/components/responses/ServerErrorResponse' | ||
|
|
||
| /v1/{prefix}/namespaces/{namespace}/tables/{table}/sign/{provider}: |
There was a problem hiding this comment.
that would require support for request properties
not necessarily, mainly because its something client can infer on its own, for example we wanna R/W path client can just send back the s3 as the provider while making the request ? we just need to define this field in the POST then ?
| * @param response the HTTP response to add headers to | ||
| */ | ||
| protected void addSignResponseHeaders(RemoteSignRequest request, HttpServletResponse response) { | ||
| if (request.method().equalsIgnoreCase("GET") || request.method().equalsIgnoreCase("HEAD")) { |
There was a problem hiding this comment.
we previously had this defined in a CACHEABLE_METHODS set, so would be good to keep this for easier readability
| Preconditions.checkArgument( | ||
| properties().containsKey(S3_SIGNER_URI) || properties().containsKey(CatalogProperties.URI), | ||
| properties().containsKey(S3_SIGNER_URI) | ||
| || properties().containsKey(RESTCatalogProperties.SIGNER_URI) |
There was a problem hiding this comment.
please add some tests for these new properties to testS3RemoteSignerWithoutUri()
There was a problem hiding this comment.
Added, but the tests look very similar to the ones in TestS3V4RestSignerClient.legacySignerProperties().
There was a problem hiding this comment.
sorry, I actually meant to only add tests to testS3RemoteSignerWithoutUri(), which verifies that the error msg S3 signer service URI is required is properly thrown when any of these new props are missing. No need to duplicate TestS3V4RestSignerClient.legacySignerProperties() into TestS3FileIOProperties
There was a problem hiding this comment.
But the error is only thrown when all of these props are missing. So the existing test is imho already testing sufficiently. Wdyt?
| } | ||
|
|
||
| /** | ||
| * The base URI of the remote signer endpoint. Optional, defaults to {@linkplain |
There was a problem hiding this comment.
nit: why not just {@link CatalogProperties#URI} here?
core/src/main/java/org/apache/iceberg/rest/requests/RemoteSignRequestParser.java
Show resolved
Hide resolved
core/src/main/java/org/apache/iceberg/rest/responses/RemoteSignResponseParser.java
Show resolved
Hide resolved
|
|
||
| lint-spec: | ||
| uv run yamllint --strict rest-catalog-open-api.yaml | ||
| uv run yamllint --strict ../aws/src/main/resources/s3-signer-open-api.yaml |
There was a problem hiding this comment.
I think we should still leave this in until we actually remove the openapi spec file
| * @deprecated since 1.11.0, will be removed in 1.12.0; use {@link | ||
| * org.apache.iceberg.rest.requests.RemoteSignRequestParser} instead. | ||
| */ | ||
| @Deprecated |
There was a problem hiding this comment.
I actually liked that you switched the impl here to using functionality from the new RemoteSignRequestParser for stuff, not sure why you decided to change that
There was a problem hiding this comment.
OK 😅 I thought it was a bit too invasive. Let me go back to the previous version.
| * @deprecated since 1.11.0, will be removed in 1.12.0; the serializers for S3 signing are now | ||
| * registered in {@link RESTSerializers}. | ||
| */ | ||
| @Deprecated |
There was a problem hiding this comment.
this class I would probably just deprecate and not switch to using RESTSerializers.registerAll(MAPPER).
nastra
left a comment
There was a problem hiding this comment.
overall LGTM, but left a few minor comments that would be good to address
7ee473b to
90e4eba
Compare
|
Heads up: I had to rebase because of a conflict with fec9800. |
0fcc2da to
ee33e03
Compare
|
Rebased again because of another conflict with b2f312f. |
steveloughran
left a comment
There was a problem hiding this comment.
Commented.
Looking at the signer servlet I'm wondering how over-enthusiastic about signing it is; it probably needs more validation of requests so the javadoc should warn of this.
open-api/rest-catalog-open-api.py
Outdated
| properties: dict[str, str] | None = None | ||
| body: str | None = Field( | ||
| None, | ||
| description='Optional body of the request to send to the signing API. This should only be populated for requests which do not have the relevant data in the URI itself (e.g. DeleteObjects requests)', |
There was a problem hiding this comment.
This implies that the body of PUT and multipart uploads are to be be included. They don't have to be, provided the checksum information is provided as a signed header. This avoids having to upload many GB of data to the service, needlessly.
Not sure about whether DeleteObjects qualifies here. I think technically it'd be OK to just sign the checksum, but given the damage the request can do, a production signing service SHOULD validate the entire request and every path in the body.
This'd argue for a list of which commands the body MUST be included (DeleteObjects), and where it SHOULD be omitted
- PUT
- UploadPart
- CompleteMultipartUpload
There was a problem hiding this comment.
The current description is admittedly a bit too normative, and biaised towards S3 on top of that. It should probably be revisited. But again, let's focus on promoting existing functionality from aws to core in this PR, and tackle enhancements to both the spec and test infra to follow-up PRs, wdyt?
There was a problem hiding this comment.
I'd also note that the S3 signer client currently only includes the body for DeleteObjects. PUT operations in particular do not have the body included.
There was a problem hiding this comment.
I agree the signer doesn't put the big binaries, but the spec implies they should, so should at least say "requests where the body of the message contains content which must be validated before a request is signed, such as the S3 DeleteObjects call".
FWIW I don't know which of the other stores have operations with large payloads other than their own equivalents of DeleteObjects, otherwise operations are mutating HTTP where custom headers are used.
There was a problem hiding this comment.
That's a fair point. I rephrased the description with your suggestion.
| if (HttpMethod.POST.name().equalsIgnoreCase(request.method()) | ||
| && request.uri().getQuery().contains("delete")) { | ||
| String body = request.body(); | ||
| Preconditions.checkArgument( |
There was a problem hiding this comment.
needs to be escalated to a 400 response somehow
There was a problem hiding this comment.
This PR doesn't change the behavior of this servlet, just moves some portions of it from the aws module to the core module. I'm open to enhancements to this servlet, but I think they should be introduced separately.
| public class S3SignerServlet extends RemoteSignerServlet { | ||
|
|
||
| static final Clock SIGNING_CLOCK = Clock.fixed(Instant.now(), ZoneId.of("UTC")); | ||
| static final Set<String> UNSIGNED_HEADERS = |
There was a problem hiding this comment.
good time to review the headers which mustn't be used in signing to assist in caching
Can you add "Referer" to this list; it's used used in s3a audit log, and if people work off this list they won't include it.
it's almost worth pulling this is out to list headers to to skip.
- User-Agent
- Referer (yes, that's the spelling)
- any others people know of where they'd taint cacheing and are harmless
There was a problem hiding this comment.
adding Referer would be something that should be done in a separate PR if necessary, but not here, since the functionality should stay the same
steveloughran
left a comment
There was a problem hiding this comment.
thx for the change.
Dev ML discussion: https://lists.apache.org/thread/2kqdqb46j7jww36wwg4txv6pl2hqq9w7 This commit promotes the S3 remote signing endpoint from an AWS-specific implementation to a first-class REST catalog API endpoint. This enables other storage providers (GCS, Azure, etc.) to eventually reuse the same signing endpoint pattern without duplicating the API definition. OpenAPI Specification changes: - Add `/v1/{prefix}/namespaces/{namespace}/tables/{table}/sign/{provider}` endpoint to the main REST catalog OpenAPI spec - Define `RemoteSignRequest`, `RemoteSignResult` and `RemoteSignResponse` schemas - Remove the separate `s3-signer-open-api.yaml` from the AWS module - Update the Python client Core Module changes (iceberg-core): - Add `RemoteSignRequest` and `RemoteSignResponse` model classes, copied from the iceberg-aws module - Add `RemoteSignRequestParser` and `RemoteSignResponseParser` for JSON serialization, copied from the iceberg-aws module - Add `SIGNER_URI` and `SIGNER_ENDPOINT` properties to `CatalogProperties` for configuring the signing endpoint - Add `V1_TABLE_REMOTE_SIGN` field and `remoteSign()` method to `ResourcePaths` - Register the new endpoint in `Endpoint.java` - Add abstract `RemoteSignerServlet` base class for remote signing tests, copied from the iceberg-aws module AWS Module changes (iceberg-aws): - Deprecate `S3SignRequest` and `S3SignResponse` for removal - Deprecate `S3SignRequestParser` and `S3SignResponseParser` for removal - Deprecate `S3ObjectMapper` for removal - Refactor `S3SignerServlet` to extend `RemoteSignerServlet` - Update `S3V4RestSignerClient`
This reverts commit 432ca04.
914bb9b to
852f1cb
Compare
| for requests where the body of the message contains content which must be validated before a request is | ||
| signed, such as the S3 DeleteObjects call. | ||
| provider: | ||
| type: string |
There was a problem hiding this comment.
should we define an ENUM for this, as s3a / s3e .... can create confusion for the catalog, we can say all are s3 ? similar for GCS / Azure check the resolving file IO i believe we do something similar there
There was a problem hiding this comment.
An enum means we need a spec change for every new provider – unless we go ahead an create enums for all major cloud providers?
There was a problem hiding this comment.
unless we go ahead an create enums for all major cloud providers?
thats what we had in mind, like let say s3 / azure / gcp and we can add more in case to case basis, open string still leave room for interpretation in catalog is what i think, but i can be convinced other wise :)
There was a problem hiding this comment.
OK I'm fine with that! I just introduced the enum, the constants are s3, gcs and adls (these names match the naming convention used by ResolvingFileIO).
singhpk234
left a comment
There was a problem hiding this comment.
Spec changes looks good to me.
Added a suggestion for the provider being ENUM
Dev ML discussion: https://lists.apache.org/thread/2kqdqb46j7jww36wwg4txv6pl2hqq9w7
This commit promotes the S3 remote signing endpoint from an AWS-specific implementation to a first-class REST catalog API endpoint.
This enables other storage providers (GCS, Azure, etc.) to eventually reuse the same signing endpoint pattern without duplicating the API definition.
OpenAPI Specification changes:
/v1/{prefix}/namespaces/{namespace}/tables/{table}/sign/{provider}endpoint to the main REST catalog OpenAPI specRemoteSignRequest,RemoteSignResultandRemoteSignResponseschemass3-signer-open-api.yamlfrom the AWS moduleCore Module changes (iceberg-core):
RemoteSignRequestandRemoteSignResponsemodel classes, copied from the iceberg-aws moduleRemoteSignRequestParserandRemoteSignResponseParserfor JSON serialization, copied from the iceberg-aws moduleSIGNER_URIandSIGNER_ENDPOINTproperties toCatalogPropertiesfor configuring the signing endpointV1_TABLE_REMOTE_SIGNfield andremoteSign()method toResourcePathsEndpoint.javaRemoteSignerServletbase class for remote signing tests, copied from the iceberg-aws moduleAWS Module changes (iceberg-aws):
S3SignRequestandS3SignResponsefor removalS3SignRequestParserandS3SignResponseParserfor removalS3ObjectMapperfor removalS3SignerServletto extendRemoteSignerServletS3V4RestSignerClient