Skip to content

CORS: clarify API documentation and remove conformance tests for credentialed requests - #4663

Merged
k8s-ci-robot merged 3 commits into
kubernetes-sigs:mainfrom
snorwin:update-cors
Mar 18, 2026
Merged

k8s-ci-robot merged 3 commits into
kubernetes-sigs:mainfrom
snorwin:update-cors

Conversation

@snorwin

@snorwin snorwin commented Mar 10, 2026

Copy link
Copy Markdown
Member

What type of PR is this?

/kind documentation
/kind test

What this PR does / why we need it:
This PR updates the CORS API documentation to clarify how wildcard * values interact with the allowCredentials configuration and removes conformance tests that rely on detecting credentialed requests.

Previously, parts of the documentation referred to credentialed requests, which may be misleading since the gateway cannot reliably determine whether a request is credentialed. Whether a request is treated as credentialed is determined by the browser, not the server or gateway.

Which issue(s) this PR fixes:

N/A

Does this PR introduce a user-facing change?:

Clarified CORS API documentation to describe behavior based on `allowCredentials` instead of credentialed requests.

snorwin added 2 commits March 10, 2026 20:04
…I reference

Signed-off-by: Norwin Schnyder <norwin.schnyder+github@gmail.com>
Signed-off-by: Norwin Schnyder <norwin.schnyder+github@gmail.com>
@k8s-ci-robot k8s-ci-robot added release-note Denotes a PR that will be considered when it comes time to generate release notes. kind/documentation Categorizes issue or PR as related to documentation. kind/test labels Mar 10, 2026
@k8s-ci-robot k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Mar 10, 2026
@snorwin

snorwin commented Mar 10, 2026

Copy link
Copy Markdown
Member Author

/cc @rikatz @howardjohn @DamianSawicki

@DamianSawicki

Copy link
Copy Markdown
Contributor

since the gateway cannot reliably determine whether a request is credentialed. Whether a request is treated as credentialed is determined by the browser, not the server or gateway.

@jub0bs: Could you possibly help verify our assumptions here?

// the `Access-Control-Expose-Headers` response header.
// If the configuration contains the wildcard `*` in `exposeHeaders` and
// `allowCredentials` is set to `true`, the gateway cannot use the `*`
// in the `Access-Control-Expose-Headers` response header.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here I’m wondering what the purpose of allowing this configuration is:

- type: CORS
    cors:
      ...
      exposeHeaders:
        - "*"
      allowCredentials: true

If it effectively has the same semantics as when exposeHeaders is not specified at all.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW, I haven't seen any implementations that support exposing all response headers while also allowing credentialed access. It's technically difficult to do so.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If it effectively has the same semantics as when exposeHeaders is not specified at all.

Well, the semantics intended in the GEP is for the proxy to read all the headers set by the server (or by the proxy itself) and list them in the Access-Control-Expose-Headers header. However, Envoy does not support that and jub0bs explains above that it's difficult to support.

I haven't tested it, but looking at the code it seems for the above configuration translated literally from Gateway API to Envoy config, Envoy will just set

Access-Control-Expose-Headers: *
Access-Control-Allow-Credentials: true

in response headers. With exposeHeaders not specified at all, the proxy/server response is at least valid according to standards. However, according to the playground, even for the above config the response body is shared with Javascript and only headers are concealed, so you are right that the semantics in Envoy seem the same.

Since we're not aware of any proxies supporting this in the way intended in the GEP (and we don't have conformance for that), perhaps we should forbid such a config in CEL and update the GEP, but I'm not sure if it has to be included in the present PR.

@jub0bs

jub0bs commented Mar 11, 2026

Copy link
Copy Markdown

@DamianSawicki Correct. This is in line with section 3.3.5 of the Fetch standard:

A request’s credentials mode is not necessarily observable on the server; only when credentials exist for a request can it be observed by virtue of the credentials being included. Note that even so, a CORS-preflight request never includes credentials.

