HAWKULAR-1280: update the agent's docker/openshift configuration

.gitignore

@@ -25,3 +25,6 @@ nb-configuration.xml
 
 # MacOS DS_Store
 .DS_Store
+
+# Swap files
+*.swp

docker-dist/Dockerfile

@@ -20,26 +20,26 @@ FROM jboss/wildfly:10.1.0.Final
 MAINTAINER Hawkular project <[email protected]>
 
 # ADD test-simple.war /opt/jboss/wildfly/standalone/deployments/
-ADD target/hawkular-javaagent-wildfly-dist/bin/standalone.conf $JBOSS_HOME/bin
-ADD target/hawkular-javaagent-wildfly-dist/bin/hawkular-javaagent.jar $JBOSS_HOME/bin
-ADD target/hawkular-javaagent-wildfly-dist/standalone/configuration/hawkular-javaagent-config.yaml $JBOSS_HOME/standalone/configuration/
+COPY target/hawkular-javaagent.jar $JBOSS_HOME/bin/
+COPY target/hawkular-javaagent-config.yaml $JBOSS_HOME/standalone/configuration/
 
 ADD src/main/resources/run_hawkular_javaagent.sh /opt/hawkular/bin/run_hawkular_agent.sh
 
-ENV HAWKULAR_SERVER_PROTOCOL http
-ENV HAWKULAR_SERVER_ADDR hawkular
-ENV HAWKULAR_SERVER_PORT 8080
-ENV HAWKULAR_AGENT_USER=jdoe HAWKULAR_AGENT_PASSWORD=password
-ENV HAWKULAR_IMMUTABLE=true
-ENV JAVA_OPTS="-Xmx256m -Djava.net.preferIPv4Stack=true -Djava.awt.headless=true -XX:MaxMetaspaceSize=256m"
+ENV HAWKULAR_URL=http://hawkular:8080 \
+    HAWKULAR_AGENT_USER=jdoe \
+    HAWKULAR_AGENT_PASSWORD=password \
+    HAWKULAR_IMMUTABLE=true
 
 EXPOSE 8080 9090
 
 USER root
+RUN echo 'JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=org.jboss.byteman,org.jboss.logmanager -Djava.util.logging.manager=org.jboss.logmanager.LogManager -javaagent:$JBOSS_HOME/bin/hawkular-javaagent.jar=config=$JBOSS_HOME/standalone/configuration/hawkular-javaagent-config.yaml,delay=10"' >> $JBOSS_HOME/bin/standalone.conf
+
 RUN yum install --quiet -y openssl && \
     rm -rf /var/cache/yum && \
     chown -RH jboss:0 $JBOSS_HOME/standalone $JAVA_HOME/jre/lib/security/cacerts /opt/hawkular && \
-    chmod -R ug+rw $JBOSS_HOME/standalone $JAVA_HOME/jre/lib/security/cacerts /opt/hawkular
+    chmod -R ug+rw $JBOSS_HOME/standalone $JAVA_HOME/jre/lib/security/cacerts /opt/hawkular && \
+    chmod -R a+rw /opt/hawkular/
 
 USER jboss
 CMD /opt/hawkular/bin/run_hawkular_agent.sh

docker-dist/README.adoc

@@ -1,57 +1,99 @@
-= Docker
+= Containers: Docker, OpenShift & Kubernetes
 
-This builds a WF 10 server with an agent installed
+The following instructions outline how to build a docker image which contains Wildfly 10.1 with the Hawkular Javaagent installed as well as how to deploy in Docker and on OpenShift or Kubernetes.
 
-== Build
+== Building
 
-This command will build three docker images:
+The following command will build the docker images with default image "wildfly-hawkular-javaagent:latest"
 
