NO-JIRA: update TLS security profile documentation for clarity and consistency

[sanchezl]

Update TLS security profile documentation for clarity and consistency in preparation for possibly updating the pre-defined TLS profiles in an upcoming release.

[openshift-ci-robot]

Pipeline controller notification
This repository 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

[openshift-ci]

Hello @sanchezl! 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.

[coderabbitai]

Walkthrough

Updated documentation and comments in the TLS security profile types file to reference Mozilla TLS 5.0, clarify profile field meanings and equivalences (Old, Intermediate, Modern, Custom), and refine wording and forward-compatibility notes. No structural or API changes.

Changes

Cohort / File(s)	Summary
TLS Security Profile Documentation Updates config/v1/types_tlssecurityprofile.go	Rewrote and expanded descriptive comments for TLSSecurityProfile, OldTLSProfile, IntermediateTLSProfile, ModernTLSProfile, CustomTLSProfile, and related constants/types to align with Mozilla TLS 5.0 guidance. Clarified discriminator usage, field meanings, equivalences to custom profiles, forward-compatibility notes, and refined wording; no type or signature changes.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

• Focus review on accuracy of Mozilla TLS 5.0 references and that comments correctly describe existing behavior.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

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.}

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
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

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to Reviews -> Disable Knowledge Base setting

📥 Commits

Reviewing files that changed from the base of the PR and between 0952bf6 and ce5b632.

📒 Files selected for processing (1)

• config/v1/types_tlssecurityprofile.go (3 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**

⚙️ CodeRabbit configuration file

-Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity.

Files:

• config/v1/types_tlssecurityprofile.go

🔇 Additional comments (7)

config/v1/types_tlssecurityprofile.go (7)

7-20: ✓ Clear, consistent documentation for Type field.

The expanded comments effectively explain the profile types and their relationship to Mozilla guidelines. The intent-based nature of profiles and potential cipher list reduction are now explicit, which will help users understand forward compatibility considerations.

---

22-63: ✓ Old profile documentation effectively demonstrates equivalence.

The expanded comment clearly explains the use case and provides a concrete Custom profile equivalent. This will help users understand what they're getting with the Old profile and how to replicate it if needed.

---

69-89: ✓ Intermediate profile documentation is clear and consistent.

The expanded documentation provides good context about use cases and equivalence to Custom profiles, maintaining consistency with the Old profile documentation style.

---

91-103: ✓ Modern profile documentation is clear and appropriately concise.

The comment effectively communicates the TLS 1.3 focus and provides the Custom profile equivalent. The reduced verbosity is appropriate given the profile's simplicity.

---

121-131: ✓ Profile type struct documentation improves discoverability.

Adding documentation comments to OldTLSProfile, IntermediateTLSProfile, and ModernTLSProfile types provides better context for developers exploring the API and improves code documentation generation tools (e.g., godoc).

---

144-157: ✓ TLSProfileType constant documentation is clear and consistent.

Updated comments consistently reference the Mozilla Server Side TLS guidelines and provide good context for each constant value. This improves maintainability and user understanding.

---

201-210: ✓ TLSProfiles map documentation is clearer and more actionable.

The updated comments provide explicit Mozilla guidelines reference with version and date, and the NOTE section is reworded for better clarity about validation and whitelisting. This will help operators understand the constraints and appropriate usage patterns.

[openshift-ci-robot]

@sanchezl: This pull request explicitly references no jira issue.

In response to this:

Update TLS security profile documentation for clarity and consistency in preparation for possibly updating the pre-defined TLS profiles in an upcoming release.

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.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

config/v1/types_tlssecurityprofile.go (1)

201-210: Consider replacing “whitelist” with “allowlist” in NOTE

For more modern and inclusive terminology, you may want to replace “whitelist” with “allowlist” in the NOTE about callers validating constants. For example:

-// of ties, the kube-apiserver wins. Do not fail, just be sure to whitelist only
-// and everything will be ok.
+// of ties, the kube-apiserver wins. Do not fail, just be sure to allowlist only
+// and everything will be ok.

This keeps the meaning while aligning with current wording conventions.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to Reviews -> Disable Knowledge Base setting

📥 Commits

Reviewing files that changed from the base of the PR and between ce5b632 and be117b4.

📒 Files selected for processing (1)

• config/v1/types_tlssecurityprofile.go (3 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**

⚙️ CodeRabbit configuration file

-Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity.

Files:

• config/v1/types_tlssecurityprofile.go

🔇 Additional comments (1)

config/v1/types_tlssecurityprofile.go (1)

7-118: Doc updates for TLS profiles look consistent and accurate

The updated comments for TLSSecurityProfile, the Old/Intermediate/Modern profile fields, and the associated profile types cleanly describe intent, Mozilla TLS 5.0 basis, and the equivalence to the concrete TLSProfiles entries (minTLSVersion and cipher lists) without changing behavior. This improves clarity while keeping the API stable.

Also applies to: 121-158

[openshift-ci]

@sanchezl: 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	be117b4	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.

[everettraven]

These docs updates look good to me, but you will need to regenerate the CRDs.

If you run PROTO_OPTIONAL=true make update and include the changes in your commit, that should resolve the verify failure