This instance of Jake Archibald's CORS playground offers an extreme example: under the assumption that you haven't created any cookies (or client-side certificates, etc.) associated with jakearchibald.com beforehand, the browser treats the resulting request as credentialed even though it carries no credentials whatsoever.

@DamianSawicki DamianSawicki left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We may want to follow up on exposeHeaders separately, but in the current scope as a quick improvement for 1.5.1 the PR looks good to me.

Thanks @snorwin!

/lgtm

Comment thread conformance/tests/httproute-cors.go Resolved
@k8s-ci-robot k8s-ci-robot added lgtm "Looks good to me", indicates that a PR is ready to be merged. do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. labels Mar 11, 2026
Signed-off-by: Norwin Schnyder <norwin.schnyder+github@gmail.com>
@k8s-ci-robot k8s-ci-robot removed lgtm "Looks good to me", indicates that a PR is ready to be merged. do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. labels Mar 12, 2026
@snorwin

snorwin commented Mar 12, 2026

Copy link
Copy Markdown
Member Author

@howardjohn PTAL, I’d really appreciate your opinion on this API documentation update.

@DamianSawicki DamianSawicki left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice catches in test case descriptions @snorwin! Re-lgtming.

/lgtm

@k8s-ci-robot k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Mar 12, 2026
@snorwin

snorwin commented Mar 12, 2026

Copy link
Copy Markdown
Member Author

/cherry-pick release-1.5

@k8s-infra-cherrypick-robot

Copy link
Copy Markdown
Contributor

@snorwin: once the present PR merges, I will cherry-pick it on top of release-1.5 in a new PR and assign it to you.

Details

In response to this:

/cherry-pick release-1.5

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

@kflynn

kflynn commented Mar 12, 2026

Copy link
Copy Markdown
Contributor

Concur with revisiting exposeHeaders later, but I'm OK with this for the moment.

/lgtm

@kflynn

kflynn commented Mar 12, 2026

Copy link
Copy Markdown
Contributor

/approve

@rikatz

rikatz commented Mar 18, 2026

Copy link
Copy Markdown
Member

as previously discussed, changes looks good, thanks for sticking on this and fixing all cors stuff folks
/approve

@k8s-ci-robot

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: DamianSawicki, kflynn, rikatz, snorwin

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@k8s-ci-robot k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Mar 18, 2026
@k8s-ci-robot
k8s-ci-robot merged commit ab1de57 into kubernetes-sigs:main Mar 18, 2026
20 checks passed
@k8s-infra-cherrypick-robot

Copy link
Copy Markdown
Contributor

@snorwin: #4663 failed to apply on top of branch "release-1.5":

Applying: api: use allowCredentials instead of credentialed requests in CORS API reference
Applying: conformance: remove tests for credentialed requests
Using index info to reconstruct a base tree...
M	conformance/tests/httproute-cors-allow-credentials-behavior.go
M	conformance/tests/httproute-cors.go
Falling back to patching base and 3-way merge...
Auto-merging conformance/tests/httproute-cors.go
Removing conformance/tests/httproute-cors-allow-credentials-behavior.yaml
CONFLICT (modify/delete): conformance/tests/httproute-cors-allow-credentials-behavior.go deleted in conformance: remove tests for credentialed requests and modified in HEAD. Version HEAD of conformance/tests/httproute-cors-allow-credentials-behavior.go left in tree.
error: Failed to merge in the changes.
hint: Use 'git am --show-current-patch=diff' to see the failed patch
hint: When you have resolved this problem, run "git am --continue".
hint: If you prefer to skip this patch, run "git am --skip" instead.
hint: To restore the original branch and stop patching, run "git am --abort".
hint: Disable this message with "git config set advice.mergeConflict false"
Patch failed at 0002 conformance: remove tests for credentialed requests

Details

In response to this:

/cherry-pick release-1.5

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. kind/documentation Categorizes issue or PR as related to documentation. kind/test lgtm "Looks good to me", indicates that a PR is ready to be merged. release-note Denotes a PR that will be considered when it comes time to generate release notes. size/L Denotes a PR that changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

7 participants