ARTEMIS-3042 simple properties based, extensible broker image

artemis-image/README.md

@@ -0,0 +1,93 @@
+###What is in the image
+
+An _empty_, _open_ broker with a default acceptor on port 61616
+
+ - by empty: has no addresses or queues but will auto create on demand
+ - by open: has no security; authentication or authorization, users or roles
+
+###How will the image behave
+
+ 1) the image will use or create `/app/data` for persistence of data
+
+ 2) the image will use any [.properties files](https://activemq.apache.org/components/artemis/documentation/latest/configuration-index.html#broker_properties) from `/app/etc` to augment configuration
+
+ 3) the image will use `/app/etc/broker.xml` if present, to bootstrap configuration, the 'bring your own config' use case
+
+###Build and Use
+
+First build an OCI image tar file from this artemis project using mvn:
+
+ `$> mvn install`
+
+An OCI image is created as a tar file, that tar can be loaded into a registry, eg:
+
+ `$> podman image load --input target/jib-image.tar`
+
+To run the image with host network access, localhost:61616 will be visible, use:
+
+ `$> podman run --net=host localhost/target/activemq-artemis-image:<...>`
+
+Execute the artemis producer/consumer command line tools from a `local distribution` to validate:
+Note: there is a `local distribution` in ../artemis-distribution/target/apache-artemis-<version>-bin/apache-artemis-<version>/
+
+ `$> ./bin/artemis producer --url tcp://127.0.0.1:61616`
+
+ `$> ./bin/artemis consumer --url tcp://127.0.0.1:61616`
+
+###Intent
+
+The intent is that this image is useful as is. If one can trust users, having no access control or limits can work fine.
+
+If not, then this image can be configured by mounting an `/app/etc` directory with property files that augment default configuration.
+This image could also be the base for a derived jib image, by simply adding more property files to the `src/main/resources` directory.
+
+###Examples
+
+####amqp_sasl_scram_test__etc
+In this example, you can run the image with configuration that locks the broker down to a single user on a single predefined
+queue called `TEST`. The necessary configuration overrides:
+ - restricting the acceptor to AMQP/SASL-SCRAM
+ - providing RBAC for queue TEST
+
+are in:`./examples/amqp_sasl_scram_test__etc/amqp_sasl_scram.properties`
+
+To exercise this example, you need to choose a password for the pre-configured user 'A'.
+With SASL_SCRAM the broker retains a salted representation of that value, but not the plain text value.
+
+Register your chosen password by creating `./examples/amqp_sasl_scram_test__etc/user` using mvn as follows:
+
+ `$> mvn exec:exec -Dexample.pwd=<some value>`
+
+To see the result, cat the generated user file to see the stored representation:
+
+ `$> cat ./examples/amqp_sasl_scram_test__etc/user`
+
+You can then mount the `./examples/amqp_sasl_scram_test__etc directory` as `/app/etc` for the container and initialize JAAS 
+via the `java.security.auth.login.config` system property, which is passed to the JVM via the ENV `JDK_JAVA_OPTIONS` as follows:
+
+ `$> podman run --env  JDK_JAVA_OPTIONS=-Djava.security.auth.login.config=/app/etc/login.config --net=host --privileged -v ./examples/amqp_sasl_scram_test__etc:/app/etc localhost/target/activemq-artemis-image:<version>`
+
+Execute the artemis producer/consumer command line tools to validate secure access to the TEST queue using AMQP
+SASL-SCRAM with your chosen password via:
+
+ `$> ./bin/artemis producer --protocol amqp --url amqp://127.0.0.1:61616 --user A --password <some value>`
+
+ `$> ./bin/artemis consumer --protocol amqp --url amqp://127.0.0.1:61616 --user A --password <some value>`
+
+####byoc__etc
+This is an example of "Bring Your Own Config" or BYOC. The image will look for `/app/etc/broker.xml`. If that file exists
+it will be treated as the broker xml configuration for the embedded broker. If your existing configuration is nicely
+locked down or if you want to provide some custom defaults for your image, referencing an existing broker.xml makes sense.
+Property files can still be used to augment the defaults or be used solely for more dynamic parts of configuration.
+
+To exercise the example, `./examples/byoc__etc directory` as `/app/etc` for the container as follows:
+
+ `$> podman run --net=host --privileged -v ./examples/byoc__etc:/app/etc localhost/target/activemq-artemis-image:<version>`
+
+Note the broker name 'byoc' configured form the broker.xml config
+Execute the artemis producer/consumer command line tools to validate, it behaves like the bare image:
+
+ `$> ./bin/artemis producer --url tcp://127.0.0.1:61616`
+
+ `$> ./bin/artemis consumer --url tcp://127.0.0.1:61616`
+

