Introduction

For JS7 - Automated Deployment On Premises use of a Deployment Area is recommended.

...

• to hold the script environment for JS7 - Automated Installation and Update and for JS7 - Deployment Packaging,
• to hold the configuration files and optionally certificates for deployment of JS7 componentsproducts,
• to hold the JS7 installations per JS7 release and component product such as JOC Cockpit, Controller, Agent,
• to hold the archive of Deployment Packages per JS7 releases and target host,

...

• Deployment Packages are specified from a JS7 - Deployment Descriptor that holds the information which JS7 components products should be installed, on which hosts to install the components products and what configuration items should be used.
• Deployment Packages are created from a script available with JS7 - Deployment Packaging.
• Deployment Packages are transferred and extracted to target hosts. 

...

• js7.deploy
  • desc
    • standalone
      • standalone-agent-http-2022-12-04.descriptor.json
      • standalone-agent-https-2022-12-04.descriptor.json
      • standalone-controller-http-2022-12-04.descriptor.json
      • standalone-controller-https-2022-12-04.descriptor.json
      • standalone-joc-http-2022-12-04.descriptor.json
      • standalone-joc-https-2022-12-04.descriptor.json
      • standalone-joc-controller-agent-http-2022-12-04.descriptor.json
      • standalone-joc-controller-agent-https-2022-12-04.descriptor.json

Deployment Descriptors for use with Controller and JOC Cockpit Cluster Instances

...

• js7.deploy
  • desc
    • cluster
      • cluster-agent-http-2022-12-04.descriptor.json
      • cluster-agent-https-2022-12-04.descriptor.json
      • cluster-controller-http-2022-12-04.descriptor.json
      • cluster-controller-https-2022-12-04.descriptor.json
      • cluster-joc-http-2022-12-04.descriptor.json
      • cluster-joc-https-2022-12-04.descriptor.json
      • cluster-joc-controller-agent-httpshttp-2022-12-04.json

Adjusting the Deployment Descriptor

• • • • descriptor.json
      • cluster-joc-controller-agent-https-2022-12-04.descriptor.json

Adjusting the Deployment Descriptor

For starters it is recommended to use the standalone-agent-http-2022-12-04.json Deployment Descriptor that looks similar to this:

{
    "descriptor": {
        "descriptorId": "standalone-agent-http-2022-12-04",
        "title": "Install or update Agent Standalone instance using HTTP connections",
        "account": "sos",
        "scheduled": "2022-12-02T0602T05:19:12.000+0100:00",
        "created": "2022-11-30T2330T22:19:12.000+0100:00"
    },
    "agents": [{
    "controllerRefs": [
   {
   {
         "agent_001controllerId": {
"controller",
        "members": [
         "target": {
            "agentId": "agent_001",
            "connectiontarget": {
              "connection": {
                "host": "centostest-primary",
                        "port": 22
                    },
                    "authentication": {
                        "method": "publickey",
                "user": "sos",
                "userkeyFile": "/home/sos/.ssh/sos_rsa",
              },
              "keyFilepackageLocation": "/home/sos/.ssh/sos_rsa"
/tmp",
              "execPre": "StopService",
         },
     "execPost": "StartService",
              "packageLocationmakeService": "/tmp"true
                },
                "media": {
                    "release": "2.5.02",
                    "tarball": "2.5.02/js7_agent_unix.2.5.02.tar.gz"
                },
   
             "installation": {
                    "home": "/opt/sos-berlin.com/js7/agent-standaloneprimary",
                    "data": "/var/sos-berlin.com/js7/agent-standaloneprimary",
                    "httpPort": "31445",
              "javaHome": "/opt/java/jdk8u202-b08",
              "javaHomejavaOptions": "/opt/java/jdk8u202-b08-Xmx125m -Djava.security.egd=file:///dev/urandom"
            }
    }
      }
      }
  ]
      }
    ],
  },
  "controllersversion": [],
    "joc": []"1.5.3"
}

Explanation:

• The descriptor.descriptorId element identifies the descriptor. The identifier is similarly used as the name of the Deployment Package. Identifiers can be made up from lowercase and uppercase letters, can include digits, underscores and hyphens. The file name of the Deployment Descriptor is not relevant.
• The agents.agent_001controllerRefs[].members[].agentId element specifies the unique Agent name agent_001.
  • Agent names can be made up from lowercase and uppercase letters, can include digits, underscores and hyphens. Users are free to choose Agent names, for example from the hostname or FQDN that the Agent is operated for, for example using element names such as agents.centostest-primary, agents.centostest-secondary.sos etc.
  • Any number of Agents can be specified in a Deployment Descriptor. 