-. `wildfly-hawkular-javaagent` - Hawkular Javaagent running along Wildfly in standalone mode.
-. `wildfly-hawkular-agent` - Wildfly 10 running with Hawkular Wildfly Agent subsystem in standalone mode.
-. `wildfly-hawkular-agent-domain` - Wildfly 10 running with Hawkular Wildfly Agent subsystem in domain mode.
+```bash
+build.sh
+```
+
+A parameter can also be used to pass a customized tag to the build. For instance, to build with the a tag of 'devel'
+
+```bash
+build.sh devel
+```
+
+The docker image name can also be customized with an additional parameter. To build with a tag of 'devel' and an image name of 'hawkular/wildfly-javaagent'
 
 ```bash
-sh do.sh
+build.sh devel hawkular/wildfly-javaagent
 ```
 
-== Run
+== Running in a docker image
+
+You will typically need three pieces of information when connecting to a remote Hawkular Services server: the URL for the Hawkular Services server, a username and a password.
 
-Select the type of Hawkular agent you would like to run, once you have a running Hawkular Services you can run it like:
+This information can be passed to the docker image via environment properties: 'HAWKULAR_URL', 'HAWKULAR_AGENT_USER', 'HAWKULAR_AGENT_PASSWORD'
+
+NOTE: For security reasons, it is recommend to only pass secret information such as usernames and passwords via an property file and not as normal parameters.
+
+Please see 'example-env-file' as an example of what this property file should look like.
+
+For example, if you were to make a copy of 'example-env-file' called 'hawkular-env-file' and edit its content to match your Hawkular Services server, you can deploy it using the following command:
 
 ```bash
-docker run -p 8081:8080 --link hawkular -e  {selected hawkular agent}
+docker run --env-file hawkular-env-file wildfly-hawkular-javaagent:latest
 ```
 
-It will connect to http://hawkular:8080 using username `jdoe` and password `password`.
+NOTE: if your Hawkular Services server is being accessed over https and is using untrusted https certificates, please see the 'Running with untrused certificates' section below.
+
+== Running in OpenShift and Kubernetes
 
-You can configure the endpoint, username and password passing the following environment variables.
+NOTE: the following instructions are listed using the OpenShift 'oc' command. If you are using Kubernetes you will need to replace the 'oc' command with 'kubectl'
 
+Like in the Docker example, we will need to pass the Hawkular Services URL, username and password to our pod. Unlike in the Docker example, for our pod will will pass this information as a secret.
 
-* HAWKULAR_SERVER_PROTOCOL defaults to `http`
-* HAWKULAR_SERVER_ADDR defaults to `hawkular`
-* HAWKULAR_SERVER_PORT defaults to `8080`
-* HAWKULAR_AGENT_USER defaults to `jdoe`
-* HAWKULAR_AGENT_PASSWORD defaults to `password`
+The process for this is similar to the Docker example. We will create a file which will contain properties 'HAWKULAR_URL', 'HAWKULAR_AGENT_USER', and 'HAWKULAR_AGENT_PASSWORD'.
+
+Please see the 'example-env-file' for an example.
+
+For example, if you were to make a copy of 'example-env-file' called 'hawkular-env-file' and edit its content to match your Hawkular Services server, you can create your secret using the following command:
 
-e.g.
 ```bash
-docker run -p 8081:8080 --link 2271bcd4adca:hawkular-services -e HAWKULAR_AGENT_PASSWORD=hard-to-guess -e HAWKULAR_SERVER_ADDR=hawkular-services wildfly-hawkular-javaagent
+oc create secret generic hawkular-javaagent-example --from-env-file=hawkular-env-file
 ```
 
