Configuration Mapping

Configuration Mapping

The local and remote configuration will trigger a task execution based on each unique declaration of context and target, using the corresponding default task tasksRunLocal.tsk and tasksRunLocal.tsk.

context  target  deployHost
remote   UAT     vm.example.com
local    UAT     vm.example.com
remote   PROD    vm.example.com
local    PROD    vm.example.com

Customer tasks can be defined for directories customLocal and customRemote respectively, or custom if shared.

context    target  deployTaskOverride
local      DOCKER  docker-compose-test.tsk
remote     UAT     on-premise-deploy.tsk
remote     PROD    on-premise-deploy.tsk
container  PUSH    publish-production-ertefact.tsk

Note that container override tasks are made available in the customRemote directory.

Execution Engine

Execution Engine

To alleviate the burden of argument passing, exception handling and logging, the execution engine has been provided. The execution engine will essentially execute the native interpretive language (PowerShell or bash), line by line, but each execution will be tested for exceptions (trivial in bash, significantly more complex in PowerShell).

Where is it used

In all places using .tsk files, i.e. build, package, wrap and deploy. The following operations are available to all tasks, however, some are more applicable to specific processes, see Build, Local and Remote task execution for more details of how these can be used.

Operations

The following operations are provided to simplify common tasks.

Notes on EXCREM use, the properties are similar to those used for remote tasks, where the minimum required is the host, if other properties are not used, must be set to NOT_SUPPLIED, i.e.

deployHost=localhost
remUser=NOT_SUPPLIED
remCred=NOT_SUPPLIED
remThb=NOT_SUPPLIED

Windows only

The following operations are only available in PowerShell version

Common Variables

These are automatically set at both build and deploy time.

Build-time Variables

These are automatically set at execution start-up

See also Environment and Global Variables.

Deploy-time Variables

Environment Variables

Environment Variables

Due to inconsistencies between Windows and Linux handling of environment variables, these have been divided between environment variables that are set before calling an entry script to alter the behaviour of CDAF, and environment variables that are set within bash scripts to make them globally available.

Control Variables

The following environment variables are available to control the behaviour of CDAF

Global Variables

These variables are available to child scripts, custom scripts and task execution engine, see also Build-time Variables.

See also Build-time Variables.

Image Registry

These override Solution Properties properties. They are used to push the image created by dockerBuild to pull a base image from a private registry.

These override Solution Properties properties. They are used to push the image created by imageBuild to push to a private registry.

These override Solution Properties properties. They are used to push the image created by dockerPush to push to a private registry.

Solution Properties

Solution Properties

CDAF.solution : file to identify a directory as the automation solution directory where the key configuration files are placed. This file is used as the bases of the manifest.txt file while is included in the resulting CI artefact package.

See solution/CDAF.solution in CDAF automation directory.

Solution Properties

Environment Variable Substitution

The following properties can be used in place of environment variables

Image Registry

These properties are used to push the image created by dockerBuild to pull a base image from a private registry. These can be overriden by Environment Variables.

These properties are used to push the image created by imageBuild to push to a private registry. These can be overriden by Environment Variables.

These properties are used to push the image created by dockerPush to push to a private registry. These can be overriden by Environment Variables.

Git Clean-up Properties

To clean-up Git branches and docker images, the following properties are used.

Extended Processes

Extended Processes

Optional Build Processes

By placing these files in your solution root, the processes will execute as described

Optional Package Processes

By placing these files in your solution root, the processes will execute as described

Feature Branch Execution

Feature Branch Execution

Place feature-branch.properties in your SOLUTIONROOT to allow dynamic delivery execution, based on Git Branch name. This capability is limited to entry.sh/entry.bat/entry.ps1, which are Git aware, and the recommended loose coupling entry scripts for CDAF.

# Separate environments for features and bugs
feature=DEV1
bugfix=DEV2

# Hotfixes deploy to all environments
hotfix=DEV1
hotfix=DEV2

See CDAF Samples for complete implementations in Linux and Windows.

Sensitive Data Strategies

Sensitive Data Strategies

Loose Coupling

A key approach to support the principle of automation execution in a local desktop context, is the use of environment variables. It’s important to remember that environment variables do not necessarily need to be persisted, i.e. stored unencrypted on disk, it’s the global availability of the variable that makes it an environment variable.

context  target  databaseFQDN        dBpassword
local    TEST    db1.nonprod.local   $DB1_PASSWORD
local    UAT     db2.nonprod.local   $DB2_PASSWORD
local    PROD    cluster.prod.local  $PRD_PASSWORD

Variable Expansion

Variables can be referenced in preoperties files (see [Configuration Management][mydoc_basics_configuration_management]) or CDAF.solution file and then expanded at deploy time into variables or files using ASSIGN, PROPLD or DETOKN in the execution engine.

Encrypted Files

This approach is to allow secrets in a file to be stored in source control. Encryption key for Windows is an EAS key, while for Linux it’s a GPG key. This approach is used when there are a large number of secrets to cater for, and therefore only the key needs to be managed as a secret.

In early generations of secret management, the secrets would be stored as persistent environment variables, however all modern toolsets provide an encrypted store which can load secrets as environment variables.

See the DECRYP & DETOKN operations in the execution engine for guidance on usage.

Cloud Storage Integration

Toolset providers who also supply public cloud provide integration to their secret storage offerings, while these can be convenient, this does couple your automation to toolset and makes the execution of locally challenging.

Legacy Features

Legacy Features

Remote Deployment

Machine to machine deployments are increasingly uncommon, as local agents/runners are readily available, making on-premise deployments from the build server an infrequent use case. While there is no plan to deprecate this capability, it’s complexity makes local testing i.e. shift-left complicated, especially in windows. For CDAF configuration, see Remote Tasks.

Windows Remote PowerShell

This approach uses the local host for both target (CD) and build (CI) execution. Provision the host with both roles

.\automation\provisioning\mkdir.ps1 C:\deploy
.\automation\provisioning\CredSSP.ps1 server

.\automation\provisioning\trustedHosts.ps1 *
.\automation\provisioning\CredSSP.ps1 client

Linux SSH

Generate PKI key and public certificate, and perform a loop-back connection to local host to place the public certificate in the authorised hosts configuration.

.\automation\provisioning\agent.sh deployer@localhost

Symetric Encryption

With the implementation of 12-Factor applications, secret management in files is less common, and the storage of encrypted files in source control for subsequent decryption is now uncommon. While this capability is not planned for deprecation, it is recommended to use sensitive data strategies instead.

Variable Validation

Variable Validation

There are 5 rules available, two for plain text and three for secrets. When validating a secret against a known MD5 value, either a literal or variable can be supplied. See VARCHK in the execution engine operations

# Plain text values
OPT_ARG                                # Optional plain text
terraform_version=required             # Required plain text

# Secret values
TERRAFORM_TOKEN=optional               # Optional secret
TERRAFORM_TOKEN=secret                 # Required secret
TERRAFORM_TOKEN=$TERRAFORM_TOKEN_MASK  # Required secret verified against supplied SHA-256 value