Skip to main content

Overview

Apache Artemis, the successor to ActiveMQ Classic, is an open-source (Apache 2.0) message broker for JMS, AMQP 1.0, MQTT, STOMP and OpenWire clients. This template runs it in one of three shapes: a single broker in one location, a primary and a backup broker sharing a volume in one location (ha.enabled), or one broker in each of two locations kept in sync by a two-way asynchronous mirror, either active-passive (one location serves clients and the other takes over when it is down) or active-active (both serve clients).
This template does not create a GVC. It deploys into a GVC you already have, in the locations you list in locations. With two locations, both must already be locations of that GVC. A listed location the GVC does not have simply starts nothing.

What Gets Created

Prerequisites

1

Create the credentials secret

A dictionary secret with the broker’s admin login. It is the web console login, the login your clients use and, with two locations, the login the mirror uses between them. Use a hex password (no spaces, quotes or backslashes):
Set credentialsSecretName to this name. Read the login back with cpln secret reveal SECRET_NAME -o yaml.
2

Know your GVC's locations

Set locations to the location or locations your GVC already has. The chart default aws-us-east-1 is a placeholder; if your GVC lacks it, nothing runs and the deployment message reads maxScale is set to 0.
Create the secret before installing. A name pointing at a secret that does not exist installs “successfully” and then wedges silently: the workload never starts and cpln logs is empty. The only place the missing secret is named is status.versions[].message:
Once the secret exists, force a redeployment:

Installation

Install with the credentials secret and your GVC’s location. For two locations, add --set 'locations[1].name=SECOND_LOCATION'.
To install using another method, follow the instructions for it:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Locations

Credentials

High Availability

One location only. Refused with two locations and with publicAccess.enabled. Choose it at install; it cannot be switched on or off for an existing release.

Mirror

Applies to two locations only.

Image and Resources

Storage

Network Access

Connecting

Log in with the username and password from your credentials secret (cpln secret reveal SECRET_NAME -o yaml). LOCATION is one of your listed locations. The message ports are reachable only from inside Control Plane, as internalAccess allows; they are never public. Port 61617 carries the mirror between locations; do not point clients at it. To check the broker is serving, tunnel to the console and log in:

Client Failover

