Lifecycle Fix

Did you ever have one of those changes where you thought you tested every use case? Well I just did. I thought I was creating new lifecycles with all their phases, but it turns out the lifecycles in question already existed and I completely missed that.

This release fixes #26 which prevents new lifecycles from being created unless the overwrite phases parameter was set to NeverCloneLifecyclePhases.

Better support for instances with completely different environments

One of the common reasons for a person to have separate instances is to have separate environments. For example, one instance has Dev/Test and the other instance has Stage/Prod.

This release makes it much easier to support that scenario with improvements to

• Leaving the scoping on existing steps in your runbook and deployment process alone
• Default values for variable creation
• Picking which channels to clone
• Include / Exclude parameters for CloneSpaceProject script

Cloning Deployment Process

With instances with different environments, you'll want to clone any new steps from the deployment or runbook process over. Even those scoped to environments. For example, this is my deployment process.

I want to include step 7, so I'd set ProcessEnvironmentScopingMatch to IgnoreMismatch. That will result in:

However, if I were to update the destination process to be:

And then re-run the clone that scoping would be removed:

A new option "IgnoreMismatchOnNewLeaveExistingAlone" has been added to the scoping parameters, ProcessEnvironmentScopingMatch, ProcessChannelScopingMatch, and ProcessTenantTagScopingMatch. That will still clone the step over without scoping the first time it was found, but it will leave the scoping alone on subsequent runs. Everything else will be updated.

Cloning Variables

With instances with different environments, the chance of variable overlap is small. Especially variables scoped to environments. For example, the variables associated with this project:

When I clone those over, I want them all to have a default value that I know must be replaced. A new option, AddNewWithDefaultValue has been added to the OverwriteExistingVariables parameter. Combined with IgnoreMismatch for VariableEnvironmentScopingMatch and the variables will be:

Any variable updates will be ignored.

If I add a new variable to the source:

That new variable will be added with the default value:

Channel Filter

A new channel filters has been added to let you control which channels to include rather than including all the channels. Instances with separate environments will most likely have different lifecycles and channels.

Exclude / Include Parameters on CloneSpaceProject script

Before you could only provide a list of environments, tenants, targets, workers, and channels to exclude. But...often times the list to exclude is longer than the list to include. So the include parameters were added.

Please note: These parameters are either-or. You can have either an include value set or an exclude value set. It cannot be both.

Additional Parameters

There are new parameters in each script.

CloneSpace:

• CloneProjectLogos: Set to true to clone logos on projects, set to false to skip. Default is true.
• CloneTenantLogos: Set to true to clone tenant logos, set to false to skip. Default is true.
• ProcessTenantTagScopingMatch: Similar to other scoping parameters, but for tenant tag scoping on deployment or runbook processes.
• VariableTenantTagScopingMatch: Similar to other scoping parameters, but for tenant tag scoping on variables.
• InfrastructureTenantTagScopingMatch: Similar to other scoping parameters, but for tenant tag scoping on Accounts and Deployment Targets.

CloneLibraryVariableSet:

• VariableTenantTagScopingMatch: Similar to other scoping parameters, but for tenant tag scoping on variables.

CloneSpaceProject:

• CloneProjectLogos: Set to true to clone logos on projects, set to false to skip. Default is true.
• CloneTenantLogos: Set to true to clone tenant logos, set to false to skip. Default is true.
• ProcessTenantTagScopingMatch: Similar to other scoping parameters, but for tenant tag scoping on deployment or runbook processes.
• VariableTenantTagScopingMatch: Similar to other scoping parameters, but for tenant tag scoping on variables.
• InfrastructureTenantTagScopingMatch: Similar to other scoping parameters, but for tenant tag scoping on Accounts and Deployment Targets.
• EnvironmentsToInclude: A list of environments to include in the clone. Useful when the list of items to exclude is much longer than the list of items to include. Cannot have a value for both Include and Exclude parameters. Must be either-or.
• TargetsToInclude: A list of targets to include in the clone. Useful when the list of items to exclude is much longer than the list of items to include. Cannot have a value for both Include and Exclude parameters. Must be either-or.
• TenantsToInclude: A list of tenants to include in the clone. Useful when the list of items to exclude is much longer than the list of items to include. Cannot have a value for both Include and Exclude parameters. Must be either-or.
• ChannelsToInclude: A list of channels to include in the clone. Useful when the list of items to exclude is much longer than the list of items to include. Cannot have a value for both Include and Exclude parameters. Must be either-or.
• ChannelsToExclude: A list of channels to exclude in the clone. Useful when the list of items to include is much longer than the list of items to exclude. Cannot have a value for both Include and Exclude parameters. Must be either-or.

