Applicative Administration Commands¶

Abstract

The punchplatform provides its users with very few concepts to understand, and a minimal set of commands. This chapter go through the essentials for everyday administration when you operate or troubleshoot your applicatios and punchlines. More "platform/component" oriented commands are documented in Components administration commands.

For most of commands operating on data processing punchlines/applications, you will need to specify the specific tenant on which you want to apply a change.

The file system configuration folder layout has a REST-like tree organisation starting with the tenant name, then have sub folders for channels and books. In channels and books folders are stored the application configuration files.

Platform services managed using the platformctl and kafkactl tools. For everyday operation, this is most helpful to provide easily a view of the platform framewor components health. For more commands related to the platform software framework components, refer to Components administration commands.
Channels contain your ever running applications. You act upon a channel using the channelctl commands : start, stop reload.
Books contain application worflows. You act upon a book using the bookctl commands : start, stop reload.
Applications can be individually started or stopped using the --application command option provided by channelctland bookctl.

Platform Commands¶

Your platform health can be in one of three states.

State	Meaning
GREEN	Your platform is in nominal condition. All its components are green as well.
YELLOW	Some of the platform component(s) are in degraded condition yet can provide its service.
RED	Some of the platform component(s) are not capable of ensuring its service.

Use the platformctl to query or act upon your platform. Note that on a secure platform, platformctl will automatically leverage the required credentials. The followings commands are available:

Platform Health Check¶

Refer to

platformctl health

Platform Status¶

Simply type in

platformctl status

Configuration Backup Restore¶

It is strongly advised to save your configuration files preferably using a git repository to ensure traceability and configuration rollback. You should then always commit and push the updated reference configuration of your platform to your central git repository for configuration management.

The punch provides an additional backup restore facility to back up restore all your tenants configuration files. This function requires a Kafka cluster. To back up your tenants configuration tree:

platformctl backup --cluster common

To restore your configuration :

platformctl restore --cluster common --destination /tmp

The restored tenants folder will be written in the provided output folder (here /tmp). If you want to restore it in your configuration folder type in:

platformctl restore --cluster common --destination $PUNCHPLATFORM_CONF_DIR

In which case the previous configuration will be moved to a tenants.<timestamp>.sav folder for you to ensure you did not make a mistake.

Backup-restore requires a topic be created upfront. On production platforms use for example the following command:

kafkactl create-topics --topic platform-tenants-backups --cluster common --replication-factor 3

The kafkactlcommand is described hereafter.

Kafka Commands¶

Kafka plays a key role both for administrative internal punch services and your applicative pipelines. The punch provides a dedicated kafkactlcommand to make it easy to check or manage the kafka topics used by these various services.

List Kafka Topics¶

kafkactl --list-topics

Describe Kafka Topics¶

kafkactl --describe-topics

Describe Consumer Groups¶

This command is useful to check who (i.e. which service or application) is listening to which topic. Refer to

kafkactl --describe-consumer-groups --help

Create Kafka Topics¶

Refer to

kafkactl --create-topics --help

Delete Kafka Topics¶

Refer to

kafkactl --delete-topics --help

Channel Commands¶

The runtime status of a channel is one of the following.

State	Meaning
ACTIVE	the channel or service is running in nominal condition.
STOPPED	the channel or service is stopped.
PARTIAL	this is a non nominal situation. One of your channel application is not running anymore, most probably because an operator stopped it using an external or cli command
OUT_OF_SYNC	This indicates that one of the channel configuration file was changed after the channel was started.

The basic operations are to start stop or reload one or several channels.

Channel Status Check¶

channelctl --tenant yourtenant status

The status of a single channel can be queried using:

channelctl --tenant mytenant status --channel mychannel

The various configuration files can be edited using standard file editors. Changing a configuration file has no effect until you restart the corresponding channel(s).

The punch stores a snapshot of the runtime status channels in a configuration store. You can have a look at the configuration store for a tenant using the following command:

channelctl --tenant yourtenant describe

Info

The configuration store is either a filesystem (on development or one node punch) or Kafka (on distributed punch).

Channel Start¶

To start all the channels from a tenant:

channelctl --tenant yourtenant start

or

channelctl --tenant mytenant start --channel mychannel

Channel Stop¶

To stop a channel:

channelctl --tenant mytenant stop --channel apache_httpd