-=== Connecting to a secured Hawkular Services
+Once you have create your secret, you can then deploy the 'hawkular-javaagent-example.yaml' deployment
+
+```bash
+oc create hawkular-javaagent-example.yaml
+```
+
+This should create a deployment in your current project with a single replica.
+
+NOTE: if your Hawkular Services server is being accessed over https and is using untrusted https certificates, please see the 'Running with untrused certificates' section below.
+
+== Running with untrused certificates (https)
+
+Running your Hawkular Services server with self signed or untrusted certificates will mean that the agent will not be able to trust and connect to the server.
+
+In order for the agent to trust this connection, you will need to pass the public certificate used to sign the Hawkular Services server. This file will need to be in a PEM format.
+
+If you wish to connect to your Hawkular Services server in this case, you will need to pass to the agent the public CA certificate used to sign the Hawkular Services's certificate.
+
+NOTE: You need to make sure that the domain name or IP stored in the certificate matches the `HAWKULAR_SERVER_ADDR` else it will be rejected when trying to connect.
+
+WARNING: This will add your custom certificate to the system wide Java cacerts. All Java applications running in your docker image will now trust applications which are signed with the CA.
+
+=== Untrusted Certificates and Docker
+
+If running in Docker, you will need to pass the public CA certificate as a volume when you are starting your container.
+
+For instance, if the public CA certificate used to sign the Hawkular Services server is located at /opt/hawkular/hawkular-services-public.pem then you will need to run the following command:
+
+```bash
+docker run --env-file hawkular-env-file -v /opt/hawkular/hawkular-services-public.pem:/client-secrets/hawkular-services-public.pem wildfly-hawkular-javaagent:latest
+```
 
-You might also use these docker instances to when connecting to a secured (https) Hawkular Services.
-You need to provide Hawkular Services public certificate in PEM format into `/client-secrets/hawkular-services-public.pem` of your docker Hawkular Agent
-and set `HAWKULAR_SERVER_PROTOCOL` to `https`.
+=== Untrusted Certificates and OpenShift/Kubernetes
 
-WARNING: You need to make sure that the domain name or IP stored in the certificate matches the `HAWKULAR_SERVER_ADDR`
-else it will be rejected when trying to connect.
+If running in OpenShift or Kubernetes you will need to pass to the pod a secret which contains the ca certificate.
 
-Below is a full example running Cassandra 3.0.9, Hawkular Services and wildfly-hawkular-javaagent.
+For instance, if the public CA certificate used to sign the Hawkular Services server is located at /opt/hawkular/hawkular-services-public.pem then you will need to run the following command before deploying your pod:
 
 ```bash
-mkdir $HOME/hawkular-certificates
-docker run --name hawkular-cassandra -e CASSANDRA_START_RPC=true -d cassandra:3.0.9
-docker run --name hawkular-services --link=hawkular-cassandra -e CASSANDRA_NODES=hawkular-cassandra -e HAWKULAR_HOSTNAME=hawkular-services -e HAWKULAR_USE_SSL=true -p 8443:8443 -v $HOME/hawkular-certificates:/client-secrets/ hawkular/hawkular-services
-docker run --name hawkular-agent-01 --link=hawkular-services -e HAWKULAR_SERVER_PROTOCOL=https -e HAWKULAR_SERVER_ADDR=hawkular-services -e HAWKULAR_SERVER_PORT=8443 -v $HOME/hawkular-certificates:/client-secrets/ wildfly-hawkular-javaagent
+oc create secret generic hawkular-javaagent-example-ca --from-file=hawkular-services-ca.crt=/opt/hawkular/hawkular-services-public.pem
 ```

docker-dist/do.sh → docker-dist/build.sh

@@ -19,15 +19,11 @@
 
 docker > /dev/null 2>&1 || { echo "docker is required, but is not found. Make sure it is accessible."; exit 1; }
 TAG="${1:-latest}"
+IMAGE="${2:-wildfly-hawkular-javaagent}"
 
 pushd "$( dirname "${BASH_SOURCE[0]}" )"
 
-echo "Building Docker image for Wildfly + Hawkular javaagent with tag $TAG."
-docker build -t wildfly-hawkular-javaagent:$TAG . -f Dockerfile
-
-echo "Building Docker image for Wildfly + Hawkular Wildfly Agent (Standalone) with tag $TAG."
-docker build -t wildfly-hawkular-agent:$TAG -f Dockerfile-wf-agent .
-echo "Building Docker image for Wildfly + Hawkular Wildfly Agent (Domain) with tag $TAG."
-docker build -t wildfly-hawkular-agent-domain:$TAG -f Dockerfile-wf-agent-domain .
+echo "Building Docker image for Wildfly + Hawkular javaagent: $IMAGE:$TAG."
+docker build -t $IMAGE:$TAG . -f Dockerfile
 
 popd