CNTRLPLANE-367: Update Authentication API GoDoc for OIDC-related fields #2314

everettraven · 2025-05-07T19:32:46Z

I had noticed that the GoDoc for the OIDC-related fields was a bit sparse and needed to be brought up to date with the OpenShift API conventions.

This PR attempts to improve the GoDoc for only the OIDC-related fields as part of the GA criteria for the BYO OIDC feature.

Signed-off-by: Bryce Palmer <[email protected]>

openshift-ci · 2025-05-07T19:32:56Z

Hello @everettraven! 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 · 2025-05-07T19:33:25Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: everettraven
Once this PR has been reviewed and has the lgtm label, please assign joelspeed for approval. For more information see the Code Review Process.

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

Needs approval from an approver in each of these files:

OWNERS

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

openshift-ci-robot · 2025-05-07T19:37:50Z

@everettraven: This pull request references CNTRLPLANE-367 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "4.20.0" version, but no target version was set.

In response to this:

I had noticed that the GoDoc for the OIDC-related fields was a bit sparse and needed to be brought up to date with the OpenShift API conventions.

This PR attempts to improve the GoDoc for only the OIDC-related fields as part of the GA criteria for the BYO OIDC feature.

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.

jacobsee · 2025-05-07T22:39:34Z

config/v1/types_authentication.go

 	ClaimMappings TokenClaimMappings `json:"claimMappings"`

-	// claimValidationRules are rules that are applied to validate token claims to authenticate users.
+	// claimValidationRules configures the rules to be used the Kubernetes API Server


Suggested change

// claimValidationRules configures the rules to be used the Kubernetes API Server

// claimValidationRules configures the rules to be used by the Kubernetes API Server

jacobsee · 2025-05-07T22:54:54Z

config/v1/types_authentication.go

 	// type sets the type of the validation rule
 	//
+	// type configures the type of the validation rule.
+	// type is optional.


Suggested change

// type sets the type of the validation rule

//

// type configures the type of the validation rule.

// type is optional.

// type configures the type of the validation rule.

// type is optional.

liouk · 2025-05-08T14:39:05Z

config/v1/types_authentication.go

+	// name configures the unique human-readable identifier
+	// associated with the identity provider.
+	// name is used to distinguish between multiple identity providers.
+	// name has no impact on token validation or authentication mechanics.
+	// name is required.
+	// name must not be an empty string ("").


Instead of repeating name ... in the beginning of every sentence, would it make sense to make it a bit more natural, such as:

Suggested change

// name configures the unique human-readable identifier

// associated with the identity provider.

// name is used to distinguish between multiple identity providers.

// name has no impact on token validation or authentication mechanics.

// name is required.

// name must not be an empty string ("").

// Name configures the unique human-readable identifier

// associated with the identity provider.

// Used to distinguish between multiple identity providers and

// has no impact on token validation or authentication mechanics.

// It is required and must not be an empty string ("").

Also, we should probably match case in the doc comments.

This also seems to agree with our API conventions. This applies to various places in this diff.

Yeah, looking back at this I went a little overboard with the repetition there 😅 - updating.

Also, we should probably match case in the doc comments.

It's API convention to match the serialized name, not the field name in the Go type

For additional context on the serialized name matching, see: #2314 (comment)

liouk · 2025-05-08T14:41:51Z

config/v1/types_authentication.go

+	// issuer configures how the platform interacts
+	// with the identity provider and how tokens issued
+	// from the identity provider are evaluated by the
+	// Kubernetes API Server.


This looks like a more suitable comment for the type TokenIssuer instead of the field.

Comments on top level types do not get included in the generated OpenAPI spec field documentation that is shown to end users for fields of that type. This comment is here so that it appears for the end-user and explains what this field is used for if they run something like oc explain ...

liouk · 2025-05-08T14:43:12Z