ProjectSyncer:

• CloneProjectLogos: Set to true to clone logos on projects, set to false to skip. Default is true.
• ProcessTenantTagScopingMatch: Similar to other scoping parameters, but for tenant tag scoping on deployment or runbook processes.
• VariableTenantTagScopingMatch: Similar to other scoping parameters, but for tenant tag scoping on variables.

Default Step Template Control Type

In Octopus 2021.x and later the control type parameter became required for all step templates. Previously, if it wasn't present the Octopus UI would default to singlelinetext. The workaround is to update each step template manually.

This release will set the control type parameter to SingleLineText when the parameter doesn't have that specified in the step template.

New Lifecycle Phase Clone Option

Some of the users of the space cloner want to use it to keep two instances in sync with completely separate environments. This poses a problem with lifecycles during the initial sync. Prior to this release if the lifecycle wasn't there the space cloner would clone it, and it would attempt to clone all the phases in that lifecycle. Except...all the environments didn't exist for all the phases. So the clone would fail. The workaround was to pre-create the lifecycles with the phases you wanted.

This release adds an additional option to the OverwriteExistingLifecyclesPhases parameter. You can pass in True, False or NeverCloneLifecyclePhases.

• True: Always clones lifecycle phases
• False: Only clones lifecycles phases when the lifecycle doesn't exist
• NeverCloneLifecyclePhases: What it says on the tin, Never clone lifecycle phases, ever.

This release also fixes issue #22.

Fixing some bugs with the new "object must exist" checks.

This release fixes the following issues:

#19 - Invalid Operation when running CloneSpace.ps1
#21 - Script Modules Cause Project Cloning Error

Thanks to @iguyking for submitting the PR for the fix to #19!

Write out except message

In the core Data Adapter functionality it was trapping the error message, returning the status code, but never writing out the exception. For debugging purposes, this was causing all kinds of confusion. Now it writes out the exception message. Hopefully, this can eliminate some back and forth and so we can get to the root cause.

Scope Mismatch Options

Version 3 of the space cloner is ready for use! Major features added:

• Scoping Mismatch
• Deployment Process Cloning Control
• Error Handling

Scoping Mismatch Control

My source instance has Development, Test and Production but my destination instance has Test and Production. One of my variables is scoped to Development and Test. What should happen?

Up until this release, this is what would happen when a scope mismatch was found. Imagine you had this variable set:

When Development wasn't found the space cloner would exclude that environment from the variable value and proceed on.

That worked fine when the variable had other scoping to rely on. It got interesting when variables were only scoped to Development. And not everyone wants that behavior. You now have the ability to control what is happening.

You can tell it to skip when unless an exact match is found (SkipUnlessExactMatch):

Or skip unless a partial match is found (SkipUnlessPartialMatch)

Or, you can tell it to error out with ErrorUnlessExactMatch or ErrorUnlessPartialMatch.

The options are:

• ErrorUnlessExactMatch: An Error will be thrown unless an exact match on the scoping is found. For example, the source has Development and Test, an error will be thrown unless the destination has Development AND Test.
• SkipUnlessExactMatch: The item (variable, account, step, etc.) will be excluded or skipped unless an exact match is found. For example, the source has Development and Test, the item will be skipped unless Development AND Test.
• ErrorUnlessPartialMatch: An Error will be thrown unless a partial match on the scoping is found. For example, the source has Development and Test, an error will be thrown unless the destination has Development OR Test.
• SkipUnlessPartialMatch: The item (variable, account, step, etc.) will be excluded or skipped unless a partial match is found. For example, the source has Development and Test, the item will be skipped unless Development OR Test.
• IgnoreMismatch: The item will be cloned regardless of matching.

The new command line arguments are:

Process Scoping

• ProcessEnvironmentScopingMatch: How to handle when a step in a deployment or runbook process is scoped to 1 to N Environments in the source but not all environments are in the destination. Default is SkipUnlessPartialMatch.
• ProcessChannelScopingMatch: How to handle when a step in a deployment or runbook process is scoped to to 1 to N Channels in the source but not all Channels are in the destination. Default is SkipUnlessPartialMatch.

