The Configuration as Code feature is designed to give you the benefits of source control, branching, reverting, and pull requests while being able to use your tool of choice to manage your processes and non-sensitive variables. While it has many benefits, there are some unsuitable use cases and scenarios. This document will describe each one as well as provide alternatives.
Core design decision
The core design decision is each project in each space has a unique folder in a git repository. A git repository can store several projects across several spaces or store a single project in a single space. But, each project must have a unique folder in a git repository because of all the scaffolding data referenced by a project.
That scaffolding data includes (but is not limited to):
- Environments
- Tenant Tags
- Worker Pools
- Feeds
- Step Templates
- Channels / Lifecycles
That data is not stored in source control because it is shared across multiple projects.
An error will occur when Octopus Deploy attempts to load a process from source control with one or more of those items missing. You’ll be unable to create releases until those errors are resolved.
Syncing multiple instances
The configuration as code feature is not designed to allow two or more projects on different instances to point to the same folder. We’ve seen our users attempt to use Configuration as Code to keep the deployment processes in sync across multiple instances. That scenario is unsupported.
While it may work initially, it will be harder and harder to manage over time. You will need to keep all the scaffolding data in sync across multiple instances. That is easier said than done. Step templates will be the most difficult, as having the same step template on all instances, the version has to match. Otherwise, you’ll have to worry about settings such as parameters, scripts, package versions, feeds, and more.
Configuration as Code currently supports storing the deployment process and non-sensitive variables for a project in the Git repo. It does not store or runbook processes or sensitive variables.
Typically, having two instances results from splitting an Octopus Deploy instance by environment (one instance has Dev/Test the other has Staging/Prod), by Tenant (one instance has test tenants, the other has customers), or both. Pointing multiple instances at the same folder will only work if they are all exactly the same forever.
Octopus Terraform Provider
Use the Octopus Terraform Provider to keep multiple instances in sync. Use Terraform’s variable functionality to manage the differences between the instances. For example, have a variable for environment scoping. One instance populates the environment list with “Test” while the other populates it with Staging and Production.
You will still need a process to keep step templates in sync.
The downside to this approach is you’ll be unable to use the Octopus Deploy UI to manage your deployment processes. In addition, you’ll need to convert your existing deployment process into Terraform manually. The files generated by Configuration as Code has a similar syntax as the Terraform provider, but it is not a 1:1 match.
Separate folders for each instance
Another alternative is each instance points to a unique folder in the same GitHub repo. For example, if you had a Developer instance and a Production instance.
- .octopus/project-a/dev-instance
- .octopus/project-a/production-instance
Use a file diff tool, Beyond Compare, Meld, WinMerge, or KDiff, to manually copy specific changes between the two directories. Any instance-specific configuration, such as environment scoping, worker pools, or feeds, would be excluded.
You will still need a process to keep step templates in sync.
The downside to this approach is it is a manual process and prone to error.
Project templating
The configuration as code feature is not designed to allow two or more projects on the same space to point to the same folder. We’ve seen our users attempt to use Configuration as Code as project templating. This scenario is unsupported.
While it may work for the first couple of projects, as all the necessary scaffolding data is there because the projects will be in the same space. However, projects will have subtle differences. Those differences include:
- Packages to deploy
- Target roles
- Worker pools
- Tenant Tags
- Package Feeds
You will find projects are constantly overwriting each other.
One option is to have a single git repo for all your projects, with each project saved to a unique folder in the repository. You could then use a file comparison tool to copy changes between projects. That scenario will not scale well. Branch naming conventions would need to be strictly enforced if you configured 50 projects to save to the same git repo. The number of possible branches would exponentially grow with each added project. The chances of a person selecting the wrong branch will subsequently increase. And manually copying changes via a file comparison tool is error-prone and time-consuming.
Having a branch per project will partially solve the problem of the subtle differences, but it will be very time-consuming to sync any “main” branch changes with the project branches. You will need to manually sync all the branches or create and maintain a process to handle the syncing.
Configuration as Code is an all-or-nothing feature. You’ll be unable to say manage “some of my deployment process” using Configuration as Code. It is the entire deployment process or nothing.
Octopus Terraform Provider
Use the Octopus Terraform Provider to create a deployment process template. Use Terraform’s variable functionality to manage the different projects. For example, have a variable for target roles; one project has OctoFX-WebApi while another uses RandomQuotes-WebApi.
One advantage to this approach is the flexibility to decide what resources are managed by the Terraform Provider and what resources are managed by users in the Octopus UI. The downside to this approach is you’ll be unable to use the Octopus Deploy UI to manage your deployment processes. In addition, you’ll need to convert your existing deployment process into Terraform manually. The files generated by Configuration as Code has a similar syntax as the Terraform provider, but it is not a 1:1 match.
Help us continuously improve
Please let us know if you have any feedback about this page.
Page updated on Monday, September 16, 2024