config/v1/types_authentication.go

 	ClaimValidationRules []TokenClaimValidationRule `json:"claimValidationRules,omitempty"`
 }

 // +kubebuilder:validation:MinLength=1
 type TokenAudience string

 type TokenIssuer struct {
-	// URL is the serving URL of the token issuer.
-	// Must use the https:// scheme.
+	// issuerURL configures the URL that is used to issue tokens


Wrong field name.

issuerURL is the serialized name which we prefer to use for GoDoc on the OpenShift APIs because it is what end-users will be familiar with. The serialized field name is what the documentation, generated by the GoDoc, will be attached to when users do something like oc explain ... on the field

liouk · 2025-05-08T14:44:00Z

config/v1/types_authentication.go

-	// configuration namespace. The .data of the configMap must contain
-	// the "ca-bundle.crt" key.
-	// If unset, system trust is used instead.
+	// issuerCertificateAuthority configures the certificate authority,


Wrong field name here as well.

See explanation here: #2314 (comment)

liouk · 2025-05-08T14:46:15Z

config/v1/types_authentication.go

 	//
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=63
 	// +required
 	ComponentNamespace string `json:"componentNamespace"`

-	// clientID is the identifier of the OIDC client from the OIDC provider
+	// clientID configures the identifier, from the identity provider, that the platform


Suggested change

// clientID configures the identifier, from the identity provider, that the platform

// clientID configures the client identifier, from the identity provider, that the platform

Signed-off-by: Bryce Palmer <[email protected]>

openshift-ci · 2025-05-08T18:58:59Z

@everettraven: The following test failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
ci/prow/verify	`053afe5`	link	true	`/test verify`

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.

config/v1: update oidc-related field godoc

a03cb39

Signed-off-by: Bryce Palmer <[email protected]>

openshift-ci bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label May 7, 2025

openshift-ci bot requested review from deads2k and JoelSpeed May 7, 2025 19:33

everettraven changed the title ~~Update Authentication API GoDoc for OIDC-related fields~~ CNTRLPLANE-367: Update Authentication API GoDoc for OIDC-related fields May 7, 2025

openshift-ci-robot added the jira/valid-reference Indicates that this PR references a valid Jira ticket of any type. label May 7, 2025

jacobsee reviewed May 7, 2025

View reviewed changes

liouk suggested changes May 8, 2025

View reviewed changes

fixup! minor tweaks based on reviews

053afe5

Signed-off-by: Bryce Palmer <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CNTRLPLANE-367: Update Authentication API GoDoc for OIDC-related fields #2314

CNTRLPLANE-367: Update Authentication API GoDoc for OIDC-related fields #2314

everettraven commented May 7, 2025

openshift-ci bot commented May 7, 2025

openshift-ci bot commented May 7, 2025

openshift-ci-robot commented May 7, 2025 •

edited by openshift-ci bot

Loading

jacobsee May 7, 2025

jacobsee May 7, 2025

liouk May 8, 2025

everettraven May 8, 2025

everettraven May 8, 2025

everettraven May 8, 2025

liouk May 8, 2025

everettraven May 8, 2025

liouk May 8, 2025

everettraven May 8, 2025

liouk May 8, 2025

everettraven May 8, 2025

liouk May 8, 2025

openshift-ci bot commented May 8, 2025

	// claimValidationRules configures the rules to be used the Kubernetes API Server
	// claimValidationRules configures the rules to be used by the Kubernetes API Server

	// clientID configures the identifier, from the identity provider, that the platform
	// clientID configures the client identifier, from the identity provider, that the platform

CNTRLPLANE-367: Update Authentication API GoDoc for OIDC-related fields #2314

Are you sure you want to change the base?

CNTRLPLANE-367: Update Authentication API GoDoc for OIDC-related fields #2314

Conversation

everettraven commented May 7, 2025

openshift-ci bot commented May 7, 2025

openshift-ci bot commented May 7, 2025

openshift-ci-robot commented May 7, 2025 • edited by openshift-ci bot Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

openshift-ci bot commented May 8, 2025

openshift-ci-robot commented May 7, 2025 •

edited by openshift-ci bot

Loading