• The target section specifies the connection and authentication details for the target host to which the Agent should be deployed.
  • Deployment is performed using scp and ssh commands that will use the indicated SSH host and port.
  • Authentication makes use of public/private key specifying the user account and the location of the private keyFile. This setting can be omitted if the private key file matches one of the known names such as id_rsa.
  • For automated deployment It is required that the deployment user account can connect to the target host without use of a password but with a private key only.
  • The packageLocation element specifies the location on the target host where the Deployment Package tarball will be stored.
• The media section specifies the release number and the location of the JS7 installation tarball for the Agent. If a relative path is specified then the value of the DEP_RELEASE environment variable) from the env.sh Environment Script) is prepended to specify the directory in which the installation tarball is available.
• The installation section specifies installation options for the Agent:
  • The Agent's home directory has to be specified . A data directory optionally can be specified, if it is omitted then the <home>/var_<http-port> directory is assumedand a data directory has to be specified. Users should take care that the target.user account has permissions to create required directories, see JS7 - Deployment - Managing Ownership.
  • By default the directories and files of the extracted Deployment Package are owned by the deployment account specified with the target.user element.
    • Should a different account be used on the target host then
      • the owner account of the home directory can be specified with the installation.homeOwner element.
      • the owner account of the data directory can be specified with the installation.dataOwner element.
      • the run-time account of the Agent's service/daemon can be specified with the installation.runUser element.
    • In order to modify accounts of directory owners the target.user account has to be provided permissions to perform sudo to switch to the acquire root permissions without using a password.
  • The Agent's HTTP port can be specified that defaults to port 4445.
  • The location of the Java JDK on the target host can be specified with the javaHome element.
    • The location of Java will be added to the Agent's Start Script in <home>/bin/agent_<http-port>.sh and to the systemd service file in <home>/bin/agent_<http-port>.service.
    • If this setting is omitted, then the Java location is determined by the run-time account, for example from its OS profile settings.

...

The Deployment Packaging script performs the following steps:

• install the JS7 components products according to the Deployment Descriptor
• create a deployment tarball of the installed files. If different A separate tarball for each home and data directories are used then a tarball for each directory will be created.
• create a Rollout Script and Deployment Script that will transfer and extract the deployment tarball on the target host.

...

${DEP_BIN}/js7_create_deployment_package.sh \
    --deploy-desc=${DEP_DESC}/standalone/standalone-agent-http-2022-12-04.descriptor.json \
    --make-dirs

Output of the script will look like this:

-- begin of log --------------
/home/sos/js7.deploy/bin/js7_create_deployment_package.sh --deploy-desc=/home/sos/js7.deploy/desc/standalone/standalone-agent-http-2022-12-04.descriptor.json --make-dirs
-- begin of output -----------
----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- -----
.. creating deployment package for Agent ID: agent_001
----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- -----
.... creating install script: /home/sos/js7.deploy/work/tmp/js7_deploy_package_install_17858.sh
.... running install script: /home/sos/js7.deploy/work/tmp/js7_deploy_package_install_17858.sh
-- begin of log --------------
/home/sos/js7.deploy/bin/js7_install_agent.sh --real-path-prefix=/home/sos/js7.deploy/work/agents/agent_001 --release=2.5.0 --tarball=/home/sos/js7.deploy/release/2.5.0/js7_agent_unix.2.5.0.tar.gz --home=/home/sos/js7.deploy/work/agents/agent_001/opt/sos-berlin.com/js7/agent-standalone --data=/home/sos/js7.deploy/work/agents/agent_001/var/sos-berlin.com/js7/agent-standalone --http-port=31445 --java-home=/opt/java/jdk8u202-b08 --make-dirs
-- begin of output -----------
.. using tarball: /home/sos/js7.deploy/release/2.5.0/js7_agent_unix.2.5.0.tar.gz
.. extracting tarball to temporary directory: /tmp/js7_install_agent_18024.tmp
.. creating Agent home directory: /home/sos/js7.deploy/work/agents/agent_001/opt/sos-berlin.com/js7/agent-standalone
.. creating Agent data directory: /home/sos/js7.deploy/work/agents/agent_001/var/sos-berlin.com/js7/agent-standalone
.. copying files from extracted tarball directory: /tmp/js7_install_agent_18024.tmp/agent to Agent home: /home/sos/js7.deploy/work/agents/agent_001/opt/sos-berlin.com/js7/agent-standalone
.. creating Agent data directory: /home/sos/js7.deploy/work/agents/agent_001/var/sos-berlin.com/js7/agent-standalone
.. copying files to Agent data directory: /home/sos/js7.deploy/work/agents/agent_001/var/sos-berlin.com/js7/agent-standalone
.. copying Agent Instancee Start Script /home/sos/js7.deploy/work/agents/agent_001/opt/sos-berlin.com/js7/agent-standalone/bin/agent_instance.sh-example to /home/sos/js7.deploy/work/agents/agent_001/opt/sos-berlin.com/js7/agent-standalone/bin/agent_31445.sh
.. copying /home/sos/js7.deploy/work/agents/agent_001/opt/sos-berlin.com/js7/agent-standalone/bin/agent.service-example to /home/sos/js7.deploy/work/agents/agent_001/opt/sos-berlin.com/js7/agent-standalone/bin/agent_31445.service
.. updating Agent Instance Start Script: /home/sos/js7.deploy/work/agents/agent_001/opt/sos-berlin.com/js7/agent-standalone/bin/agent_31445.sh
.. updating Agent systemd service file: /home/sos/js7.deploy/work/agents/agent_001/opt/sos-berlin.com/js7/agent-standalone/bin/agent_31445.service
-- end of log ----------------
.... creating installation deployment package file: tar -cf /home/sos/js7.deploy/archive/standalone-agent-http-2022-12-04/agents/agent_001/js7_deploy_agent_unix.agent_001.2.5.0.install.tar -C /home/sos/js7.deploy/work/agents/agent_001/opt/sos-berlin.com/js7 agent-standalone
.... installation deployment package ready: /home/sos/js7.deploy/archive/standalone-agent-http-2022-12-04/agents/agent_001/js7_deploy_agent_unix.agent_001.2.5.0.install.tar.gz
.... creating configuration deployment package file: tar -cf /home/sos/js7.deploy/archive/standalone-agent-http-2022-12-04/agents/agent_001/js7_deploy_agent_unix.agent_001.2.5.0.config.tar -C /home/sos/js7.deploy/work/agents/agent_001/var/sos-berlin.com/js7 agent-standalone
.... configuration deployment package ready: /home/sos/js7.dep/archive/standalone-agent-http-2022-12-04/agents/agent_001/js7_deploy_agent_unix.agent_001.2.5.0.config.tar.gz
.... install script for deployment package ready: /home/sos/js7.dep/archive/standalone-agent-http-2022-12-04/agents/agent_001/run_install_agent.sh
.... job script for deployment package ready: /home/sos/js7.dep/archive/standalone-agent-http-2022-12-04/agents/agent_001/run_deploy_agent.sh
.... creating JS7 import file: tar -cf /home/sos/js7.dep/archive/standalone-agent-http-2022-12-04/js7_import.tar *
.... JS7 import file ready: /home/sos/js7.dep/archive/standalone-agent-http-2022-12-04/js7_import.tar.gz
.. Deployment Script ready: /home/sos/js7.dep/archive/standalone-agent-http-2022-12-04/run_deploy.sh
-- end of log ----------------

...

• js7.deploy
  • archive
    • standalone-agent-http-2022-12-04 (directory name created from the Deployment Descriptor ID)
      
      • agents (sub-directory for Agent deployments)
        • agent_001 (sub-directory for specific Agent identified by its Agent ID)
          • js7_deploy_agent_unix.agent_001.2.5.0.config.tar.gz (tarball of the Agent's configuration directory)
          • js7_deploy_agent_unix.agent_001.2.5.0.install.tar.gz (tarball of the Agent's installation directory)
          • run_deploy_agent.sh (Deployment Script for Agent)
          • run_install_agent.sh (Installer Wrapper Script for Agent)
          • run_rollout_agent.sh (Rollout Script for Agent)
      • js7_import.tar.gz (tarball for import into JS7 JOC Cockpit, includes workflow and schedule for automated deployment)
      • run_rollout.sh (Rollout Script for any JS7 componentsproduct, includes calls to agents/agent_001/run_rollout_agent.sh and similar scripts per JS7 componentproduct) 

Basically the run_rollout_agent.sh script can be used to transfer the Agent's tarballs for configuration and installation directories to the target host. In addition, the run_deploy_agent.sh script is transferred to the target host and is executed on that host to extract the tarballs of Agent installation and configuration directories.

• Use of the Rollout Script from the command line is applicable if a smaller number of JS7 components products should be installed and if no JS7 scheduling environment is yet available.
• If a JS7 scheduling environment is set up then it is preferable to import the js7_import.tar.gz tarball to JOC Cockpit that adds a workflow and schedule for parallel deployment of JS7 componentsproducts. For details see JS7 - Deployment Workflow.

...

• importing the workflow and schedule created with the Deployment Package into JOC Cockpit und using the JS7 - Deployment Workflow.
• or by executing the Rollouot Rollout Script from the command line.

...

${DEP_ARCHIVE}/standalone-agent-http-2022-12-04/run_rollout.sh

...

• JS7 - Deployment - Getting Started
  
  • JS7 - Deployment - Setting up the Deployment Area
  • JS7 - Deployment - Managing Ownership
  • JS7 - Deployment - Managing Certificates

...