With two locations, give every client both brokers in a failover URL, primary first in active-passive mode. The client connects to the first broker that accepts it and moves when that broker goes away or closes its client ports.
  • AMQP 1.0 / JMS with qpid-jms tries the brokers in the order listed:
  • OpenWire (ActiveMQ clients) uses the same shape; add randomize=false, or the client picks a broker at random:
  • Core clients: a (tcp://a,tcp://b) connection list does not move a live connection to the other broker; reconnect in your application.
  • The plain name does not fail over. RELEASE_NAME-artemis.GVC_NAME.cpln.local reaches the broker in the client’s own location and does not move to the other location while that broker is down or, in active-passive mode, standing by. Clients that must keep working through a location outage use a failover URL, or you point them at the other location’s broker.
  • Delivery is at least once: consumers that move on failover must tolerate a redelivered message.
With ha.enabled, list the two brokers of your one location instead (replica-0 and replica-1):

Operations

Choosing a Mirror Mode

In either mode each broker copies every message, acknowledgement and queue creation or deletion to the other, and consumers must be idempotent. The mirror is asynchronous: a broker that crashes can lose the messages it had not yet copied to its peer, and only if its volume is lost too. More than two locations, synchronous mirroring and a retained, replayable log are not offered (use the kafka template for a log).

Takeover and Failback

In active-passive mode, when the primary broker has been unreachable for mirror.takeoverSeconds, the other broker opens its client ports and failover clients move to it. A primary that restarts within that time is not taken over, and neither is a primary that is up but still catching up. When the primary returns, it catches up from the other broker and opens, and the other broker closes again, which moves clients back. Messages the primary had not yet copied when it went down are delivered after it returns. If the link between the locations breaks while both brokers are up, the other broker also opens after the takeover delay and both serve clients until the link is back. A restarted broker refuses clients until it has caught up from its peer, or until mirror.catchUpTimeoutSeconds has passed.

Losing a Location for Good

During an outage there is nothing to do: the other broker takes over and failback is automatic when the location returns. If the location will not return:
  1. Run on the surviving location alone: helm upgrade with only that location in locations. Its broker restarts as a single broker with every mirrored message.
  2. Before adding a location back, delete its old volume, or the returning broker starts on out-of-date messages that the mirror never reconciles. Delete it, then wait until cpln volumeset get RELEASE_NAME-artemis-vs --gvc GVC_NAME -o yaml shows no storageDeviceId for that location:
  3. Add the location back with mirror.primary set to the surviving location. The returning broker starts empty as the standby and receives every message sent from then on; messages already on the surviving broker stay only there until they are consumed.
A returning location made the primary instead also starts empty: it keeps its client ports closed (HOLDING in its log) while the other broker holds messages it lacks, the other broker serves clients after takeoverSeconds plus catchUpTimeoutSeconds, and the primary opens by itself once those messages are consumed. Adding a second location to a running single-broker release does not copy existing messages; only messages sent after the upgrade are mirrored. In active-passive mode, make the installed location the primary.

Scaling and Availability

  • One location with ha.enabled: true: replica-0 (primary) and replica-1 (backup) share one volume holding the journal, bindings, paging and large messages. The broker holding the lock serves clients; the other waits and takes over within seconds when the active broker stops. AMQP and OpenWire failover clients follow a takeover; Core-protocol clients do not. A message in flight during a takeover can be delivered again.
  • Send speed: with ha.enabled, every persistent write is synced to a shared network filesystem, so persistent sends are slower than to a single broker.
  • Web console with ha.enabled: it stays private, because the two brokers keep separate logins. Port-forward to the active broker:
    Use RELEASE_NAME-artemis-1 when that broker is the active one. The roles swap at every takeover; the active one is the replica on the newest line of cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-artemis"} |~ "AMQ221007|AMQ221010"' --since 24h (log lines arrive a few minutes late). The waiting backup’s console shows no queues, and a waiting primary has no console.
  • Growing a volume: changing volumeset.capacity does not resize an existing volume. Grow a live volume with:
  • Long outages: while one location is down, the other broker keeps every message to copy to it, so its volume grows with traffic. Consider volumeset.autoscaling.

Troubleshooting

The credentials secret does not exist. Create it, then run cpln workload force-redeployment RELEASE_NAME-artemis --gvc GVC_NAME. See the warning under Prerequisites.
A location in locations is not a location of your GVC. Correct the list and upgrade.
With two locations, a new broker checks that its peer’s location exists in the GVC and stops if it does not. Add the location to the GVC or fix the name in locations.
The replica you forwarded to is the waiting primary, which has no console. Forward to the other replica.
A message sent to an address with no queue is dropped. Clients that send to a queue name create it automatically; when you create an address in the console, also create its queue before sending to it.

Important Notes

  • Create the credentials secret first. If the deployment already wedged, run cpln workload force-redeployment RELEASE_NAME-artemis --gvc GVC_NAME after creating it.
  • Choose ha.enabled at install. A volume set’s type cannot change in place, so turning it on or off for an existing release is not supported; install a new release instead. Messages on the old release do not carry over.
  • No more than two locations. Mirroring more than two brokers duplicates messages.
  • Consume each queue in one location at a time in active-active mode, and make consumers idempotent in both modes.
  • An upgrade that changes the workload restarts the brokers in every location at the same time, so clients are refused until they are back. With ha.enabled the two brokers restart one at a time instead.
  • Rotating the secret: the brokers apply it on every start, so run cpln workload force-redeployment RELEASE_NAME-artemis --gvc GVC_NAME after changing it. Rotate the password and keep the username; a new username adds a second admin and the old one keeps working.
  • A message sent to an address with no queue is dropped.
  • Changes to internalAccess and publicAccess take a few minutes to apply and restart the brokers.

External References

Apache Artemis Documentation

Official Artemis documentation

Broker Connections and Mirroring

How the two-way AMQP mirror works

Configuration Index

Every broker configuration setting

Qpid JMS Failover

Failover URL options for AMQP clients

Artemis Template

View the source files, default values, and chart definition