openshift
OCPBUGS-56851: make multiline comments for oidc one line for better crd gen and better `oc explain` description format
This change specifically targets OIDC-specific comments to ensure oc explain, based on CRD generation, will render the Description field in an optimal format i.e. no disjointed lines.
Pipeline controller notification
This repo is configured to use the pipeline controller. Second-stage tests will be triggered either automatically or after lgtm label is added, depending on the repository configuration. The pipeline controller will automatically detect which contexts are required and will utilize /test Prow commands to trigger the second stage.
For optional jobs, comment /test ? to see a list of all defined jobs. To trigger manually all jobs from second stage use /pipeline required command.
This repository is configured in: LGTM mode
Hello @ehearne-redhat! Some important instructions when contributing to openshift/api: API design plays an important part in the user experience of OpenShift and as such API PRs are subject to a high level of scrutiny to ensure they follow our best practices. If you haven't already done so, please review the OpenShift API Conventions and ensure that your proposed changes are compliant. Following these conventions will help expedite the api review process for your PR.
![openshift-ci[bot] avatar](https://avatars.githubusercontent.com/in/91280?v=4 "Published by a pub.dev verified publisher"){kind=small}
@ehearne-redhat: This pull request references Jira Issue OCPBUGS-56851, which is valid. The bug has been moved to the POST state.
3 validation(s) were run on this bug
- bug is open, matching expected state (open)
- bug target version (4.22.0) matches configured target version for branch (4.22.0)
- bug is in the state ASSIGNED, which is one of the valid states (NEW, ASSIGNED, POST)
Requesting review from QA contact: /cc @xingxingxia
The bug has been updated to refer to the pull request using the external bug tracker.
In response to this:
This change specifically targets OIDC-specific comments to ensure
oc explain, based on CRD generation, will render theDescriptionfield in an optimal format i.e. no disjointed lines.
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 openshift-eng/jira-lifecycle-plugin repository.
📝 Walkthrough
Walkthrough
The PR updates documentation strings and formatting across generated Go files, the OpenAPI outputs, and multiple Authentication CRD YAMLs. It also adds a new OpenAPI definition AcceptRisk and new properties: Update.acceptRisks, riskNames, and conditions. No existing public type or method signatures were changed beyond the added OpenAPI definitions and properties; remaining edits are descriptive or formatting-only.
🚥 Pre-merge checks | ✅ 2 | ❌ 1
❌ Failed checks (1 warning)
| Check name | Status | Explanation | Resolution |
|---|---|---|---|
| Docstring Coverage | ⚠️ Warning | Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. | Write docstrings for the functions missing them to satisfy the coverage threshold. |
✅ Passed checks (2 passed)
| Check name | Status | Explanation |
|---|---|---|
| Title check | ✅ Passed | The title clearly describes the main change: reformatting OIDC-related multiline comments into single lines to improve CRD generation and oc explain output formatting. |
| Description check | ✅ Passed | The description is directly related to the changeset, explaining the purpose of converting multiline comment fragments into sentence-style lines for better CRD description formatting. |
✏️ Tip: You can configure your own custom pre-merge checks in the settings.
✨ Finishing touches
- [ ] 📝 Generate docstrings
[!WARNING] There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.
🔧 golangci-lint (2.5.0)
Error: build linters: unable to load custom analyzer "kubeapilinter": tools/_output/bin/kube-api-linter.so, plugin: not implemented The command is terminated due to an error: build linters: unable to load custom analyzer "kubeapilinter": tools/_output/bin/kube-api-linter.so, plugin: not implemented
Comment @coderabbitai help to get the list of available commands and usage tips.
![coderabbitai[bot] avatar](https://avatars.githubusercontent.com/in/347564?v=4 "Published by a pub.dev verified publisher"){kind=small}
✅ Actions performed
Review triggered.
Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.
PR-Agent: could not fine a component named verify in a supported language in this PR.
![qodo-code-review[bot] avatar](https://avatars.githubusercontent.com/in/484649?v=4 "Published by a pub.dev verified publisher"){kind=small}
Verify should only fail on this repo if you have out of date generation, I can see in the logs it's showing a diff so you'll need to investigate this
Hey @everettraven - I spun up a kind cluster and applied the old and new CRD authentications . This is an example but I can get more if needed.
OLD
ehearne-mac:api ehearne$ kubectl explain authentication.spec.oidcProviders.claimMappings.extra
GROUP: config.openshift.io
KIND: Authentication
VERSION: v1
FIELD: extra <[]Object>
DESCRIPTION:
extra is an optional field for configuring the mappings
used to construct the extra attribute for the cluster identity.
When omitted, no extra attributes will be present on the cluster identity.
key values for extra mappings must be unique.
A maximum of 32 extra attribute mappings may be provided.
ExtraMapping allows specifying a key and CEL expression
to evaluate the keys' value. It is used to create additional
mappings and attributes added to a cluster identity from
a provided authentication token.
...
NEW:
ehearne-mac:api ehearne$ kubectl explain authentication.spec.oidcProviders.claimMappings.extra
GROUP: config.openshift.io
KIND: Authentication
VERSION: v1
FIELD: extra <[]Object>
DESCRIPTION:
extra is an optional field for configuring the mappings used to construct
the extra attribute for the cluster identity.
When omitted, no extra attributes will be present on the cluster identity.
key values for extra mappings must be unique.
A maximum of 32 extra attribute mappings may be provided.
ExtraMapping allows specifying a key and CEL expression
to evaluate the keys' value. It is used to create additional
mappings and attributes added to a cluster identity from
a provided authentication token.
...
@ehearne-redhat Thanks for that! Do we have a list of what looked to be the worst offenders that we can verify look better with these changes?
Hey @everettraven - I don't have a specific list to hand. However, I believe the ones that were the big offenders were UsernameClaimMapping.Claim, and maybe OIDCClientConfig.ComponentNamespace .
What I'll do is, I'll compile a list of all these changes old vs new, and pick out a few which demonstrate this change best.
Hey @everettraven - I have a few examples here but can get more if needed.
spec.oidcProviders.claimMappings
Before (master)
GROUP: config.openshift.io
KIND: Authentication
VERSION: v1
FIELD: claimMappings <Object>
DESCRIPTION:
claimMappings is a required field that configures the rules to be used by
the Kubernetes API server for translating claims in a JWT token, issued
by the identity provider, to a cluster identity.
FIELDS:
extra <[]Object>
extra is an optional field for configuring the mappings
used to construct the extra attribute for the cluster identity.
When omitted, no extra attributes will be present on the cluster identity.
key values for extra mappings must be unique.
A maximum of 32 extra attribute mappings may be provided.
groups <Object>
groups is an optional field that configures how the groups of a cluster
identity
should be constructed from the claims in a JWT token issued
by the identity provider.
When referencing a claim, if the claim is present in the JWT
token, its value must be a list of groups separated by a comma (',').
For example - '"example"' and '"exampleOne", "exampleTwo", "exampleThree"'
are valid claim values.
uid <Object>
uid is an optional field for configuring the claim mapping
used to construct the uid for the cluster identity.
When using uid.claim to specify the claim it must be a single string value.
When using uid.expression the expression must result in a single string
value.
When omitted, this means the user has no opinion and the platform
is left to choose a default, which is subject to change over time.
The current default is to use the 'sub' claim.
username <Object> -required-
username is a required field that configures how the username of a cluster
identity
should be constructed from the claims in a JWT token issued by the identity
provider.
After (current branch)
GROUP: config.openshift.io
KIND: Authentication
VERSION: v1
FIELD: claimMappings <Object>
DESCRIPTION:
claimMappings is a required field that configures the rules to be used by
the Kubernetes API server for translating claims in a JWT token, issued by
the identity provider, to a cluster identity.
FIELDS:
extra <[]Object>
extra is an optional field for configuring the mappings used to construct
the extra attribute for the cluster identity.
When omitted, no extra attributes will be present on the cluster identity.
key values for extra mappings must be unique.
A maximum of 32 extra attribute mappings may be provided.
groups <Object>
groups is an optional field that configures how the groups of a cluster
identity should be constructed from the claims in a JWT token issued by the
identity provider.
When referencing a claim, if the claim is present in the JWT token, its
value must be a list of groups separated by a comma (',').
For example - '"example"' and '"exampleOne", "exampleTwo", "exampleThree"'
are valid claim values.
uid <Object>
uid is an optional field for configuring the claim mapping used to construct
the uid for the cluster identity.
When using uid.claim to specify the claim it must be a single string value.
When using uid.expression the expression must result in a single string
value.
When omitted, this means the user has no opinion and the platform is left to
choose a default, which is subject to change over time.
The current default is to use the 'sub' claim.
username <Object> -required-
username is a required field that configures how the username of a cluster
identity should be constructed from the claims in a JWT token issued by the
identity provider.
spec.oidcProviders.claimMappings.groups
Before (master)
GROUP: config.openshift.io
KIND: Authentication
VERSION: v1
FIELD: groups <Object>
DESCRIPTION:
groups is an optional field that configures how the groups of a cluster
identity
should be constructed from the claims in a JWT token issued
by the identity provider.
When referencing a claim, if the claim is present in the JWT
token, its value must be a list of groups separated by a comma (',').
For example - '"example"' and '"exampleOne", "exampleTwo", "exampleThree"'
are valid claim values.
FIELDS:
claim <string> -required-
claim is a required field that configures the JWT token
claim whose value is assigned to the cluster identity
field associated with this mapping.
prefix <string>
prefix is an optional field that configures the prefix that will be
applied to the cluster identity attribute during the process of mapping
JWT claims to cluster identity attributes.
When omitted (""), no prefix is applied to the cluster identity attribute.
Example: if `prefix` is set to "myoidc:" and the `claim` in JWT contains
an array of strings "a", "b" and "c", the mapping will result in an
array of string "myoidc:a", "myoidc:b" and "myoidc:c".
After (current branch)
GROUP: config.openshift.io
KIND: Authentication
VERSION: v1
FIELD: groups <Object>
DESCRIPTION:
groups is an optional field that configures how the groups of a cluster
identity should be constructed from the claims in a JWT token issued by the
identity provider.
When referencing a claim, if the claim is present in the JWT token, its
value must be a list of groups separated by a comma (',').
For example - '"example"' and '"exampleOne", "exampleTwo", "exampleThree"'
are valid claim values.
FIELDS:
claim <string> -required-
claim is a required field that configures the JWT token claim whose value is
assigned to the cluster identity field associated with this mapping.
prefix <string>
prefix is an optional field that configures the prefix that will be applied
to the cluster identity attribute during the process of mapping JWT claims
to cluster identity attributes.
When omitted (""), no prefix is applied to the cluster identity attribute.
Example: if `prefix` is set to "myoidc:" and the `claim` in JWT contains an
array of strings "a", "b" and "c", the mapping will result in an array of
string "myoidc:a", "myoidc:b" and "myoidc:c".
spec.oidcProviders.claimMappings.username
Before (master)
GROUP: config.openshift.io
KIND: Authentication
VERSION: v1
FIELD: username <Object>
DESCRIPTION:
username is a required field that configures how the username of a cluster
identity
should be constructed from the claims in a JWT token issued by the identity
provider.
FIELDS:
claim <string> -required-
claim is a required field that configures the JWT token
claim whose value is assigned to the cluster identity
field associated with this mapping.
claim must not be an empty string ("") and must not exceed 256 characters.
prefix <Object>
prefix configures the prefix that should be prepended to the value
of the JWT claim.
prefix must be set when prefixPolicy is set to 'Prefix' and must be unset
otherwise.
prefixPolicy <string>
enum: "", NoPrefix, Prefix
prefixPolicy is an optional field that configures how a prefix should be
applied to the value of the JWT claim specified in the 'claim' field.
Allowed values are 'Prefix', 'NoPrefix', and omitted (not provided or an
empty string).
When set to 'Prefix', the value specified in the prefix field will be
prepended to the value of the JWT claim.
The prefix field must be set when prefixPolicy is 'Prefix'.
When set to 'NoPrefix', no prefix will be prepended to the value
of the JWT claim.
When omitted, this means no opinion and the platform is left to choose
any prefixes that are applied which is subject to change over time.
Currently, the platform prepends `{issuerURL}#` to the value of the JWT
claim
when the claim is not 'email'.
As an example, consider the following scenario:
`prefix` is unset, `issuerURL` is set to `https://myoidc.tld`,
the JWT claims include "username":"userA" and "email":"[email protected]",
and `claim` is set to:
- "username": the mapped value will be "https://myoidc.tld#userA"
- "email": the mapped value will be "[email protected]"
After (current branch)
GROUP: config.openshift.io
KIND: Authentication
VERSION: v1
FIELD: username <Object>
DESCRIPTION:
username is a required field that configures how the username of a cluster
identity should be constructed from the claims in a JWT token issued by the
identity provider.
FIELDS:
claim <string> -required-
claim is a required field that configures the JWT token claim whose value is
assigned to the cluster identity field associated with this mapping.
claim must not be an empty string ("") and must not exceed 256 characters.
prefix <Object>
prefix configures the prefix that should be prepended to the value of the
JWT claim.
prefix must be set when prefixPolicy is set to 'Prefix' and must be unset
otherwise.
prefixPolicy <string>
enum: "", NoPrefix, Prefix
prefixPolicy is an optional field that configures how a prefix should be
applied to the value of the JWT claim specified in the 'claim' field.
Allowed values are 'Prefix', 'NoPrefix', and omitted (not provided or an
empty string).
When set to 'Prefix', the value specified in the prefix field will be
prepended to the value of the JWT claim.
The prefix field must be set when prefixPolicy is 'Prefix'.
When set to 'NoPrefix', no prefix will be prepended to the value of the JWT
claim.
When omitted, this means no opinion and the platform is left to choose any
prefixes that are applied which is subject to change over time.
Currently, the platform prepends `{issuerURL}#` to the value of the JWT
claim when the claim is not 'email'.
As an example, consider the following scenario:
`prefix` is unset, `issuerURL` is set to `https://myoidc.tld`,
the JWT claims include "username":"userA" and "email":"[email protected]",
and `claim` is set to:
- "username": the mapped value will be "https://myoidc.tld#userA"
- "email": the mapped value will be "[email protected]"
Hoping I caught those pesky comments ! :D Thanks again @everettraven for the reviews.
Scheduling tests matching the pipeline_run_if_changed or not excluded by pipeline_skip_if_only_changed parameters:
/test e2e-aws-ovn
/test e2e-aws-ovn-hypershift
/test e2e-aws-ovn-hypershift-conformance
/test e2e-aws-ovn-techpreview
/test e2e-aws-serial-1of2
/test e2e-aws-serial-2of2
/test e2e-aws-serial-techpreview-1of2
/test e2e-aws-serial-techpreview-2of2
/test e2e-azure
/test e2e-gcp
/test e2e-upgrade
/test e2e-upgrade-out-of-change
[APPROVALNOTIFIER] This PR is APPROVED
This pull-request has been approved by: everettraven
The full list of commands accepted by this bot can be found here.
The pull request process is described here
- ~~OWNERS~~ [everettraven]
Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment
@xingxingxia could you take a look and verify when you have the time? :)
These tests no longer exist and were sharded a while ago. The sharded versions are passing on this PR.
/override ci/prow/e2e-aws-serial /override ci/prow/e2e-aws-serial-techpreview
@everettraven: Overrode contexts on behalf of everettraven: ci/prow/e2e-aws-serial, ci/prow/e2e-aws-serial-techpreview
In response to this:
These tests no longer exist and were sharded a while ago. The sharded versions are passing on this PR.
/override ci/prow/e2e-aws-serial /override ci/prow/e2e-aws-serial-techpreview
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.
Launched a cluster of cluster-bot build. Issues are gone /verified by @xingxingxia
@xingxingxia: This PR has been marked as verified by @xingxingxia.
In response to this:
Launched a cluster of cluster-bot build. Issues are gone /verified by @xingxingxia
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 openshift-eng/jira-lifecycle-plugin repository.
@ehearne-redhat: all tests passed!
Full PR test history. Your PR dashboard.
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. I understand the commands that are listed here.
@ehearne-redhat: Jira Issue Verification Checks: Jira Issue OCPBUGS-56851 :heavy_check_mark: This pull request was pre-merge verified. :heavy_check_mark: All associated pull requests have merged. :heavy_check_mark: All associated, merged pull requests were pre-merge verified.
Jira Issue OCPBUGS-56851 has been moved to the MODIFIED state and will move to the VERIFIED state when the change is available in an accepted nightly payload. :clock4:
In response to this:
This change specifically targets OIDC-specific comments to ensure
oc explain, based on CRD generation, will render theDescriptionfield in an optimal format i.e. no disjointed lines.
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 openshift-eng/jira-lifecycle-plugin repository.
Fix included in accepted release 4.22.0-0.nightly-2026-01-24-213011
