Merge pull request #113 from CoScale/feature/COD-12104

COD-12104: Add documentation for secrets and environment variables

HOWTO

@@ -35,4 +35,4 @@ Ex: `<a href="http://app.coscale.com" db-href="/alerts/manage/" class="js-dashbo
 
 {% endhighlight %}
 
-`xml` can be replaced with any language, full list available on http://rouge.jneen.net/
+`xml` can be replaced with any language, full list available on https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers

_docs_advanced/security.md

@@ -15,7 +15,7 @@ All data is stored in a cluster of PostgreSQL and Cassandra databases. Metric da
 
 ## Security & Firewall
 
-By default, all CoScale agents communicate with the CoScale platform over a secured SSL connection, using the default port 443. The agent communicates with one host, api.coscale.com (37.187.86.75). CoScale only requires your firewall to allow outgoing connections to api.coscale.com on TCP port 443. No incoming connections are required.
+By default, all CoScale agents communicate with the CoScale platform over a secured SSL connection, using the default port 443. The agent communicates with one host, api.coscale.com (46.105.51.99, 5.39.67.37, 178.33.227.57 and 176.31.230.12). CoScale only requires your firewall to allow outgoing connections to api.coscale.com on TCP port 443. No incoming connections are required.
 
 All installed agent plugins are digitally signed by CoScale. This signature is verified when installing or updating plugins.
 

_docs_agent/linux/environment-variables.md

@@ -1,15 +1,40 @@
 ---
 layout: page
-title: Environment variables configuration
+title: Using environment variables or secrets for configuration
 description: Configure the CoScale agent and plugins using environment variables.
 ---
 
-Our agent can get its configuration values for plugins from environment values configured on the server. This allows you to use the same agent for a lot of servers without having to generate a new agent for different configuration setups. An example where this might be used is with database plugin where the status user password isn't the same on all machines.
+## Option 1: Using docker Labels
+When creating your Docker image you can add a label to tell the CoScale agent how to monitor this image when it's detected. To make this work in an environment where sensitive data is stored in a secrets, you can tell the agent to read usernames and passwords from environment variables.
 
-{% include alert.html type="warning" text="At the moment we only support Linux." %}
+### Example 1
+In this example we have created an image with RabbitMQ running on it, we added a Docker label to automatically run the RabbitMQ plugin on the container once it starts. We tell the agent to get the password from an environment variable $RABBIT_MQ_PASSWORD by defining `$RABBIT_MQ_PASSWORD` in the Docker LABEL.
+
+{% highlight bash %}
+FROM rabbitmq:3.6
+
+RUN rabbitmq-plugins enable rabbitmq_management
+
+# Here we set USERNAME and PASSWWORD in the RabbitMQ configuration taken from environment variables
+LABEL com.coscale.monitoring='[{"PluginType":"RABBITMQ","Configuration":{"HOSTNAME":["localhost"],"PORT":["15672"],"USERNAME":["$RABBIT_MQ_USERNAME"],"PASSWORD":["$RABBIT_MQ_PASSWORD"]}}]'
+{% endhighlight %}
+
+### Example 2
+In this example we have created an image with RabbitMQ running on it, we added a Docker label to automatically run the RabbitMQ plugin on the container once it starts. We tell the agent to get the password from a secret on the filesystem located at `/run/secrets/rabbitmq_password` by defining `$/run/secrets/rabbitmq_password` in the Docker LABEL.
 
-## How to get started
+{% highlight bash %}
+FROM rabbitmq:3.6
 
+RUN rabbitmq-plugins enable rabbitmq_management
+
+# Here we set USERNAME and PASSWWORD in the RabbitMQ configuration taken from secrets on the disk
+LABEL com.coscale.monitoring='[{"PluginType":"RABBITMQ","Configuration":{"HOSTNAME":["localhost"],"PORT":["15672"],"USERNAME":["$/run/secrets/rabbitmq_username"],"PASSWORD":["$/run/secrets/rabbitmq_password"]}}]'
+{% endhighlight %}
+
+## Option 2: Using a packaged agent
+Our agent can get its configuration values for plugins from environment values configured on the server. This allows you to use the same agent for a lot of servers without having to generate a new agent for different configuration setups. An example where this might be used is with database plugin where the status user password isn't the same on all machines.
+
+{% include alert.html type="warning" text="At the moment we only support Linux." %}
 ### 1. Create environment file
 Create a `/etc/default/coscale-agent` and add the following content
 
@@ -22,7 +47,6 @@ export CS_MYSQL_PORT=3306
 export CS_MYSQL_USER=user
 export CS_MYSQL_PASSWORD=password
 export CS_MYSQL_DATABASE=product
-
    {% endhighlight %}
 
 ### 2. Configure agent