Variable Scoping

• VariableChannelScopingMatch: How to handle when a variable in a project or library variable set is scoped to 1 to N Channels in the source but not all environments are in the destination. Default is SkipUnlessPartialMatch.
• VariableEnvironmentScopingMatch: How to handle when a variable in a project or library variable set is scoped to 1 to N Environments in the source but not all environments are in the destination. Default is SkipUnlessPartialMatch.
• VariableProcessOwnerScopingMatch: How to handle when a variable in a project or library variable set is scoped to 1 to N Deployment or Runbooks in the source but not all environments are in the destination. Default is SkipUnlessPartialMatch.
• VariableActionScopingMatch: How to handle when a variable in a project or library variable set is scoped to 1 to N Deployment Steps in the source but not all environments are in the destination. Default is SkipUnlessPartialMatch.
• VariableMachineScopingMatch: How to handle when a variable in a project or library variable set is scoped to 1 to N Deployment Targets in the source but not all environments are in the destination. Default is SkipUnlessPartialMatch.
• VariableAccountScopingMatch: How to handle when a variable in a project or library variable set is scoped to an Account in the source but not all environments are in the destination. Default is SkipUnlessExactMatch.
• VariableCertificateScopingMatch: How to handle when a variable in a project or library variable set is scoped to an Certificate in the source but not all environments are in the destination. Default is SkipUnlessExactMatch.

Infrastructure Scoping

• InfrastructureEnvironmentScopingMatch: How to handle when a Deployment Target or Account is scoped to 1 to N Environments in the source but not all environments are in the destination. Default is SkipUnlessPartialMatch.
• InfrastructureTenantScopingMatch: How to handle when a Deployment Target or Account is scoped to 1 to N Tenants in the source but not all environments are in the destination. Default is SkipUnlessPartialMatch.

You can read more here on how this all works:
https://github.com/OctopusDeployLabs/SpaceCloner/blob/master/docs/HowScopeCloningWorks.md

Deployment Process Cloning Control

Up until this release if a step was found on the destination instance but not on the source it would be left as-is. Some users who wish to have a single source of truth found this to be suboptimal (especially when they deleted steps).

A new command line option has been added to make this easier to control.
ProcessCloningOption -> The two options are KeepAdditionalDestinationSteps or SourceOnly. The default is KeepAdditionalDestinationSteps. When the option is set to SourceOnly any steps found on the destination but not on the source will be removed.

Better Error Handling

There have been a lot of instances where a required field was not checked prior to saving. The space cloner would then call the API and a 400 bad request would happen. Required fields are now checked; if something is required and it isn't found the space cloner will stop. You'll be informed that the field is required in the log as well as the script console.

Nancy to .NET Core Strikes Again

In earlier versions of Octopus Deploy a double slash was fine in the API calls. With .NET core rest API conversion that is no longer allowed. There was one repo call that still had a leading slash when it shouldn't. Removing that (and updating the comparison logic).

Better handling for whitespace

For whatever reason, some instances have whitespace around names when they shouldn't which is throwing off the matching logic. This release fixes that.

Adding Certificate support

When the space cloner was originally created certificate support was in the list of items to clone. But there were a lot of hurdles to get through and I decided at the time to skip certificate cloning.

Now that space cloner has matured and more functionality has been added, I decided to revisit that decision. A number of improvements to the space cloner made it possible to clone certificates. Most notably, being able to download files (something I had to solve for packages and images).

Certificate cloning has now been added. But there are a few caveats to it:

• Like other parameters the CertificateToClone parameter accepts multiple items. But it does not accept all or wild cards. You must specify the certificate name you want to clone.
• Certificates are downloaded as-is and uploaded as-is. If the certificate has a password, you must supply a password. That is accomplished by this format in the CertificateToClone parameter: [CertName]::[CertPassword] for example MyCertName::MyCertPassword.

Certificates are only cloned when one of these conditions are met:

• Certificate does not exist in the destination
• Certificate thumbprint doesn't match
• Certificate has been archived in the destination

If none of those conditions are met then the certificate is left alone.

Other Items Of Note

• Support for 2021.3 was added
• A guard clause was added to prevent the cloning of projects that are version-controlled. That will be removed after Config as Code is GA and I know what the final objects will look like.