artemis-image/TODO.md

@@ -0,0 +1,7 @@
+TODO:
+ - replace @classpath_file with cp from libs/*.jar directory - more extensible for folks that want extra jars/plugins in derived images
+   - or figure out a mount point for extra jars
+ - currently running as root!
+   - maybe we need a base image with an 'app' or 'java' user preconfigured with rw permissions on /app
+   - or do that in a launch.sh
+     - this is a known and reasonable limitation of jib https://github.com/GoogleContainerTools/jib/issues/1029

artemis-image/examples/amqp_sasl_scram_test__etc/amqp_sasl_scram.properties

@@ -0,0 +1,44 @@
+## ---------------------------------------------------------------------------
+## Licensed to the Apache Software Foundation (ASF) under one or more
+## contributor license agreements.  See the NOTICE file distributed with
+## this work for additional information regarding copyright ownership.
+## The ASF licenses this file to You under the Apache License, Version 2.0
+## (the "License"); you may not use this file except in compliance with
+## the License.  You may obtain a copy of the License at
+##
+## http://www.apache.org/licenses/LICENSE-2.0
+##
+## Unless required by applicable law or agreed to in writing, software
+## distributed under the License is distributed on an "AS IS" BASIS,
+## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+## See the License for the specific language governing permissions and
+## limitations under the License.
+## ---------------------------------------------------------------------------
+
+## reset to default
+securityEnabled=true
+
+## reference user role files with login.config, -Djava.security.auth.login.config=jaas/login.config
+## the broker JAAS domain in login.config
+acceptorConfigurations.tcp.params.securityDomain=broker
+
+## lock down broker acceptor
+## to SCRAM AMQP
+acceptorConfigurations.tcp.params.saslMechanisms=SCRAM-SHA-512
+acceptorConfigurations.tcp.params.protocols=AMQP
+acceptorConfigurations.tcp.params.saslLoginConfigScope=amqp-sasl-scram
+
+## if over TLS, configure acceptor key and trust store
+# acceptorConfigurations.tcp.params.sslEnabled=true
+# acceptorConfigurations.tcp.params.keyStorePath=/app/etc/<keystore>.keystore
+# acceptorConfigurations.tcp.params.keyStorePassword=<password>
+
+
+## create TEST address and ANYCAST queue b/c we won't have createX permissions
+## TEST is the default queue for ./bin/artemis producer
+addressConfigurations.TEST.queueConfigs.TEST.routingType=ANYCAST
+
+## grant users role read/write
+securityRoles.TEST.users.send=true
+securityRoles.TEST.users.consume=true
+

artemis-image/examples/amqp_sasl_scram_test__etc/login.config

@@ -0,0 +1,26 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+amqp-sasl-scram {
+   org.apache.activemq.artemis.spi.core.security.jaas.SCRAMPropertiesLoginModule required
+   ;
+};
+
+broker {
+    org.apache.activemq.artemis.spi.core.security.jaas.SCRAMLoginModule required
+    ;
+};

artemis-image/examples/amqp_sasl_scram_test__etc/role

@@ -0,0 +1,18 @@
+## ---------------------------------------------------------------------------
+## Licensed to the Apache Software Foundation (ASF) under one or more
+## contributor license agreements.  See the NOTICE file distributed with
+## this work for additional information regarding copyright ownership.
+## The ASF licenses this file to You under the Apache License, Version 2.0
+## (the "License"); you may not use this file except in compliance with
+## the License.  You may obtain a copy of the License at
+##
+## http://www.apache.org/licenses/LICENSE-2.0
+##
+## Unless required by applicable law or agreed to in writing, software
+## distributed under the License is distributed on an "AS IS" BASIS,
+## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+## See the License for the specific language governing permissions and
+## limitations under the License.
+## ---------------------------------------------------------------------------
+
+users=A

artemis-image/examples/byoc__etc/broker.xml

@@ -0,0 +1,46 @@
+<?xml version='1.0'?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+<configuration
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xmlns="urn:activemq"
+        xsi:schemaLocation="urn:activemq:core schema/artemis-configuration.xsd">
+   <core xmlns="urn:activemq:core">
+
+      <!--
+       Configure an image in the traditional way.
+       Providing boilerplate xml can form the well known configuration for an organisational base image that can be further extended with properties
+      -->
+
+      <!-- set an example specific name, it appears in the started/stopped logging messages -->
+      <name>byoc</name>
+      <security-enabled>false</security-enabled>
+
+      <!-- broker properties in the image are still in play so there will be an acceptor
+         configured from src/main/resources/acceptors.properties -->
+
+      <addresses>
+         <address name="TEST">
+            <anycast>
+               <queue name="TEST"/>
+            </anycast>
+         </address>
+      </addresses>
+   </core>
+</configuration>

artemis-image/pom.xml

@@ -0,0 +1,127 @@
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one or more
+  ~ contributor license agreements. See the NOTICE file distributed with
+  ~ this work for additional information regarding copyright ownership.
+  ~ The ASF licenses this file to You under the Apache License, Version 2.0
+  ~ (the "License"); you may not use this file except in compliance with
+  ~ the License. You may obtain a copy of the License at
+  ~
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+   <modelVersion>4.0.0</modelVersion>
+
+   <parent>
+      <groupId>org.apache.activemq</groupId>
+      <artifactId>artemis-pom</artifactId>
+      <version>2.28.0-SNAPSHOT</version>
+   </parent>
+
+   <artifactId>artemis-image</artifactId>
+   <name>Apache ActiveMQ Artemis Image</name>
+
+   <properties>
+      <!-- for checkstyle plugin -->
+      <activemq.basedir>${project.basedir}/..</activemq.basedir>
+      <!-- none of the surefire project defaults are relevant to the tests here -->
+      <activemq-surefire-argline></activemq-surefire-argline>
+
+
+      <!-- for the locked down examples/amqp_sasl_scram_test__etc -->
+      <!-- user A is referenced in the role file, so don't just change it here -->
+      <example.user>A</example.user>
+      <!-- a password must be provided to generate the user credential data.
+         use: mvn exec:exec -Dexample.pwd=xyz on the command line to register your value in the example.user.file -->
+      <example.pwd></example.pwd>
+      <example.user.file>examples/amqp_sasl_scram_test__etc/user</example.user.file>
+   </properties>
+
+
+   <dependencies>
+      <dependency>
+         <groupId>org.apache.activemq</groupId>
+         <artifactId>apache-artemis</artifactId>
+         <version>${project.version}</version>
+         <type>pom</type>
+      </dependency>
+      <dependency>
+         <groupId>junit</groupId>
+         <artifactId>junit</artifactId>
+         <version>${junit.version}</version>
+         <scope>test</scope>
+      </dependency>
+      <!-- The johnzon-core and json-api contents are repackaged in -commons,
+           However maven can still need them during tests that don't see the shaded bits during build -->
+      <dependency>
+         <groupId>org.apache.johnzon</groupId>
+         <artifactId>johnzon-core</artifactId>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>jakarta.json</groupId>
+         <artifactId>jakarta.json-api</artifactId>
+         <scope>test</scope>
+      </dependency>
+   </dependencies>
+
+   <build>
+      <plugins>
+         <plugin>
+            <groupId>com.google.cloud.tools</groupId>
+            <artifactId>jib-maven-plugin</artifactId>
+            <version>3.3.0</version>
+            <configuration>
+               <from>
+                  <!-- reproducible build and single pull with @sha reference -->
+                  <image>eclipse-temurin:19-jre@sha256:619e1c33be065f75eb00b0999627b7b1e070f55c427e63dfd256f06d00935111</image>
+               </from>
+               <to>
+                  <image>target/activemq-artemis-image:${project.version}</image>
+               </to>
+               <container>
+                  <mainClass>org.apache.activemq.artemis.ActiveMQImageMain</mainClass>
+                  <ports>
+                     <port>61616</port>
+                  </ports>
+                  <format>OCI</format>
+               </container>
+            </configuration>
+            <executions>
+               <execution>
+                  <phase>package</phase>
+                  <goals>
+                     <goal>buildTar</goal>
+                  </goals>
+               </execution>
+            </executions>
+         </plugin>
+
+         <!-- to easily create a single salted credential for our ${example.user.file}-->
+         <plugin>
+            <groupId>org.codehaus.mojo</groupId>
+            <artifactId>exec-maven-plugin</artifactId>
+            <version>${exec-maven-plugin.version}</version>
+            <configuration>
+               <executable>java</executable>
+               <arguments>
+                  <argument>-classpath</argument>
+                  <classpath/>
+                  <argument>org.apache.activemq.artemis.spi.core.security.jaas.SCRAMPropertiesLoginModule</argument>
+                  <argument>${example.user}</argument>
+                  <argument>${example.pwd}</argument>
+               </arguments>
+               <outputFile>${example.user.file}</outputFile>
+            </configuration>
+         </plugin>
+      </plugins>
+   </build>
+
+</project>