The following subsections provide detailed information on the Python Cartridge Agent:
Overview
The cartridge agent (CA) is a python based component that resides within a cartridge instance and handles the communication between the cartridge and Stratos. The Python cartridge agent communicates with the message broker to subscribe and publish topics, communicates with a remote Git repository to synchronize the artifacts in the cartridge with the remote repository and also publishes health statistics to the CEP. The Python cartridge agent source can be found the /components/org.apache.stratos.python.cartridge.agent directory.
Configurations
The Python cartridge agent is automatically configured based on the configurations in the <AGENT_HOME>/agent.conf file. The agent.conf file contains parameters to configure the message broker, Thrift receiver, monitoring server and more. In the case of VM's, Puppet will handle setting the values in this file. While, in the Kubernete's based container scenario, the Docker entry point script will handle the process of setting these values. The values for the agent.conf file parameters that do not have default values should be provided by the calling party; otherwise, the cartridge agent will not start.
Click here to see the agent.conf
[agent]
mb.ip =MB-IP
mb.port =MB-PORT
mb.urls =MB-URLS
mb.username =MB-USERNAME
mb.password =MB-PASSWORD
mb.publisher.timeout =MB-PUBLISHER-TIMEOUT
listen.address =LISTEN_ADDR
thrift.receiver.urls =CEP-URLS
thrift.server.admin.username =CEP-ADMIN-USERNAME
thrift.server.admin.password =CEP-ADMIN-PASSWORD
cep.stats.publisher.enabled =ENABLE_HEALTH_PUBLISHER
lb.private.ip =LB_PRIVATE_IP
lb.public.ip =LB_PUBLIC_IP
enable.artifact.update =ENABLE_ARTFCT_UPDATE
auto.commit =COMMIT_ENABLED
auto.checkout =CHECKOUT_ENABLED
artifact.update.interval =ARTFCT_UPDATE_INT
artifact.clone.retries =ARTFCT_CLONE_RETRIES
artifact.clone.interval =ARTFCT_CLONE_INT
port.check.timeout =PORT_CHECK_TIMEOUT
enable.data.publisher =ENABLE-DATA-PUBLISHER
monitoring.server.ip =MONITORING-SERVER-IP
monitoring.server.port =MONITORING-SERVER-PORT
monitoring.server.secure.port =MONITORING-SERVER-SECURE-PORT
monitoring.server.admin.username =MONITORING-SERVER-ADMIN-USERNAME
monitoring.server.admin.password =MONITORING-SERVER-ADMIN-PASSWORD
log.file.paths =LOG_FILE_PATHS
APPLICATION_PATH =APPLICATION-PATH
metadata.service.url =METADATA-SERVICE-URL
super.tenant.repository.path =/repository/deployment/server/
tenant.repository.path =/repository/tenants/
The python cartridge agent persist the payload parameters, similar to how the Java agent worked. When the cartridge agent is initialized, it will read both the agent configuration files (agent.conf and logging.ini), and as required, will provide these values to the modules.
In addition, the logging parameters can be configured via the <AGENT_HOME>/logging.ini file.
Logging
The log files associated with the agent are located in the following two directories; the agent.screen log is in the /tmp directory and the other agent logs are in /var/log/apache-stratos/ directory. The agent.log is the standard cartridge agent log file; while, the error.log contains all the ERROR level logs. The agent.log is very verbose when the debug level logging (DEBUG) is enabled. Therefore, it is useful to refer the error.log when the agent.log is filled with a large number of DEBUG log entries. As the agent.screen.log file contains all the output of the Python Agent process's standard output (stdout), including all the uncaught exceptions, the agent.screen.log is useful in situations when the agent.log fails to include process related output.
Methods of installing and starting a CA
The cartridge agent installation and starting process will be done automatically; however, it will vary based on the approach used to deploy a cartridge in Stratos. In a Docker scenario this will be done by the entry point script while in a VM scenario this will be done by Puppet.
Docker file scenario
The approach used with the a Docker file is to install the needed service (e.g., PHP, MySQL, Tomcat etc.) and then add the cartridge agent to the image. The entrypoint script is the run script file. This script replaces the mandatory and optional values with the values that are passed to the container as environment variables and starts the Python process. Additionally, the run script will also persist the payload parameters in the <AGENT_HOME>/payload/launch.params file.
Click here to see the run script
source /root/.bashrc
/usr/local/bin/populate-user-data.sh
#mandatory parameters
sed -i "s/MB-IP/${MB_IP}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
sed -i "s/MB-PORT/${MB_PORT}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
#parameters that can be empty
#default values have to be set
if [ -z "${LISTEN_ADDR}" ]; then
sed -i "s/LISTEN_ADDR/localhost/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s/LISTEN_ADDR/${LISTEN_ADDR}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
# defaults to the message broker IP if not set
if [ -z "${CEP_IP}" ]; then
sed -i "s/CEP-IP/${MB_IP}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s/CEP-IP/${CEP_IP}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
if [ -z "${CEP_PORT}" ]; then
sed -i "s/CEP-PORT/7711/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s/CEP-PORT/${CEP_PORT}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
if [ -z "${CEP_USERNAME}" ]; then
sed -i "s/CEP-ADMIN-USERNAME/admin/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s/CEP-ADMIN-USERNAME/${CEP_USERNAME}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
if [ -z "${CEP_PASSWORD}" ]; then
sed -i "s/CEP-ADMIN-PASSWORD/admin/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s/CEP-ADMIN-PASSWORD/${CEP_PASSWORD}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
if [ -z "${ENABLE_HEALTH_PUBLISHER}" ]; then
sed -i "s/ENABLE_HEALTH_PUBLISHER/true/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s/ENABLE_HEALTH_PUBLISHER/${ENABLE_HEALTH_PUBLISHER}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
if [ -z "${LB_PRIVATE_IP}" ]; then
sed -i "s/LB_PRIVATE_IP/ /g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s/LB_PRIVATE_IP/${LB_PRIVATE_IP}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
if [ -z "${LB_PUBLIC_IP}" ]; then
sed -i "s/LB_PUBLIC_IP/ /g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s/LB_PUBLIC_IP/${LB_PUBLIC_IP}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
if [ -z "${ENABLE_ARTFCT_UPDATE}" ]; then
sed -i "s/ENABLE_ARTFCT_UPDATE/true/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s/ENABLE_ARTFCT_UPDATE/${ENABLE_ARTFCT_UPDATE}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
if [ -z "${COMMIT_ENABLED}" ]; then
sed -i "s/COMMIT_ENABLED/false/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s/COMMIT_ENABLED/${COMMIT_ENABLED}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
if [ -z "${CHECKOUT_ENABLED}" ]; then
sed -i "s/CHECKOUT_ENABLED/true/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s/CHECKOUT_ENABLED/${CHECKOUT_ENABLED}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
if [ -z "${ARTFCT_UPDATE_INT}" ]; then
sed -i "s/ARTFCT_UPDATE_INT/15/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s/ARTFCT_UPDATE_INT/${ARTFCT_UPDATE_INT}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
if [ -z "${PORT_CHECK_TIMEOUT}" ]; then
sed -i "s/PORT_CHECK_TIMEOUT/600000/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s/PORT_CHECK_TIMEOUT/${PORT_CHECK_TIMEOUT}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
if [ -z "${ENABLE_DATA_PUBLISHER}" ]; then
sed -i "s/ENABLE-DATA-PUBLISHER/false/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s/ENABLE-DATA-PUBLISHER/${ENABLE_DATA_PUBLISHER}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
# defaults to the message broker IP if not set
if [ -z "${MONITORING_SERVER_IP}" ]; then
sed -i "s/MONITORING-SERVER-IP/${MB_IP}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s/MONITORING-SERVER-IP/${MONITORING_SERVER_IP}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
if [ -z "${MONITORING_SERVER_PORT}" ]; then
sed -i "s/MONITORING-SERVER-PORT/7611/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s/MONITORING-SERVER-PORT/${MONITORING_SERVER_PORT}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
if [ -z "${MONITORING_SERVER_SECURE_PORT}" ]; then
sed -i "s/MONITORING-SERVER-SECURE-PORT/7711/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s/MONITORING-SERVER-SECURE-PORT/${MONITORING_SERVER_SECURE_PORT}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
if [ -z "${MONITORING_SERVER_ADMIN_USERNAME}" ]; then
sed -i "s/MONITORING-SERVER-ADMIN-USERNAME/admin/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s/MONITORING-SERVER-ADMIN-USERNAME/${MONITORING_SERVER_ADMIN_USERNAME}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
if [ -z "${MONITORING_SERVER_ADMIN_PASSWORD}" ]; then
sed -i "s/MONITORING-SERVER-ADMIN-PASSWORD/admin/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s/MONITORING-SERVER-ADMIN-PASSWORD/${MONITORING_SERVER_ADMIN_PASSWORD}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
if [ -z "${LOG_FILE_PATHS}" ]; then
sed -i "s/LOG_FILE_PATHS/ /g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s#LOG_FILE_PATHS#${LOG_FILE_PATHS}#g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
if [ -z "${APP_PATH}" ]; then
sed -i "s/APP-PATH/ /g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
else
sed -i "s#APP-PATH#${APP_PATH}#g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/agent.conf
fi
if [ -z "${LOG_LEVEL}" ]; then
sed -i "s/LOG_LEVEL/INFO/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/logging.ini
else
sed -i "s/LOG_LEVEL/${LOG_LEVEL}/g" /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/logging.ini
fi
SYS_LOG="/var/log/apache2/error.log"
SAML_ALIAS="/var/www/"
#sed -i "s#SYS-LOG#${SYS_LOG}#g" /etc/apache2/apache2.conf
#sed -i "s#APP-PATH#${APP_PATH}#g" /etc/apache2/sites-available/default
#sed -i "s#SAML-ALIAS#${SAML_ALIAS}#g" /etc/apache2/sites-available/default
cd /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT
python agent.py > /tmp/agent.screen.log 2>&1 &
/usr/sbin/apache2ctl -D FOREGROUND
Stratos will provide these values via Kubernetes using the values provided via the application definition JSON.
Click here to see a sample Docker file
FROM ubuntu:14.04
MAINTAINER chamilad@wso2.com
RUN apt-get update
RUN apt-get install -y wget
WORKDIR /opt/
#################################
# Enable ssh - This is not good. http://jpetazzo.github.io/2014/06/23/docker-ssh-considered-evil/
# For experimental purposes only
##################################
RUN apt-get install -y openssh-server
RUN mkdir -p /var/run/sshd
RUN echo 'root:g' | chpasswd
RUN sed -i "s/PermitRootLogin without-password/#PermitRootLogin without-password/" /etc/ssh/sshd_config
##################
# Install PHP
##################
RUN apt-get install -y apache2 php5 zip unzip stress
RUN rm /etc/apache2/sites-enabled/000-default.conf
ADD files/000-default.conf /etc/apache2/sites-enabled/000-default.conf
#ADD files/apache2/apache2.conf /etc/apache2/apache2.conf
#ADD files/apache2/sites-available/default-ssl /etc/apache2/sites-available/default-ssl
#ADD files/apache2/sites-available/default /etc/apache2/sites-available/default
##################################
# Install Dependent Python Libs
##################################
RUN apt-get install -y git python python-pip python-dev gcc
RUN pip install paho-mqtt
RUN pip install GitPython==0.3.1-beta2
RUN pip install psutil
RUN pip install gittle
RUN pip install pexpect
##################
# Configure Agent
##################
WORKDIR /mnt/
RUN mkdir -p /mnt/packs
RUN mkdir -p /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT
ADD packs/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT.zip /mnt/packs/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT.zip
WORKDIR /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT
RUN unzip -q ../packs/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT.zip
WORKDIR /mnt/
RUN rm -rf packs
RUN mkdir -p /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/payload
RUN mkdir -p /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/extensions
ADD packs/extensions /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/extensions
RUN chmod +x /mnt/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT/extensions/*
RUN mkdir -p /var/log/apache-stratos/
RUN touch /var/log/apache-stratos/cartridge-agent-extensions.log
EXPOSE 22 80
###################
# Setup run script
###################
ADD run /usr/local/bin/run
RUN chmod +x /usr/local/bin/run
ADD files/populate-user-data.sh /usr/local/bin/populate-user-data.sh
RUN chmod +x /usr/local/bin/populate-user-data.sh
ENTRYPOINT /usr/local/bin/run | /usr/sbin/sshd -D
Puppet scenario
In Virtual Machine (VM) scenario, Puppet will be used to configure the VM. Puppet configurations are located in the /tools/puppet3/modules/python_agent/ directory. The old agent and java modules are not used anymore, unless they are explicitly needed in cartridges Java related cartridges (e.g., tomcat etc.).
Setting up the cartridge agent
Follow the steps below to setup the cartridge agent:
Step 1 - Check out the source
Checkout the source from Apache Stratos remote repository to a folder of your choice.
git clone https://git-wip-us.apache.org/repos/asf/stratos.git <local-folder-name>
For example:
git clone https://git-wip-us.apache.org/repos/asf/stratos.git myLocalRepo
Step 2 - Build using Maven
- Go to the top level of the directory in which you checked out the source.
cd <local-folder-name>
For example:
cd myLocalRepo
Use Maven to build the source distribution of the release.
mvn clean install
If required, you can execute the following command to get details on the deployable cartridge agent ZIP file.
ls -l products/python-cartridge-agent/target
If Stratos has been built successfully, the deployable cartridge agent ZIP file named apache-stratos-python-cartridge-agent-<VERSION>-SNAPSHOT.zip (e.g., apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT.zip) can be found in the /products/python-cartridge-agent/target/ directory.
Step 3 - Install and start the cartridge agent
The cartridge agent installation and starting process will be done automatically; however, it will vary based on the approach used to deploy a cartridge in Stratos. In a Docker scenario this will be done by the entry point script; while, in a VM scenario this will be done by Puppet. For more information, see Methods of installing and starting a CA.
Docker file scenario - Building the Docker image
Checkout the Docker file content.
git clone https://github.com/chamilad/stratos-container-image-php.git
- Navigate to the
stratos-container-image-php directory.cd stratos-container-image-php
Copy the cartridge agent artifact ZIP file from the products/ directory to the packs/ directory.
cp <STRATOS_HOME>/products/python-cartridge-agent/target/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT.zip packs/
- Build the Docker image.
sudo docker build -t chamilad/stratos-php:4.1.x-alpha
- Verify the built image
sudo docker images
Puppet scenario
Follow the steps below to configure the Puppet module for the Python cartridge agent:
1. Copy the Python agent distribution to the Puppet master. For more information, see Configuring Puppet Master.
2. Set the agent configuration values in the base.pp file, found in the /etc/puppet/manifests/nodes/ directory. The Puppet module for the Python cartridge agent will configure the cartridge agent based on the values provided
Running the Python cartridge agent without Puppet or Docker
Follow the steps below to run the python cartridge agent without Puppet or Docker:
- Navigate to the
apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT directory.
cd <STRATOS_HOME>/products/ python-cartridge-agent/target/apache-stratos-python-cartridge-agent-4.1.x-SNAPSHOT
- Start the cartridge agent by running the
agent.py file.
nohup python agent.py &
