Skip to content

Latest commit

 

History

History
90 lines (77 loc) · 7.39 KB

deploy-types-and-environments.md

File metadata and controls

90 lines (77 loc) · 7.39 KB
Raw

Deploy Types and Environments

Deploy Types and Environments are meant to form a hierarchy of your deploy targets, with Deploy Types at the higher level. A Deploy Type is a class of Environments. For instance, you might have multiple development Environments, each with different names, and put them all under the "dev" Deploy Type. You might also have multiple production Environments (e.g., in different cloud regions), but classify them all as part of the "prod" Deploy Type.

The recommended pattern is to define Deploy Types first, and then refine as needed by defining specific Environment within those Deploy Types. All of the common configuration for all the Environments of that Type is specified on the Deploy Type, and then you can override these for specific Environments if you need to. Often, you'll find you don't even need to define the Environments if they can all share the same configuration. In particular, when you use dynamic configuration (see the relevant section of the REAMDE), you can have shared configuration functions that compute configuration values based on the environment name (among other things).

ValidEnvs

Deploy types can be configured with an optional parameter valled validEnvs. This is used (in all but one case) to validate that the specified environment name is allowed for a given deploy type. The only time this doesn't apply is when the environment name and the deploy type are both given explicitly on the command line (using the --env option and the positional argument, respectively). This is described as the "User specified" strategy (strategy #1) under the "Naming" section below.

The validEnvs property can take on any of the following forms:

  • A single string-typed value indicating the one and only environment name that is valid for this deploy type. Environment names must match exactly (case-sensitive) in order to be considered valid.
  • A regular expression (e.g., a regexp literal or the results of calling the RegExp function). Environment names are tested against the regular expression and are considered valid only if they pass.
  • A function, which will be invoked with the environment name as the only argument; the environment name is considered valid if and only if the function returns a truthy value.
  • An array whose elements are any mixture of the above. The environment name is considered valid if any only if it tests as valid against at least one of the elements in the array. Note than an empty array will result in no environment names testing as valid.

If the validEnvs property is not specified for a deploy type, then any environment name is considered valid for that deploy type.

Naming

One of the goals of sirocco is to limit the amount of copy-paste you need to do to configure deploys for different environments. For instance, you shouldn't need a different command for each environment you want to deploy, sirocco should be smart enough, in most circumstances, to figure out which environment you're targeting. There are a number of strategies employed to determine the Environment and Deploy Type. In order, these strategies are:

  1. User specified: If you have explicitly specified both the Deploy Type and the Environment on the command line (the former with the DEPLOY-TYPE positional argument and the latter with the --env option), then these are used exactly as given. In particular, the given Environment name is not validated against the Deploy Type's validEnvs property.
  2. Specified environment: If the Environment name has been given (with the --env option), but not the Deploy Type, then the Deploy Type is taken from the Environment name as everything up to (but not including) the first dash character. If there are no dash-characters, then the entire Environment name is used as the Deploy Type. Note that the Environment name is still used as given in both cases. E.g., if you specifiy --env dev-123, then the Deploy Type is "dev" and the Environment name is "dev-123". If you speciiy --env qa, then the Deploy Type and the Environment name are both "qa".
  3. From Env Var: If the --env option is not given, then the Environment name is taken from the CI_ENVIRONMENT_NAME environment variable (see note 1, below). The Expected Deploy Type is taken from the start of this Environment name up to but not including the first slash character ("/", see note 2). If the DEPLOY-TYPE is specified on the command line, then it must match the Expected Deploy Type determined in this way. If it is not specified, then the Expected Deploy Type is used as the Deploy Type.
  4. Branch Deploy Type: If the DEPLOY-TYPE is given on the command line (but the --env is not), and it is defined as a branch-deploy-type (see note 3), then sirocco will attempt to determine the current version control branch name (see note 4). If it is able to do so, then the Environment name is contructed by joining the branch name onto the specified Deploy Type with a dash character ("-"). Note that the branch name will be converted to all lower-case, and any slash characters ("/") will be replaced with dashes ("-") before joining.
  5. Single Environment Deploy Type: If none of the above strategies were successful (including if no branch name could be determined in the "Branch Deploy Type" strategy), then the DEPLOY-TYPE positional argument must be specified on the command line, and that deploy type must be configured with a validEnvs property defining a single valid environment name (see note 5), which is then used as the implied Environment name.

If none of the above strategies were able sucessfull, then the command will fail: you'll need to change your configuration or specify additional information on the command line.

Notes:

  1. In the "From Env Var" strategy, the name of the environment variable to read from can be overridden with the --env-name-env-var configuration, "CI_ENVIRONMENT_NAME" is the default value, which is compatible with gitlab-ci.
  2. Note that the character used to split the Deploy Type from the environment name in the "From Env Var" strategy (a slash "/"), is different from that used by the "Specified environment" strategy (a dash "-"). This is based on the way that certain CI environments (notably gitlab-ci) format nested environments. However, the character for the "From Env Var" strategy only defaults to "/", it can be overriden with the --env-name-separator configuration.
  3. The --branch-deploy-type configuration can be used to specify any number of Deploy Types that are considered branch-deploy-types, meaning that they will be subject to the Branch Deploy Type strategy above (if none of the preceding strategies work). By default, only "dev" is considered to be a branch-deploy-type.
  4. Currently only git is supported for determining branch names; it is taken from the repository of your current working directory by git-branch.
  5. The specified Deploy Type must be defined in your sirocco configuration, and it must have a validEnvs property defined which is either a string value or an array containing exactly a single string value. E.g., we're not going to look at a RegExp and try to determine if there is only a single possible value that it allows.