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.Installation
Install with the credentials secret and your GVC’s location. For two locations, add--set 'locations[1].name=SECOND_LOCATION'.
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 withpublicAccess.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 theusername 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.localreaches 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.
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 formirror.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:-
Run on the surviving location alone:
helm upgradewith only that location inlocations. Its broker restarts as a single broker with every mirrored message. -
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 yamlshows nostorageDeviceIdfor that location: -
Add the location back with
mirror.primaryset 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.
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) andreplica-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:UseRELEASE_NAME-artemis-1when that broker is the active one. The roles swap at every takeover; the active one is the replica on the newest line ofcpln 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.capacitydoes 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
Workload never starts and cpln logs is empty
Workload never starts and cpln logs is empty
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.Deployment message reads maxScale is set to 0
Deployment message reads maxScale is set to 0
A location in
locations is not a location of your GVC. Correct the list and upgrade.FATAL - the mirror peer's location is not in GVC
FATAL - the mirror peer's location is not in GVC
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.Console tunnel returns 502 with ha.enabled
Console tunnel returns 502 with ha.enabled
The replica you forwarded to is the waiting primary, which has no console. Forward to the other replica.
Messages sent from the web console disappear
Messages sent from the web console disappear
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_NAMEafter creating it. - Choose
ha.enabledat 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.enabledthe 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_NAMEafter 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
internalAccessandpublicAccesstake 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