Table of Contents |
---|
Scope
- Version Control Systems are frequently used in software development. They can be applied as a basis for managed deployment of job-related objects, however, they are not focused on this purpose and therefore do not support specific deployment strategies. The basic functionality includes
- to rollback to an older release if required.
- to have changes documented.
- to commit changes that are relevant for target environments.
- to exclude test files and configuration files by not adding them to the repository.
- This article provides some considerations and recommendations on deployment strategies. Users will have to determine the applicability of the repspective deployment strategy on their own.
- SOS does not claim any preferences for a specific Version Control System product. At the time of writing no specific functionality is available that would make e.g. Git more useful for deployments than Subversion or Team Foundation Server. Therefore this article is not about comparing or recommending specific products, instead it will use Git and Subversion to explain the required repository operations for deployments.
Prerequisites
Requirements
- Deployments include to consistently deploy all job-related objects, i.e. Jobs, Job Chains, Orders, Process Classes, Locks etc., that are referenced by each other and that make up a release.
- Deployments consider configuration items, e.g. path names, ports, folders, that are applicable to all environments and configuration items that are specific for an individual environment.
- Deployments can be carried out for a number of environments. Some users might use development, integration and production environments, other users might add sandbox or user acceptance test environments.
- Deployments are caried out for releases, not for changes of individual files. Version control is not a replacement for creating backups of your job environments.
- Capability to rollback to a previous release: Should a problem be detected e.g. in a production environment and not enough time be available for thorough analysis, then the option is to rollback immediately to a consistent previous state of job-related objects.
Environments
- Three environments are required for managed deployments:
- Development
- Modifications to job-related objects are carried out in this environment.
- Integration
- No modifications are applied to job-related objects.
- Configuration items are specific for this environment.
- Production
- No modifications are applied to job-related objects.
- Configuration items are specific for this environment.
- Development
- The purpose of the integration environment is to carry out tests of deployed objects. This includes testing the completeness, interoperability and accuracy of deployed objects.
- Should users want to skip the use of an integration environment then tests would have to be performed in a production environment which is not a recommended strategy.
Terms used with Version Control Systems
- Repository
- Repositories are logical units in a Version Control System to store Branches of objects that can be assigned permissions for access by different users and groups.
- Working Copy
- Working Copies are local copies of files from a Repository. Modifications are applied to files in a Working Copy that later on can be Comitted to the Repository.
- Branch
- A Branch corresponds to the current status of the job-related objects that have been added to the Repository by Commit operations.
- Only one Branch at a time should be used for job deployment. Multiple branches are frequently used to organize the contributions of a number of developers who work in parallel on the same sources. It is not a recommended scenario for job development to have multiple engineers work in parallel on the same jobs.
- Branches can be tagged, e.g. assigned a Release number.
- Commit
- Commits include to submit a fully functional and deployable copy of job-related objects from a Working Copy to a Repository.
- Commits are not intended for backup of Working Copies for job-related objects.
- Release
- Releases are tagged Branches that are not modified after deployment.
- Release numbers can be applied according to individual conventions. Semantic Versioning is a frequently used standard for release numbering (Major.Minor.Patch).
Use Cases
- Initial creation of a repository with the configuration items of a JobScheduler instance.
- Configuration items are stored in the
live
folder. - These items should become part of the repository.
- The
live
folder should be a checked out version of the configuration.
- Configuration items are stored in the
- Initial Deployment
- Initially deploy a release to an integration or production environment.
- Update Management
- Deploy a maintenance release to an existing environments.
- Existing job-related objects will be replaced.
- Dropped job-related objects will be removed.
- Existing configuration items should be considered and maintained.
Rollback to a previous release
- Identify the release to which you want to fall back.
- With Subversion/Git operations get the files of the desired release.
- Deploy the desired release as stated with the "Update Management"
Best Practices
Separating configuration items specific for an environment
- When carrying out the deployments it is possible that parameter values are not applicable to target environments, e.g. the names of files, folders, printers etc.
- In a first step users should clearly separate all configuration items that are specific for an environment from job-related objects and configuration items that can be applied to all environments without changes.
Examples for configuration items that should be considered include
- host names for process classes
- Solution: Having a set of process classes in each environment that will not be part of the deployment procedure. This configuration will be handled directly in the specific environment.
- directories for file order sources
- Solution: Having different file order sources in each environment that will not be part of the deployment procedure. This configuration will be handled directly in the respective environment.
- values for parameters, e.g. database connection strings
- Solution: Make use of include files.
- Solution: Make use of environment variables that will be substituted at run time.
- host names for process classes
Use of Environment Variables
- Use environment variables that accept different values in target environments for
- File Order Sources
- Directories in file names
Code Block | ||
---|---|---|
| ||
<job_chain>
<file_order_source directory="${file_input_dir}\input" regex=".*"/>
...
</job_chain> |
Use of Include Files for Parameters
Use include files to specify parameter values:
Code Block | ||
---|---|---|
| ||
<order>
<params>
<include live_file="myorder.params.xml" node=""/>
</params>
...
</order> |
where the file myorder.params.xml could look like this:
Code Block | ||
---|---|---|
| ||
<params >
<param name="par1" value="value1"/>
<param name="par2" value="value2"/>
...
</params> |
Use of Include Files for Scripts
Use different script include files for development, integration and production environments:
Code Block | ||
---|---|---|
| ||
<job order="yes">
<script language="shell">
<include live_file="include_scriptfile.sh"/>
</script>
<run_time />
</job> |
Example for the Handling of different Include Files for Parameters and Scripts
- create a folder
include_files
(located parallely to thelive
folder) - create sub-folders for target environments, e.g.
dev
,int
andprod
. - create the same sub-folders for all target environments as in the development environment
live
folder - create the include files in the sub-folders for the target environments
- create a folder in the repository that contains the folder
include_file
- create a working copy with the
import, delete
andcheckout
commands (see below). - When committing the
include_files
folder you should also commit thelive
folder (and vice versa) to guarantee consistency between both folders. - When deploying to the integration environment then export the
include_files/int
folder to the targetlive
folder. - When deploying to the production environment then export the
include_files/prod
folder to the targetlive
folder.
As you have a working copy in the live
folder for dev
, the include files from dev
will be deployed when exporting the dev
folder. But with the second export from the include_files
folder, the dev
files will be overwritten with the correct version. An alternative approach is that also the live
folder in dev is not a working copy but will be updated with an export command from the dev working copy.
Handling of Version Control Systems
- Discipline
- Due to the possible sharing of tasks between job development and integration testing a test manager might not know exactly what files are included with the delivery of a release, i.e. he or she cannot check the completeness of deployed objects.
- Therefore the discipline of the job developer to commit complete and accurate jobs and job dependencies is vital to the deployment process.
- Quality of the development environment
When managing test configuration files in the development environment you should take care not to commit them to the repository. To achieve this, do not add such files to the repository. Typically you can add such files to an ignore list (available with Git and Subversion). You should take into account that each configuration item that has been committed to the repository will be deployed to the integration or production environments some time later.
Deployment
Deployment Process Flow
Flowchart |
---|
jobs_dev [label="Jobs\nDevelopment Environment",fillcolor="lightskyblue"]
jobs_int [label="Jobs\nIntegration Environment",fillcolor="lightskyblue"]
jobs_prod [label="Jobs\nProduction Environment",fillcolor="lightskyblue"]
conf_dev [shape="ellipse",label="Configuration Items\nDevelopment Environment",fillcolor="violet"]
conf_int [shape="ellipse",label="Configuration Items\nIntegration Environment",fillcolor="violet"]
conf_prod [shape="ellipse",label="Configuration Items\nProduction Environment",fillcolor="violet"]
repo_dev [label="Repository\nDevelopment Branch",fillcolor="orange"]
repo_int [label="Repository\nIntegration Branch",fillcolor="orange"]
repo_prod [label="Repository\nProduction Branch",fillcolor="orange"]
jobs_dev -> conf_dev
jobs_dev -> repo_dev
conf_dev -> repo_dev
repo_dev -> repo_int
repo_int -> jobs_int
jobs_int -> conf_int
conf_int -> repo_int
repo_dev -> repo_prod
repo_prod -> jobs_prod
jobs_prod -> conf_prod
conf_prod -> repo_prod |
Explanations
The deployments from development to integration and production environments make use of the following steps:
- Development Environment:
- add the job files and configuration files to the repository.
- do not add files to the repository that are used exclusively for testing in this environment, e.g. mock files.
- Integration Environment
- Update a local working copy from the development branch of the repository. Do not use the
live
folder directly but a separate folder outside of the JobScheduler installation for updating. - Manage configuration files for this environment in a separate folder and add them to the integration branch of the repository.
- Update the integration environment, i.e. the
live
folder, first from the working copy for the development branch 1) and then from the working copy for configuration files from the integration branch 2).
- Update a local working copy from the development branch of the repository. Do not use the
- Production Environment
- Apply the same local working copies and deployment steps as for the integration environment.
Deployment Operations with Subversion and Git
The following table describes the deployment operations with Subversion and Git.
Subversion | Git | ||
---|---|---|---|
Prerequisites | Subversion Server | Git Server | |
Find the Subversion server documentation from http://svnbook.red-bean.com/en/1.5/ | The complete Git server documentation can be found from https://git-scm.com/documentation | ||
Subversion Repository Find the documentation „how to install a subversion server“ e.g. from http://svnbook.red-bean.com/en/1.8/svn.serverconfig.html | Git Repository You can create a central repository by: |
Why using a version control system?
- deploy by releases
- branch = code Stand: nur 1 branch auf dem alle arbeiten
- branches werden getaggt
- capability to rollback to a previous release
- problem unter produktion entdeckt - keine Zeit für Analyse
- Datensicherung: wiederherstellen nach Löschen von Dateien in einer Umgebung
- Verteilung
- Technische Übertragung auf mehrere Server
Scope
-3 environments: geht nicht mit weniger
- es muss eine Integrationsumgebung geben, damit das Deployment selber getestet werden kann
Regeln für den Umgang mit version control systemen
- Commit: ein funktionsfähiger und auslieferungsfähiger Stand, es darf kein Entwicklungsschritt committed werden
- Keine Commits zur Datensicherung
Probleme
- Korrekturlieferungen aus dev
- Keine selektiven Updates auf Verzeichnisebene
- Updates auf Verzeichnisebene: nein, da sonst Problem mit globalen Ressourcen, z.B. global locks, globale Prozessklassen
- Update immer auf live folder
- Keine selektiven Updates auf Änderungshistorie
- Es wird immer der aktuelle Stand des Repository übernommen, nicht ein bestimmter Revisionsstand
- Keine selektiven Updates auf Verzeichnisebene
- Disziplin:
- wenn derjenige, der in Integration testet, nicht wissen kann, was genau in der Lieferung enthalten ist, dann kann er nicht prüfen, ob er ggf. zu viele oder falsche Objekte erhalten hat
- Know How Auftrennnung: der Entwickler kennt Locks, der Tester kennt einen Testfall für Concurrency (nicht die Objekte, die das implementieren)
- Umgebungsspezifische Dateien
- Dürfen nicht committed werden
Deployment Process
Flowchart |
---|
jobs_dev [label="Jobs\nDevelopment Environment",fillcolor="lightskyblue"]
jobs_int [label="Jobs\nIntegration Environment",fillcolor="lightskyblue"]
jobs_prod [label="Jobs\nProduction Environment",fillcolor="lightskyblue"]
conf_dev [shape="ellipse",label="Configuration Items\nDevelopment Environment",fillcolor="violet"]
conf_int [shape="ellipse",label="Configuration Items\nIntegration Environment",fillcolor="violet"]
conf_prod [shape="ellipse",label="Configuration Items\nProduction Environment",fillcolor="violet"]
repo_dev [label="Repository\nDevelopment Branch",fillcolor="orange"]
repo_int [label="Repository\nIntegration Branch",fillcolor="orange"]
repo_prod [label="Repository\nProduction Branch",fillcolor="orange"]
jobs_dev -> conf_dev
jobs_dev -> repo_dev
conf_dev -> repo_dev
repo_dev -> jobs_int
jobs_int -> conf_int
conf_int -> repo_int
repo_dev -> jobs_prod
jobs_prod -> conf_prod
conf_prod -> repo_prod |
The deployments from test to integration to production make use of the following steps
- copy the configuration files from one stage to the other
- do not copy the files that are used exclusively for testing in your test environment
- do not copy mock files
Just copying files probably is not sufficient. There are differences in the configuration that have to be considered.
- host names for process classes are different
- Solution: Having a set of process classes on each stage that will not be part of the deployment procedure. This configuration will be handled directly on the specific stage.
- different input for file order sources
- Solution: Having different file order sources on each stage that will not be part of the deployment procedure. This configuration will be handled directly on the specific stage.
- different values for parameters, e.g. database connection strings are different
- Make use of include files.
- Make use of environment variables that will be substituted at run time.
Using a version control software for deployment
When deploying configuration files it is more than just copying files from a to b. When working with sources a version control software migth be helpful. With a version control system
- you can rollback to an older version if neccessary
- changes are documented
- You have to commit changes that are relevant for other environments like integration or production
- You can exclude test configuration files by not adding them to the repository
This table describes the deployment with Git and Subversion.
Subversion | Git | ||
---|---|---|---|
Find the Subversion documentation from | The full Git documentation can be found here | ||
Pre Conditions | |||
Subversion Server Find the documentation „how to install a subversion server“ from http://svnbook.red-bean.com/en/1.8/svn.serverconfig.html | Git central repository. You can create a central repository with Navigate to a folder live where you want to locate the Git repository e.g. c:\temp\git_repro\live
| ||
Subversion client installed on local machine | Git client installed on local machine | ||
Subversion Projectarchive | |||
All files to be deployes are located in the live folder of a JobScheduler installation. | Creating a working copy in your Please note that after the import the | Creating a working copy in your live folder from the git repository | |
| navigate to your config folder move all files to a temporary folder
move all files back to the
|
| The files are now in the Subversion project archive. You can verify this with the command
|
Delete the files from the live folder Execute the command checkout to get the files from the project archive to the live folder
| |||
Working with the project archive | You can have several working copies of the To synchronize changes in the working copy with the project folder there are two commands | You can have several working copies of the To synchronize changes in the working copy with the project folder there are three commands | |
Read the current version from the project archive (update) The update command reads changes from the project archive and merge them into the working copy.
| Read the current version from the repository (pull) git pull
| ||
The Please note that before commiting changes a update command is neccessary especially when a commit from another working copy has been executed.
| The push command writes committed changes from the working copy to the repository
| ||
Making changes | Changes are applied to the working copy by use of JOE or a text editor software. When all changes for certain approach has been done the changes can be commited to the project archive. Before carrying out the
| Changes are applied to the working copy by use of JOE or a text editor software.
| |
Deployment | There are two possible architectures to organize the deployment:
| ||
Consider environment specific parameters and configurations
When doing the deployment it is possible that parameter values are not valid in integration/production environments, e.g. the names of files, folders, printers etc.
Use environment variables that accept different values in development, integration and production environments. For
- File order sources
- Directories in file names
Code Block | ||
---|---|---|
| ||
<job_chain name="job_chain1">
<file_order_source directory="${file_input_dir}\input" regex=".*"/>
...
</job_chain> |
Use include files to specify parameter values:
Code Block | ||
---|---|---|
| ||
<order>
<params>
<include live_file="myorder.params.xml" node=""/>
..
</order> |
where the file myorder.params.xml could look like this:
Code Block | ||
---|---|---|
| ||
<params >
<param name="par1" value="value1"/>
<param name="par2" value="value2"/>
</params> |
Use different script include files for development, integration and production environments:
Code Block | ||
---|---|---|
| ||
<job order="yes">
<script language="shell">
<include live_file="include_scriptfile.sh"/>
</script>
<run_time />
</job> |
How to handle different include files for parameters and scripts
- create a folder include_files (parallel to the
live
folder) - create subfolders for dev, int and prod
- create the same subfolders under dev, int and prod as in the
live
folder - create the include files in the subfolders for dev, int and prod
- create a projectarchive wich contains the folder include_file
- create a working copy with the import, delete and checkout command (see above).
- When committing the include_files folder you should also commit the live folder (and vica versa) to have consistency between both folders.
- When deploying to int export the include_files/int folder to the live folder at int
- When deploying to prod export the include_files/prod folder to the live folder at prod
As you have a working copy in the live folder of dev, the include files from dev will be deployed when exporting the dev live folder. But with the second export from the include_files folder, the dev files will be overwritten with the correct version. An alternative approach is that also the live folder in dev is not a working copy but will be actualized with an export command from the dev working copy.
The quality of the development environment
When having some test configuration files in the development environment you should take care not to commit them to the repository. To achieve this, no add
command should be executed on these files. You also can add these files to an ignore list (available with Git and Subversion). You should take into account that each configuration item that has been committed to the repository will be deployed to the integration or production environments some time later.
Rollback to a previous version
To rollback to a previous version
Subversion Client | Git Client | ||
Install the Subversion Client on the computer where JobScheduler is located | Install the Git Client on the computer where JobScheduler is located | ||
Subversion Working Copy | Git Working Copy | ||
Create a working copy in your
| Create a working copy in your | ||
Please note that after the import the |
| ||
| The files are now in the Subversion repository. You can verify this with the command:
| The files are now in the Git repository. You can verify this by cloning the repository to another folder:
| |
Delete the files from the Execute the command
| |||
Creating Working Copies | You can have several working copies of the The following commands are available to synchronize changes to the working copy with the repository: | You can have several working copies of the The following commands are available to synchronize changes to the working copy with the repository: | |
Retrieve the current version from the repository ( The
| Retrieve the current version from the repository (
| ||
The Please note that before committing changes it is recommended to perform an
| The push command writes committed changes from the working copy to the repository:
| ||
Making Changes | Changes are applied to the working copy by use of JOE or a text editor. With all changes for a certain feature being developed and functionally tested the changes can be committed to the repository. Before carrying out the
| Changes are applied to the working copy by use of JOE or a text editor. Use this sequence of commands:
| |
Deploying Objects | There are two possible architectures to organize the deployment:
| ||
...