or all of them:

channelctl --tenant mytenant stop

It is possible to force a channel to stop if the upper command didn't work :

channelctl --tenant mytenant stop --channel apache_httpd --force

Application Commands¶

The channelctl command provides you with the capability to start stop or status only a dedicated application. Here is an example:

channelctl --tenant mytenant start --application apache_httpd/main/single_topology

Refer to the channelctl online help for details.

Tip

You can use a '*' wilcard in any segment (channel, cluster, name) of an application.

E.g. channelctl --tenant mytenant start --application //parsing

Channel Audit¶

Before starting channels you can check if it is properly configured using the following command:

channelctl --tenant mytenant audit

Checkout the online documentation :

channelctl --tenant mytenant audit --help

Tip

A misconfigured channel cannot be started. Also these do not appear if you execute a status command. Misconfigured channels are not considered as valid hence startable channels.

Channel Shiva Application Check¶

This command provides useful additional information regarding shiva applications:

channelctl shiva-status

Channel Configuration File Quick View¶

It is handy to have a look to one of the channel configuration file without opening a separate text editor. Simply type in:

channelctl view

Book Commands¶

Books are very similar to channels. The difference is simply that a book Use bookctl instead of channelctl.

Administration Kibana GUI¶

Regular per tenant users are provided with a secured GUI. There, they can act only on their tenant configurations. The Kibana Gui let authorized users stop/start or reload channels and services.

Administration REST API¶

The punch exposes some resources as REST APIs, in particular the health status of the platform. This makes it very simple to monitor a punchplatform from an external monitoring tool.

Administrative Logging¶

All platform actions are recorded in a daily Elasticsearch index platform-logs-*. In particular the operator actions are recorded. Here is the log record format:

{
    # The content section contains the actual log. It can be:
    # - a log from punchtcl to trace the channel and job start stop commands
    # - a log from Shiva leader or workers to trace the shiva job start stop and 
    #     assignements events
    # - logs from Shiva jobs (i.e. subprocess)
    "content": {
        # level can be INFO WARN or ERROR.
        # ERRORs should be carefully watched for. 
        "level": "INFO",

        # the actual log message. 
        "message": "job started"

        # only for shiva jobs, the actual args command
        "args": "[/opt/data/punch-standalone-5.2.0/external/punchplatform-shiva-5.2.0/features/commands/logstash, -f, logstash.conf]",

        # whenever available the logger that generated the log. This
        # can be the child logger or the shiva worker logger. 
        "logger": "org.thales.punch.apps.shiva.worker.impl.WorkerTask",
    },
    # the target section relates to the target runtime environment.
    # I.e. a Storm|Shiva|Spark cluster in charge of the related event.
    "target": {
      "cluster": "main",
      "type": "storm"
    },
    # the init section relates to the event originator. 
    "init": {
      "process": {
          # the application name that generated the event
          "name": "channelctl",
          # a runtime id whenever available
          "id": "56605@server1.thales.com"
      },
      "host": {
        # the host name where the event was issued
        "name": "server1"
      },
      "user": {
          # the (unix) user name owning the application.
          # It can be a platform operator or a daemon user depending
          # on the application generating the event.
         "name": "operator"
      }
    },
    # the tenant
    "tenant": "mytenant",

    # the type is always 'punch'.
    "type": "punch",

    # the vendor is always 'thales'
    "vendor": "thales",

    # the channel name
    "channel": "logstash",

    # the job name, if available
    "job": "logstash",

    # the generation timestamp
    "@timestamp": "2019-05-16T03:54:36.949Z"

The important normalized message values are the following:

Message	Description
"application started"	indicate the start of a channel application. These messages are generated by the channelctl and shiva_worker applications.
"application stopped"	indicate the stop of a channel application. These messages are generated by the channelctl and shiva_worker applications.
"assigned application to worker"	Generated by the shiva_leader application. Indicate the assignment of a job to a shiva worker.
"scheduled ever running application"	Generated by a shiva_worker application. Indicate the scheduling of a continuously running shiva job.
"scheduled periodic application"	Generated by a shiva_worker application. Indicate the scheduling of a periodic shiva job. Typical a pml plan or any other job scheduled using a cron quartz schedule parameter.
"starting application on worker"	Generated by a shiva_worker application. Indicate the effective start of a shiva job.