Documentation
¶
Overview ¶
Package rbac provides convenience methods for working with Kubernetes RBAC resources. This includes ServiceAccounts, Roles, and RoleBindings, with support for owner references and automatic garbage collection.
Error Handling and Reconciliation ¶
All methods in this package return errors directly without performing internal retries. This follows the standard Kubernetes controller pattern where the controller-runtime's work queue handles retries automatically. When an error is returned from a reconcile function, the controller-runtime will:
- Requeue the reconciliation request
- Apply exponential backoff
- Automatically retry until success or max retries
Therefore, callers should NOT use client-go's RetryOnConflict or implement manual retry logic. Simply return the error and let the controller work queue handle it.
Usage Example ¶
func (r *MyReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
rbacClient := rbac.NewClient(r.Client, r.Scheme)
// Create RBAC resources - errors are automatically retried by controller-runtime
if err := rbacClient.EnsureRBACResources(ctx, rbac.EnsureRBACResourcesParams{
Name: "my-service-account",
Namespace: "default",
Rules: myRBACRules,
Owner: myCustomResource,
}); err != nil {
// Simply return the error - controller-runtime handles retries
return ctrl.Result{}, err
}
return ctrl.Result{}, nil
}
Index ¶
- Constants
- type Client
- func (c *Client) EnsureRBACResources(ctx context.Context, params EnsureRBACResourcesParams) (OperationResults, error)
- func (c *Client) GetAllRBACResources(ctx context.Context, name, namespace string) (*corev1.ServiceAccount, *rbacv1.Role, *rbacv1.RoleBinding, error)
- func (c *Client) GetRole(ctx context.Context, name, namespace string) (*rbacv1.Role, error)
- func (c *Client) GetRoleBinding(ctx context.Context, name, namespace string) (*rbacv1.RoleBinding, error)
- func (c *Client) GetServiceAccount(ctx context.Context, name, namespace string) (*corev1.ServiceAccount, error)
- func (c *Client) UpsertRole(ctx context.Context, role *rbacv1.Role) (OperationResult, error)
- func (c *Client) UpsertRoleBinding(ctx context.Context, roleBinding *rbacv1.RoleBinding) (OperationResult, error)
- func (c *Client) UpsertRoleBindingWithOwnerReference(ctx context.Context, roleBinding *rbacv1.RoleBinding, owner client.Object) (OperationResult, error)
- func (c *Client) UpsertRoleWithOwnerReference(ctx context.Context, role *rbacv1.Role, owner client.Object) (OperationResult, error)
- func (c *Client) UpsertServiceAccount(ctx context.Context, serviceAccount *corev1.ServiceAccount) (OperationResult, error)
- func (c *Client) UpsertServiceAccountWithOwnerReference(ctx context.Context, serviceAccount *corev1.ServiceAccount, ...) (OperationResult, error)
- type EnsureRBACResourcesParams
- type OperationResult
- type OperationResults
Constants ¶
const (
// RBACAPIGroup is the Kubernetes API group for RBAC resources
RBACAPIGroup = "rbac.authorization.k8s.io"
)
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client provides convenience methods for working with Kubernetes RBAC resources.
func NewClient ¶
NewClient creates a new rbac Client instance. The scheme is required for operations that need to set owner references.
func (*Client) EnsureRBACResources ¶
func (c *Client) EnsureRBACResources(ctx context.Context, params EnsureRBACResourcesParams) (OperationResults, error)
EnsureRBACResources creates or updates a complete set of RBAC resources: ServiceAccount, Role, and RoleBinding. All resources use the same name and are created in the same namespace. The RoleBinding binds the ServiceAccount to the Role. All resources have owner references set for automatic cleanup.
This is a convenience method that consolidates the common pattern of creating RBAC resources for a controller. It returns the operation results for each resource and an error if any operation fails.
Callers should return errors to let the controller work queue handle retries.
Non-atomic behavior: Resource creation is sequential and non-atomic. If a later resource fails, earlier resources will remain. This is acceptable because:
- Controller reconciliation will retry and complete the setup
- All resources have owner references for automatic cleanup
- Partial state is temporary and self-healing via reconciliation
func (*Client) GetAllRBACResources ¶
func (c *Client) GetAllRBACResources( ctx context.Context, name, namespace string, ) (*corev1.ServiceAccount, *rbacv1.Role, *rbacv1.RoleBinding, error)
GetAllRBACResources retrieves all RBAC resources (ServiceAccount, Role, RoleBinding) with the given name and namespace. This is useful for debugging, status reporting, or verification of RBAC resource state.
If any resource is not found, it returns an error indicating which resource is missing. If all resources exist, they are returned in order: ServiceAccount, Role, RoleBinding.
func (*Client) GetRole ¶
GetRole retrieves a Kubernetes Role by name and namespace. Returns the role if found, or an error if not found or on failure.
func (*Client) GetRoleBinding ¶
func (c *Client) GetRoleBinding(ctx context.Context, name, namespace string) (*rbacv1.RoleBinding, error)
GetRoleBinding retrieves a Kubernetes RoleBinding by name and namespace. Returns the role binding if found, or an error if not found or on failure.
func (*Client) GetServiceAccount ¶
func (c *Client) GetServiceAccount(ctx context.Context, name, namespace string) (*corev1.ServiceAccount, error)
GetServiceAccount retrieves a Kubernetes ServiceAccount by name and namespace. Returns the service account if found, or an error if not found or on failure.
func (*Client) UpsertRole ¶
UpsertRole creates or updates a Kubernetes Role without an owner reference. Returns the operation result (Created, Updated, or Unchanged) and any error. Callers should return errors to let the controller work queue handle retries.
func (*Client) UpsertRoleBinding ¶
func (c *Client) UpsertRoleBinding(ctx context.Context, roleBinding *rbacv1.RoleBinding) (OperationResult, error)
UpsertRoleBinding creates or updates a Kubernetes RoleBinding without an owner reference. Returns the operation result (Created, Updated, or Unchanged) and any error. Callers should return errors to let the controller work queue handle retries.
func (*Client) UpsertRoleBindingWithOwnerReference ¶
func (c *Client) UpsertRoleBindingWithOwnerReference( ctx context.Context, roleBinding *rbacv1.RoleBinding, owner client.Object, ) (OperationResult, error)
UpsertRoleBindingWithOwnerReference creates or updates a Kubernetes RoleBinding with an owner reference. The owner reference ensures the role binding is garbage collected when the owner is deleted. Returns the operation result (Created, Updated, or Unchanged) and any error. Callers should return errors to let the controller work queue handle retries.
func (*Client) UpsertRoleWithOwnerReference ¶
func (c *Client) UpsertRoleWithOwnerReference( ctx context.Context, role *rbacv1.Role, owner client.Object, ) (OperationResult, error)
UpsertRoleWithOwnerReference creates or updates a Kubernetes Role with an owner reference. The owner reference ensures the role is garbage collected when the owner is deleted. Returns the operation result (Created, Updated, or Unchanged) and any error. Callers should return errors to let the controller work queue handle retries.
func (*Client) UpsertServiceAccount ¶
func (c *Client) UpsertServiceAccount(ctx context.Context, serviceAccount *corev1.ServiceAccount) (OperationResult, error)
UpsertServiceAccount creates or updates a Kubernetes ServiceAccount without an owner reference. Returns the operation result (Created, Updated, or Unchanged) and any error. Callers should return errors to let the controller work queue handle retries.
func (*Client) UpsertServiceAccountWithOwnerReference ¶
func (c *Client) UpsertServiceAccountWithOwnerReference( ctx context.Context, serviceAccount *corev1.ServiceAccount, owner client.Object, ) (OperationResult, error)
UpsertServiceAccountWithOwnerReference creates or updates a Kubernetes ServiceAccount with an owner reference. The owner reference ensures the service account is garbage collected when the owner is deleted. Returns the operation result (Created, Updated, or Unchanged) and any error. Callers should return errors to let the controller work queue handle retries.
type EnsureRBACResourcesParams ¶
type EnsureRBACResourcesParams struct {
// Name is the name to use for all RBAC resources (ServiceAccount, Role, RoleBinding)
Name string
// Namespace is the namespace where the RBAC resources will be created
Namespace string
// Rules are the RBAC policy rules for the Role
Rules []rbacv1.PolicyRule
// Owner is the owner object for setting owner references
Owner client.Object
// Labels are optional labels to apply to all RBAC resources
Labels map[string]string
}
EnsureRBACResourcesParams contains the parameters for EnsureRBACResources.
type OperationResult ¶
type OperationResult = controllerutil.OperationResult
OperationResult is an alias for controllerutil.OperationResult for convenience.
type OperationResults ¶
type OperationResults struct {
// ServiceAccount is the result of the ServiceAccount operation
ServiceAccount OperationResult
// Role is the result of the Role operation
Role OperationResult
// RoleBinding is the result of the RoleBinding operation
RoleBinding OperationResult
}
OperationResults contains the operation results for each RBAC resource.
Source Files