Skip to content

Commit

Permalink
Add better docs for user CRD fields (#270)
Browse files Browse the repository at this point in the history
  • Loading branch information
@andrewstucki
andrewstucki authored Oct 21, 2024
1 parent e1cebd3 commit f3a6fe3
Show file tree
Hide file tree
Showing 4 changed files with 79 additions and 25 deletions.
1 change: 1 addition & 0 deletions operator/api/redpanda/v1alpha2/common.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -206,6 +206,7 @@ type AdminSASL struct {
Password SecretKeyRef `json:"passwordSecretRef,omitempty"`
// Specifies the SASL/SCRAM authentication mechanism.
Mechanism SASLMechanism `json:"mechanism"`
// Specifies token for token-based authentication (only used if no username/password are provided).
// +optional
AuthToken SecretKeyRef `json:"token,omitempty"`
}
Expand Down
37 changes: 33 additions & 4 deletions operator/api/redpanda/v1alpha2/user_types.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,9 @@ type UserTemplateSpec struct {

// UserAuthenticationSpec defines the authentication mechanism enabled for this Redpanda user.
type UserAuthenticationSpec struct {
// SASL mechanism to use for the user credentials. Valid values are:
// - scram-sha-512
// - scram-sha-256
// +kubebuilder:validation:Enum=scram-sha-256;scram-sha-512;SCRAM-SHA-256;SCRAM-SHA-512
// +kubebuilder:default=scram-sha-512
Type *SASLMechanism `json:"type,omitempty"`
Expand All @@ -119,7 +122,10 @@ type UserAuthenticationSpec struct {
// Password specifies a password for the user.
// +kubebuilder:validation:XValidation:message="valueFrom must not be empty if no value supplied",rule=`self.value != "" || has(self.valueFrom)`
type Password struct {
Value string `json:"value,omitempty"`
// Value is a hardcoded value to use for the given password. It should only be used for testing purposes.
// In production, use ValueFrom.
Value string `json:"value,omitempty"`
// ValueFrom specifies a source for a password to be fetched from when specifying or generating user credentials.
ValueFrom *PasswordSource `json:"valueFrom"`
}

Expand Down Expand Up @@ -169,6 +175,8 @@ const (

// UserAuthorizationSpec defines authorization rules for this user.
type UserAuthorizationSpec struct {
// Type specifies the type of authorization to use for User ACLs. If unspecified, defaults to `simple`. Valid values are:
// - simple
// +kubebuilder:default=simple
Type *AuthorizationType `json:"type,omitempty"`
// List of ACL rules which should be applied to this user.
Expand Down Expand Up @@ -281,14 +289,27 @@ func (a ACLOperation) ToKafka() kmsg.ACLOperation {
// +kubebuilder:validation:XValidation:message="supported transactionalId operations are ['Describe', 'Write']",rule="self.resource.type == 'transactionalId' ? self.operations.all(o, o in ['Describe', 'Write']) : true"
// +kubebuilder:validation:XValidation:message="supported cluster operations are ['Alter', 'AlterConfigs', 'ClusterAction', 'Create', 'Describe', 'DescribeConfigs', 'IdempotentWrite']",rule="self.resource.type == 'cluster' ? self.operations.all(o, o in ['Alter', 'AlterConfigs', 'ClusterAction', 'Create', 'Describe', 'DescribeConfigs', 'IdempotentWrite']) : true"
type ACLRule struct {
// Type specifies the type of ACL rule to create. Valid values are:
// - allow
// - deny
Type ACLType `json:"type"`
// Indicates the resource for which given ACL rule applies.
Resource ACLResourceSpec `json:"resource"`
// The host from which the action described in the ACL rule is allowed or denied.
// If not set, it defaults to *, allowing or denying the action from any host.
// +kubebuilder:default=*
Host *string `json:"host,omitempty"`
// List of operations which will be allowed or denied.
// List of operations which will be allowed or denied. Valid values are resource type dependent, but include:
// - Read
// - Write
// - Delete
// - Alter
// - Describe
// - IdempotentWrite
// - ClusterAction
// - Create
// - AlterConfigs
// - DescribeConfigs
// +kubebuilder:validation:MinItems=1
// +kubebuilder:validation:MaxItems=11
// +kubebuilder:validation:item:MaxLength=15
Expand Down Expand Up @@ -422,14 +443,22 @@ func (t ResourceType) ToKafka() kmsg.ACLResourceType {
// +kubebuilder:validation:XValidation:message="name must not be specified for type ['cluster']",rule=`self.type == "cluster" ? (self.name == "") : true`
// +kubebuilder:validation:XValidation:message="acl rules on non-cluster resources must specify a name",rule=`self.type == "cluster" ? true : (self.name != "")`
type ACLResourceSpec struct {
// Type specifies the type of resource an ACL is applied to. Valid values:
// - topic
// - group
// - cluster
// - transactionalId
Type ResourceType `json:"type"`
// Name of resource for which given ACL rule applies.
// Name of resource for which given ACL rule applies. If using type `cluster` this must not be specified.
// Can be combined with patternType field to use prefix pattern.
Name string `json:"name"`
// Describes the pattern used in the resource field. The supported types are literal
// and prefixed. With literal pattern type, the resource field will be used as a definition
// of a full topic name. With prefix pattern type, the resource name will be used only as
// a prefix. Default value is literal.
// a prefix. Prefixed patterns can only be specified when using types `topic`, `group`, or
// `transactionalId`. Default value is literal. Valid values:
// - literal
// - prefixed
//
// +kubebuilder:default=literal
PatternType *PatternType `json:"patternType,omitempty"`
Expand Down
10 changes: 4 additions & 6 deletions operator/config/crd/bases/cluster.redpanda.com_topics.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -101,9 +101,8 @@ spec:
- name
type: object
token:
description: |-
SecretKeyRef contains enough information to inspect or modify the referred Secret data
See https://pkg.go.dev/k8s.io/api/core/v1#ObjectReference.
description: Specifies token for token-based authentication
(only used if no username/password are provided).
properties:
key:
description: Key in Secret data to get value from
Expand Down Expand Up @@ -925,9 +924,8 @@ spec:
- name
type: object
token:
description: |-
SecretKeyRef contains enough information to inspect or modify the referred Secret data
See https://pkg.go.dev/k8s.io/api/core/v1#ObjectReference.
description: Specifies token for token-based authentication
(only used if no username/password are provided).
properties:
key:
description: Key in Secret data to get value from
Expand Down
56 changes: 41 additions & 15 deletions operator/config/crd/bases/cluster.redpanda.com_users.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,9 +61,13 @@ spec:
description: Password specifies where a password is read from.
properties:
value:
description: |-
Value is a hardcoded value to use for the given password. It should only be used for testing purposes.
In production, use ValueFrom.
type: string
valueFrom:
description: PasswordSource contains the source for a password.
description: ValueFrom specifies a source for a password to
be fetched from when specifying or generating user credentials.
properties:
secretKeyRef:
description: |-
Expand Down Expand Up @@ -104,7 +108,10 @@ spec:
rule: self.value != "" || has(self.valueFrom)
type:
default: scram-sha-512
description: SASLMechanism specifies a SASL auth mechanism.
description: |-
SASL mechanism to use for the user credentials. Valid values are:
- scram-sha-512
- scram-sha-256
enum:
- scram-sha-256
- scram-sha-512
Expand Down Expand Up @@ -133,8 +140,18 @@ spec:
If not set, it defaults to *, allowing or denying the action from any host.
type: string
operations:
description: List of operations which will be allowed or
denied.
description: |-
List of operations which will be allowed or denied. Valid values are resource type dependent, but include:
- Read
- Write
- Delete
- Alter
- Describe
- IdempotentWrite
- ClusterAction
- Create
- AlterConfigs
- DescribeConfigs
items:
description: ACLOperation specifies the type of operation
for an ACL.
Expand All @@ -148,7 +165,7 @@ spec:
properties:
name:
description: |-
Name of resource for which given ACL rule applies.
Name of resource for which given ACL rule applies. If using type `cluster` this must not be specified.
Can be combined with patternType field to use prefix pattern.
type: string
patternType:
Expand All @@ -157,14 +174,21 @@ spec:
Describes the pattern used in the resource field. The supported types are literal
and prefixed. With literal pattern type, the resource field will be used as a definition
of a full topic name. With prefix pattern type, the resource name will be used only as
a prefix. Default value is literal.
a prefix. Prefixed patterns can only be specified when using types `topic`, `group`, or
`transactionalId`. Default value is literal. Valid values:
- literal
- prefixed
enum:
- literal
- prefixed
type: string
type:
description: ResourceType specifies the type of resource
an ACL is applied to.
description: |-
Type specifies the type of resource an ACL is applied to. Valid values:
- topic
- group
- cluster
- transactionalId
enum:
- topic
- group
Expand All @@ -187,8 +211,10 @@ spec:
a name
rule: 'self.type == "cluster" ? true : (self.name != "")'
type:
description: ACLType specifies the type, either allow or
deny of an ACL rule.
description: |-
Type specifies the type of ACL rule to create. Valid values are:
- allow
- deny
enum:
- allow
- deny
Expand Down Expand Up @@ -225,8 +251,9 @@ spec:
type: array
type:
default: simple
description: AuthorizationType specifies the type of authorization
to use in creating a user.
description: |-
Type specifies the type of authorization to use for User ACLs. If unspecified, defaults to `simple`. Valid values are:
- simple
enum:
- simple
type: string
Expand Down Expand Up @@ -281,9 +308,8 @@ spec:
- name
type: object
token:
description: |-
SecretKeyRef contains enough information to inspect or modify the referred Secret data
See https://pkg.go.dev/k8s.io/api/core/v1#ObjectReference.
description: Specifies token for token-based authentication
(only used if no username/password are provided).
properties:
key:
description: Key in Secret data to get value from
Expand Down

0 comments on commit f3a6fe3

Please sign in to comment.