Operations Repo Structure#
BitOps expects an operations repo to be in the following structure, where each environment is in the root of the repository. Each environment then contains folders for each tool, and each tool has a
bitops.config.yaml. There are also directories that can contain before and after scripts for each tool.
├── production │ ├── ansible │ │ ├── bitops.after-deploy.d │ │ ├── bitops.before-deploy.d │ │ └── bitops.config.yaml │ ├── cloudformation │ │ ├── bitops.after-deploy.d │ │ ├── bitops.before-deploy.d │ │ └── bitops.config.yaml │ ├── helm │ │ ├── chartA │ │ │ └── bitops.config.yaml │ │ └── chartB │ │ └── bitops.config.yaml │ │ └── bitops.config.yaml │ └── terraform │ ├── bitops.after-deploy.d │ ├── bitops.before-deploy.d │ └── bitops.config.yaml └── dev ├── ansible │ ├── bitops.after-deploy.d │ ├── bitops.before-deploy.d │ └── bitops.config.yaml ├── cloudformation │ ├── bitops.after-deploy.d │ ├── bitops.before-deploy.d │ └── bitops.config.yaml ├── helm │ ├── chartA │ │ └── bitops.config.yaml │ └── chartB │ └── bitops.config.yaml │ └── bitops.config.yaml └── terraform ├── bitops.after-deploy.d ├── bitops.before-deploy.d └── bitops.config.yaml
These directories live at the root of an operations repository and are used to separate applications and environments. Depending on your use case, you may have an environment for
dev or these traditional environments may be further separated into individual services such as
test_serice_b. This pattern is preferential to having a branch for each environment as this allows the state of all your infrastructure to be managed from one location without merging potentially breaking an environment.
When running BitOps, you provide the environment variable
BITOPS_ENVIRONMENT. This tells BitOps what environment to work in for that run. A full CI/CD pipeline may call BitOps multiple times if it requires one environment to run as a pre-requisite for another.
Environment Directory Naming Convention#
Sometimes it is useful to have directories in your operations repo that are not deployable environments such as common scripts that can be referenced from any environment's before or after hooks.
BitOps allows you to name your environment directories whatever you want. However, to better reason about which directories are environments and which aren't a good convention is to prefix any non-deployable-environment directory with an underscore (e.g.
_default is special in BitOps. This directory is merged into your environment directory before deployment. You can control the default folder name through an environment variable
BITOPS_DEFAULT_FOLDER or through a BitOps configuration attribute
Within an environment directory are tool directories that group supported tools by name. Each of these directories is optional. For example, if your application only requires
terraform/ to execute, you do not need an
helm/ directory in your environment.
This directory is also where you put your infrastructure code associated with the respective tool.
Helm has additional capabilities here. You can nest multiple charts within the
helm/ directory of a given environment. BitOps will auto-detect and install these charts in alphabetical order.
Within a tool directory, you can optionally have a
bitops.before-deploy.d/ and/or a
bitops.after-deploy.d/. You can put arbitrary
*.sh scripts in here and they will be run before or after the tool executes. More for information see lifecycle docs.
If BitOps is reporting it can't find your scripts, make sure the scripts have execute permissions.
chmod +x bitops.before-deploy.d/* chmod +x bitops.after-deploy.d/*
Each tool is traditionally controlled with a set of CLI arguments. Instead of defining these CLI arguments within your pipeline configuration, these arguments can instead be defined using environment variables or within a
bitops.config.yaml file. While the core schema for this file is common between tools, the specific properties and environment variable equivalents vary from tool to tool. See BitOps Configuration for details.