Configuring Load Balancer Service Annotations

Considerations for Using Load Balancer Service Annotations

Be aware of the following considerations when using load balancer service annotations:

• Annotation changes are applied to the Kubernetes load balancer service objects without restarting the pods hosting the event broker service.

• Some load balancer annotation changes, such as IP address reassignments, may cause a brief connectivity interruption while the load balancer controller reconciles the change. This is expected behavior.

• You should always use Cluster Manager or the Solace Cloud APIs to manage load balancer service annotations. If you modify load balancer service annotations directly using kubectl or other tools, your changes will be overwritten on the next event broker service reconciliation.

• When you clone an event broker service, the load balancer service-level annotations are not copied to the new event broker service. This prevents IP address conflicts when cloning an event broker service with IP-pinning annotations.

• Service-level annotations are preserved when you upgrade or upscale your event broker service.

Merging Annotations

When you configure event broker service-level annotations, they are merged with any datacenter-level defaults at reconciliation time, such as during an event broker service upgrade. The merge follows these rules:

• Event broker service-level annotations override datacenter-level defaults when the same key exists in both.

• Datacenter-level annotations are inherited for any keys not specified at the event broker service-level.

• If you remove an event broker service-level annotation, the datacenter default for that key is restored on the next reconciliation.

• An empty string is a valid event broker service-level value and explicitly overrides the datacenter default for that key.

The following table shows how annotations are resolved in different scenarios:

Event broker services do not pick up datacenter-level annotation changes automatically. Event broker services only apply datacenter-level annotation changes on their next reconciliation, such as when you upgrade the event broker service.

Adding Load Balancer Service Annotations When Creating an Event Broker Service

You can configure Kubernetes load balancer service annotations when you create an event broker service in a Customer-Controlled Cluster. To add load balancer service annotations during event broker service creation, perform these steps:

1. When you create your event broker service, expand Advanced Connection Options.

2. In the Service Annotations section, any current datacenter-level defaults are shown in the Inherited from datacenter sections as read-only reference labels. Note that your current selection in the Port Configuration section affects the scope of annotations you see in the Service Annotations section:

   • Private: Private load balancer annotations are visible

   • Public Internet: Public load balancer annotations are visible.

   • Hybrid: Private Address and Public Internet: Both load balancer annotation types are visible.

3. Under Your annotations, in the annotation type (private or public) you want to add an annotation to, click Add Annotation to open an annotation/key and value field.

4. Complete the annotation/key and value fields with applicable values for your load balancer. For more information, see Common Annotation Keys by Distribution.

5. Repeat for each annotation you want to add.

6. Click Create Service.

Editing Service Annotations for an Existing Event Broker Service

You can add, modify, or remove load balancer service annotations for an existing event broker service in a Customer-Controlled Cluster. The Cloud Console validates annotations you add to an existing event broker service and provides feedback about any errors or warnings before changes are applied. To edit service annotations, perform these steps:

1. Log in to the Solace Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your authentication scheme. For more information, see Logging In to the Solace Cloud Console.
2. On the navigation bar, select Cluster Manager .
3. Select the event broker service that you want to configure. If the event broker service is not listed, make sure you have the right environment selected. For more information, see Selecting Environments.
4. On the Service Details page, click the Manage tab.
5. On the Management Settings menu, select Network Access.
6. On the Service Annotations card, click Edit.
7. In the Edit service annotations dialog, the current datacenter-level defaults are shown as read-only reference labels under the scope (public/private) they apply to. You can:
   • Click Add Annotation to add a new annotation to the Private or Public scope.
   • Edit the key or value of an existing annotation.
   • Click Delete to remove an annotation. Removing a service-level annotation restores the datacenter default for that key.
8. Click Apply changes to check your annotation changes against your cluster.

   The validation results are displayed inline. If there are errors, you must correct them before you can apply the changes. Warnings are informational and do not block the apply operation.

9. If validation fails, correct any validation errors and click Apply changes again to save your changes.

Annotation changes are applied without restarting the event broker service. However, some annotation changes, such as load balancer IP reassignments, may cause a brief interruption at the load balancer level while the controller reconciles the change.

Understanding Load Balancer Annotation Validation

The Cloud Console validates service annotations you add to event broker services. During event broker service creation, any service annotation errors block event broker service creation. Annotations added when editing an existing event broker service are validated and the console allows you to correct mistakes before applying them.

• Annotation keys must follow Kubernetes naming rules. Keys using the reserved prefixes kubernetes.io/ or k8s.io/ are rejected.

• Values must be valid UTF-8 strings without control characters.

• You can configure a maximum of 50 annotations per section (private or public), with a combined size limit of 256 KB.

• The same key with the same value in both private and public sections is rejected as redundant.

• Solace Cloud validates your annotations against your actual cluster using a dry-run operation. This catches errors that would be rejected by your cluster's admission webhooks, such as invalid load balancer pool names or IP address conflicts.

Validation Results

Validation returns errors or warnings:

• Errors block the apply operation (create service or apply edits). You must correct the issue before you can save your changes.

• Warnings are informational and allow you to proceed. For example, a warning is returned if you use the same key with different values in the private and public sections (which may be intentional).

Common Validation Errors

The following table describes common validation errors and how to resolve them:

Common Annotation Keys by Distribution

The annotations available for your cluster depend on your load balancer controller and its configuration. Consult your load balancer controller documentation for a complete list of supported annotations.

The following table lists commonly used Kubernetes load balancer service annotations for each supported distribution. This is a reference only; the annotation editor accepts any valid annotation key. You are responsible for using the correct annotations for your cluster's load balancer controller.