Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

📖 doc: validating and parsing CRD fields #4396

Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions docs/book/src/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,36 @@ Your CRDs are generated using [controller-gen][controller-gen]. By using the opt

You can review the design of your APIs and see if it has not more specs than should be by hurting single responsibility principle for example. So that you might to re-design them.

## How can I validate and parse fields in CRDs effectively?

To enhance user experience, it is recommended to use [OpenAPI v3 schema](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#schemaObject) validation when writing your CRDs. However, this approach can sometimes require an additional parsing step.
For example, consider this code
```go
type StructName struct {
// +kubebuilder:validation:Format=date-time
TimeField string `json:"timeField,omitempty"`
}
```

### What happens in this scenario?

- Users will receive an error notification from the Kubernetes API if they attempt to create a CRD with an invalid timeField value.
- On the developer side, the string value needs to be parsed manually before use.

### Is there a better approach?

To provide both a better user experience and a streamlined developer experience, it is advisable to use predefined types like [`metav1.Time`](https://pkg.go.dev/k8s.io/apimachinery@v0.31.1/pkg/apis/meta/v1#Time)
For example, consider this code
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
For example, consider this code
**Example**

Copy link
Contributor Author

Choose a reason for hiding this comment

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

added title instead

```go
type StructName struct {
TimeField metav1.Time `json:"timeField,omitempty"`
}
```

### What happens in this scenario?

- Users still receive error notifications from the Kubernetes API for invalid `timeField` values.
- Developers can directly use the parsed TimeField in their code without additional parsing, reducing errors and improving efficiency.



Expand Down
Loading