DOCSEARCHbyAlgolia
Submit Docs

RabbitMQ Cluster Operator

repository·main·Indexed 22 days ago

https://github.com/rabbitmq/cluster-operator

A Kubernetes operator for automating the deployment and lifecycle management of RabbitMQ clusters, including creation, upgrades, and graceful shutdowns. It provides capabilities for overriding Service and StatefulSet properties, configuring custom RabbitMQ settings via additionalConfig, managing community plugins, importing definitions via ConfigMaps or HTTPS URLs, and integrating external secrets for admin credentials.

Tokens
27.8K
Snippets
98
Records
136
Agent score
77%

What's inside rabbitmq-cluster-operator

  1. Overview of RabbitMQ Cluster Operator capabilities

    main

    The RabbitMQ Cluster Kubernetes Operator is a custom controller and Custom Resource Definition (CRD) designed to manage the full lifecycle of RabbitMQ clusters on Kubernetes. It automates tasks including:

    • Creation: Provisioning new RabbitMQ clusters.
    • Upgrade: Managing version updates for existing clusters.
    • Graceful Shutdown: Ensuring clusters are shut down safely.

  2. What is a Preferred / Storage version in Kubernetes?

    main

    In Kubernetes, when a resource has multiple API versions, one version is designated as the 'preferred' or 'storage' version.

    • The Kubernetes API server uses this version to save the resource in etcd.
    • If a user interacts with the resource using a different API version, the API server performs a lossless conversion to the storage version before saving.
    • Typically, the latest API version is the storage version, except during the initial release of a resource to comply with the Kubernetes Deprecation Policy.

  3. Configure NetworkPolicy traffic patterns for RabbitMQ

    main

    When implementing NetworkPolicies for a RabbitMQ cluster, you should consider three primary traffic patterns to ensure both security and functionality:

    1. Inter-node Traffic: Ensure that Pods within the same RabbitmqCluster can communicate with each other on the specific ports used for cluster synchronization and inter-node communication.
    2. Operator Traffic: Allow the cluster-operator and the messaging-topology-operator to communicate with the RabbitMQ Pods over HTTP. This is required for the operators to perform reconciliation operations.
    3. External/Client Traffic: Allow ingress traffic to external-facing ports (e.g., AMQP for messaging, Prometheus ports for scraping).

    Best Practice: For external traffic, instead of allowing all ingress, use a podSelector to restrict access only to known client application Pods or specific Prometheus servers.

    Warning: The ports used in standard examples are the RabbitMQ defaults. If you have configured custom ports in your RabbitmqCluster specification, you must update your NetworkPolicies to match those custom ports.

  4. Understand RabbitMQ Cluster Operator compatibility ranges

    main

    Each release of the operator defines supported ranges for several components. You should check the GitHub Release notes to find the specific supported versions for your release. The operator supports:

    • RabbitMQ Versions: Each release has a minimum and maximum supported RabbitMQ version. While the operator provides defaults, you are free to change your deployment manifest to any supported version for that release.
    • Kubernetes Server Versions: Each release supports a range of Kubernetes server versions (e.g., 1.15-1.17).
    • API Versions: The operator supports a range of API versions for its managed resources (e.g., rabbitmq.com/v1, rabbitmq.com/v2). Support for API versions aligns with the Kubernetes Deprecation Policy. Deprecations or removals of API versions occur during MINOR operator releases.

  6. Understand the types of Prometheus rules provided

    main

    The RabbitMQ Cluster Operator provides two types of Prometheus rules:

    1. Alerting Rules: These are used to trigger alerts based on specific metric thresholds or conditions. Most files in the observability/prometheus/rules/ directory are alerting rules.
    2. Recording Rules: These are used to pre-calculate frequently used or expensive queries and save them as new time series. These are specifically located in rabbitmq/recording-rules.yml.

  7. Configure Subject Alternative Names (SANs) for TLS certificates

    main

    For TLS connections to be trusted by clients, the certificates used by RabbitMQ nodes must include specific Subject Alternative Names (SANs). The SANs must match the DNS names used to reach the nodes and the service.

    Required SAN Patterns

    At a minimum, the certificate should include:

    1. A wildcard pattern for the nodes: *.<RabbitMQ cluster name>-nodes.<namespace>.svc.<K8s cluster domain name>
    2. The client service DNS name: <RabbitMQ cluster name>.<namespace>.svc.<K8s cluster domain name>

    Example Configuration

    For a 3-node cluster named myrabbit in namespace mynamespace with the domain cluster.local, the SANs must include:

    • myrabbit-server-0.myrabbit-nodes.mynamespace.svc.cluster.local
    • myrabbit-server-1.myrabbit-nodes.mynamespace.svc.cluster.local
    • myrabbit-server-2.myrabbit-nodes.mynamespace.svc.cluster.local
    • myrabbit.mynamespace.svc.cluster.local

    Note: If wildcards are not permitted, you must provide a separate SAN attribute for every individual node. If using spec.service.type: NodePort, you may also need to include the external IP addresses of each Kubernetes node in the SANs.

  8. Customize RabbitMQ deployments using CRD overrides

    main

    The RabbitmqCluster CRD provides an override mechanism that allows users to configure any field of the underlying Kubernetes StatefulSet and the client Service. This bypasses the limited set of properties explicitly defined in the CRD spec, enabling support for diverse use cases without requiring the operator to implement every possible Kubernetes configuration field manually.

    Use this feature when you need to apply specific Kubernetes configurations to your RabbitMQ nodes or services that are not directly exposed as top-level properties in the RabbitmqCluster spec.

  9. Understand the RabbitMQ Cluster Operator versioning and release strategy

    main

    The RabbitMQ Cluster Operator uses a versioning strategy designed to help users make informed decisions about upgrades. Because the operator manages dependencies like RabbitMQ and Kubernetes—which do not always follow strict Semantic Versioning (SemVer)—the operator's versioning aims to communicate the scope of changes clearly.

    Key aspects of the strategy include:

    • Functionality Changes: Bug fixes or new configuration options.
    • Compatibility Changes: Support or deprecation of specific Kubernetes server versions or RabbitMQ versions.
    • API Changes: Introduction of new resource API versions (e.g., RabbitmqCluster) or changes to the 'Storage version'.
    • Support Lifecycle: Changes in commercial support availability.

    Users should be aware that while the operator aims for clarity, the underlying software it manages (RabbitMQ and Kubernetes) may introduce breaking changes in minor or patch releases.

  10. Understand the RabbitMQ Cluster Operator versioning scheme

    main

    The RabbitMQ Cluster Operator uses a hybrid CalVer (Calendar Versioning) scheme to communicate the significance of changes and supportability. The version format is:

    YYYY.MINOR.MICRO

    Version Components

    • YYYY (Year): Indicates the year of release. This helps users determine supportability. For example, if a commercial support window is 18 months, a version from two years ago is clearly out of support.
    • MINOR: Represents any significant change, including new features, breaking changes, or changes to supported versions of RabbitMQ, Kubernetes, or the RabbitmqCluster API/storage versions.
    • MICRO: Reserved strictly for low-risk changes that do not affect the core logic or supported dependencies. Only the following are considered MICRO changes:
      • Bugfixes to the operator code.
      • Bugfixes to the operator's Docker image.
      • Bumping the default RabbitMQ image to a new patch version.

    Upgrade Guidance

    Because the operator manages complex dependencies (RabbitMQ, Kubernetes, and API versions), users should always consult the changelog before upgrading. A version bump in the MINOR digit may include breaking changes to the supported environment or the RabbitmqCluster resource schema.

    YYYY.MINOR.MICRO

  11. Configure RabbitMQ TLS using HashiCorp Vault PKI

    main

    You can configure RabbitmqCluster resources to have their server certificates issued by the Vault PKI Secrets Engine.

    Unlike standard TLS configurations where certificates and private keys are manually placed into a Kubernetes Secret, this method uses a Vault sidecar container to manage short-lived certificates.

    Key Behaviors:

    • Short-lived certificates: New certificates are issued from the Vault PKI Secrets Engine upon every RabbitMQ Pod (re)start.
    • Security: The private key is never stored in Vault.
    • Zero-downtime rotation: Before a certificate expires, the Vault sidecar requests a new one and places it in /etc/rabbitmq-tls/. The Erlang VM picks up the new certificate on-the-fly without requiring a pod restart.

    To enable this, you must configure the spec.secretBackend.vault.tls.pkiIssuerPath field in your RabbitmqCluster specification.

  12. Understand RabbitmqCluster quorumStatus

    main

    The quorumStatus field in the RabbitmqCluster status provides real-time visibility into whether any node in the cluster is 'quorum critical'. A node is considered quorum critical if stopping it would cause quorum queues to lose their majority (quorum). This happens if the node hosts leader replicas for quorum queues and there aren't enough other nodes with synced replicas to maintain quorum.

    This field is used to determine if it is safe to restart or delete pods during maintenance. It complements the StatefulSet preStop hooks, which act as a local safety mechanism, while quorumStatus provides cluster-wide observability.