> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Artemis

> Deploy Apache Artemis on Control Plane using the Template Catalog. A JMS, AMQP 1.0, MQTT, STOMP and OpenWire message broker as one broker, a primary and backup pair in one location, or a mirrored pair across two locations. Needs an existing GVC and a credentials secret.

## 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).

> [!NOTE]
>
> **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

| Resource | Name | Purpose | Optional |
| - | - | - | - |
| Workload | `RELEASE_NAME-artemis` | Artemis broker on the official `apache/artemis` image (stateful, one broker per listed location; two brokers with `ha.enabled`) | — |
| Volume Set | `RELEASE_NAME-artemis-vs` | Broker configuration and message journal at `/var/lib/artemis-instance`, with daily snapshots (a shared volume with no snapshots when `ha.enabled`) | — |
| Identity | `RELEASE_NAME-artemis-identity` | Identity bound to the workload | — |
| Policy | `RELEASE_NAME-artemis-policy` | Grants the identity `reveal` on exactly your credentials secret | — |
| Policy | `RELEASE_NAME-artemis-gvc-policy` | Grants `view` on the install GVC so each broker can check at start that its peer's location exists | Two locations |

## Prerequisites

**1. Create the credentials secret**

A [dictionary secret](https://docs.controlplane.com/guides/create-secret/dictionary.md) 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):

```bash theme={null}
cpln secret create-dictionary --name SECRET_NAME \
  --entry username=admin \
  --entry password="$(openssl rand -hex 24)"
```

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`.

> [!WARNING]
>
> **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`:
>
> ```bash theme={null}
> cpln workload get-deployments RELEASE_NAME-artemis --gvc GVC_NAME -o yaml
> ```
>
> Once the secret exists, force a redeployment:
>
> ```bash theme={null}
> cpln workload force-redeployment RELEASE_NAME-artemis --gvc GVC_NAME
> ```

## Installation

Install with the credentials secret and your GVC's location. For two locations, add `--set 'locations[1].name=SECOND_LOCATION'`.

```bash theme={null}
cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/artemis \
  --version 1.0.0 --gvc GVC_NAME \
  --set credentialsSecretName=SECRET_NAME \
  --set 'locations[0].name=LOCATION'
```

To install using another method, follow the instructions for it:

> [card] [UI](https://docs.controlplane.com/template-catalog/install-manage/ui.md)
>
> Browse, install, and manage templates visually

> [card] [CLI](https://docs.controlplane.com/template-catalog/install-manage/cli.md)
>
> Manage templates from your terminal

> [card] [Terraform](https://docs.controlplane.com/template-catalog/install-manage/terraform.md)
>
> Declare templates in your Terraform configurations

> [card] [Pulumi](https://docs.controlplane.com/template-catalog/install-manage/pulumi.md)
>
> Declare templates in your Pulumi programs

## Configuration

### Locations

```yaml theme={null}
# REQUIRED — list the location(s) of the GVC you install into (this chart never creates a GVC).
# One entry: one broker. Two entries: one broker per location, kept in sync by a two-way
# AMQP mirror. More than two is refused: mirroring more than two brokers duplicates messages.
# The GVC's other locations run nothing.
# A listed location the GVC does not have runs nothing — replace the example below.
locations:
  - name: aws-us-east-1
#  - name: aws-us-west-2   # add a second location for a broker that survives a region loss
```

### Credentials

```yaml theme={null}
# REQUIRED PREREQUISITE SECRET — CREATE IT BEFORE YOU INSTALL.
credentialsSecretName: my-artemis-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.

```yaml theme={null}
ha:
  enabled: false  # true: a primary and a backup broker in your ONE location share a volume; the backup takes over in seconds
                  # choose at install: changing it later is not supported, and messages do not carry over to a new release
```

### Mirror

Applies to two locations only.

```yaml theme={null}
# Two locations only (ignored with one):
mirror:
  mode: active-passive        # active-passive: the primary serves clients, the other location takes over when it is down
                              # active-active: both locations serve clients (consume each queue in one location only)
  primary: ""                 # active-passive: the location that serves clients; "" = the first entry in `locations`
  takeoverSeconds: 60         # active-passive: how long the primary broker must be unreachable before the other location opens
  catchUpTimeoutSeconds: 180  # a restarted broker opens client ports once caught up from its peer, or after this long
```

### Image and Resources

```yaml theme={null}
image: apache/artemis:2.57.0  # official image; runs as uid 1001

resources:
  cpu: 1000m
  memory: 2Gi  # Mi or Gi, at least 1Gi; the JVM heap is half of this
```

### Storage

```yaml theme={null}
volumeset:
  capacity: 10  # GiB per broker (minimum 10); with ha.enabled one shared volume holds both brokers' data
  snapshots:                # not taken with ha.enabled (shared volumes have no snapshots)
    schedule: "0 3 * * *"   # daily at 3am UTC; at most hourly; "" turns them off
    retentionDuration: 7d   # how long each snapshot is kept
  autoscaling:
    enabled: false          # grows the volume — useful if a location can be down for long
    maxCapacity: 100        # GiB
    minFreePercentage: 10
    scalingFactor: 1.2
```

### Network Access

```yaml theme={null}
internalAccess:
  type: same-gvc  # options: same-gvc, same-org, workload-list
  workloads: []   # for workload-list: //gvc/GVC_NAME/workload/NAME — this release's broker is added automatically

publicAccess:
  enabled: false  # true publishes the web console (8161) over HTTPS; message ports always stay internal
```

## 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.

| What | Address | Notes |
| - | - | - |
| All protocols (Core, AMQP, OpenWire, STOMP, MQTT) | `RELEASE_NAME-artemis.GVC_NAME.cpln.local:61616` | Reaches the broker in the client's own location |
| AMQP 1.0 | `RELEASE_NAME-artemis.GVC_NAME.cpln.local:5672` | |
| STOMP | `RELEASE_NAME-artemis.GVC_NAME.cpln.local:61613` | |
| MQTT | `RELEASE_NAME-artemis.GVC_NAME.cpln.local:1883` | |
| One location's broker | `replica-0.RELEASE_NAME-artemis.LOCATION.GVC_NAME.cpln.local:61616` | Use in failover URLs |
| Web console (private) | `http://localhost:8161/console` | After the port-forward below |
| Web console (public) | `status.canonicalEndpoint` | From `cpln workload get RELEASE_NAME-artemis --gvc GVC_NAME -o yaml`; needs `publicAccess.enabled: true` |

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:

```bash theme={null}
cpln port-forward RELEASE_NAME-artemis 8161:8161 --gvc GVC_NAME
```

### 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:

  ```text theme={null}
  failover:(amqp://replica-0.RELEASE_NAME-artemis.LOCATION_A.GVC_NAME.cpln.local:61616,amqp://replica-0.RELEASE_NAME-artemis.LOCATION_B.GVC_NAME.cpln.local:61616)?failover.maxReconnectAttempts=-1&failover.nested.amqp.idleTimeout=10000
  ```

* **OpenWire** (ActiveMQ clients) uses the same shape; add `randomize=false`, or the client picks a broker at random:

  ```text theme={null}
  failover:(tcp://replica-0.RELEASE_NAME-artemis.LOCATION_A.GVC_NAME.cpln.local:61616,tcp://replica-0.RELEASE_NAME-artemis.LOCATION_B.GVC_NAME.cpln.local:61616)?randomize=false
  ```

* **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`):

```text theme={null}
failover:(amqp://replica-0.RELEASE_NAME-artemis.LOCATION.GVC_NAME.cpln.local:61616,amqp://replica-1.RELEASE_NAME-artemis.LOCATION.GVC_NAME.cpln.local:61616)?failover.maxReconnectAttempts=-1
failover:(tcp://replica-0.RELEASE_NAME-artemis.LOCATION.GVC_NAME.cpln.local:61616,tcp://replica-1.RELEASE_NAME-artemis.LOCATION.GVC_NAME.cpln.local:61616)?randomize=false
```

## Operations

### Choosing a Mirror Mode

| | `active-passive` (default) | `active-active` |
| - | - | - |
| Serves clients | The primary; the other location only while the primary is down | Both locations |
| Typical use | Disaster recovery: a standby copy in a second region | Producers writing near them in both regions |
| Consuming a queue | One location at a time, enforced by the brokers | One location at a time, enforced by your clients: consuming one queue in both locations at once delivers messages twice |
| Client setup | Failover URL, primary first | Failover URL, or per-location queues (`orders.east` / `orders.west`) |

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:

   ```bash theme={null}
   cpln volumeset volume delete RELEASE_NAME-artemis-vs --location LOCATION --volume-index 0 --gvc GVC_NAME
   ```

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:

  ```bash theme={null}
  cpln port-forward RELEASE_NAME-artemis 8161:8161 --replica RELEASE_NAME-artemis-0 --gvc GVC_NAME
  ```

  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:

  ```bash theme={null}
  cpln volumeset expand RELEASE_NAME-artemis-vs --gvc GVC_NAME --new-size NEW_SIZE_GIB --location LOCATION --volume-index 0
  ```

* **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

> [accordion] 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](#prerequisites).

> [accordion] Deployment message reads maxScale is set to 0
>
> A location in `locations` is not a location of your GVC. Correct the list and upgrade.

> [accordion] 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`.

> [accordion] 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.

> [accordion] 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_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

> [card] [Apache Artemis Documentation](https://artemis.apache.org/components/artemis/documentation/latest/)
>
> Official Artemis documentation

> [card] [Broker Connections and Mirroring](https://artemis.apache.org/components/artemis/documentation/latest/amqp-broker-connections.html)
>
> How the two-way AMQP mirror works

> [card] [Configuration Index](https://artemis.apache.org/components/artemis/documentation/latest/configuration-index.html)
>
> Every broker configuration setting

> [card] [Qpid JMS Failover](https://qpid.apache.org/releases/qpid-jms-2.7.0/docs/index.html#failover-configuration-options)
>
> Failover URL options for AMQP clients

> [card] [Artemis Template](https://github.com/controlplane-com/templates/tree/main/artemis)
>
> View the source files, default values, and chart definition
