Documentation

Variables

Enabling referencing in environments

Suggest Edits

Introduction

Variables in Bunnyshell are values defined in the platform, which are evaluated into Environment Variables within the running containers of environments created by Bunnyshell.

 

Encryption & Secrets

📘

All variables are encrypted in Bunnyshell, whether or not the Secret option is checked.

The encryption/decryption is performed with a key dedicated for each Organization.

Secret option

Variables can be marked as Secret so they will be obfuscated within the UI too.

Also you can save the obfuscated string in Git or in Templates, and only Bunnyshell will know to decrypt it and extract the plain value. The encryption and decryption works inside an Organization, so you cannot use the obfuscated string in another Organization than the one it was generated into.

In bunnyshell.yaml you can mark a variable as Secret by wrapping it in SECRET[]. For example if you have a database password my-password you will have to write in bunnyshell.yaml

...
    DB_PASSWORD: SECRET["my-password"]
...

 After saving the bunnyshell.yaml you will see the obfuscated string, something like

...
    DB_PASSWORD: ENCRYPTED[bXktcGFzc3dvcmQgZW5jcnlwdGVkIHdpdGggYSBrZXkK]
...

One important aspect is that you may need to wrap your text in single or double quotes and escape accordingly the single quotes ' or the double quotes " and the backslash \. Let's see some examples:

  • SECRET[abcd] - no need to be wrapped or escaped, but is equivalent with SECRET["abcd"] or SECRET['abcd']
  • SECRET[ab,cd] - must be wrapped because it contains the comma character, SECRET["ab,cd"] or SECRET['ab,cd']
  • SECRET[ab cd] - must be wrapped because it contains the space character, SECRET["ab cd"] or SECRET['ab cd']
  • SECRET[ab\cd] - no need to be wrapped or escaped, but is equivalent with SECRET["ab\cd"] or SECRET['ab\cd']
  • SECRET[ab"cd] - must be wrapped because it contains the double quotes character, SECRET['ab"cd'] or SECRET["ab\"cd"]
  • SECRET[ab'cd] - must be wrapped because it contains the single quotes character, SECRET["ab'cd"] or SECRET['ab\'cd']
  • SECRET["ab\\cd"] - the plain text will be ab\cd, with the first backslash you just escaped (unnecessarily) the second backslash; if you really want 2 backslashes, you need to add another backslash, like SECRET["ab\\\cd"] (one necessarily escaped and one not) or SECRET["ab\\\\cd"] (both escaped)
  • SECRET["ab\"cd"] - the plain text will be ab"cd, you escaped the middle "; if you actually want \ and " in the middle you have to add an escaped \ and an escaped ", like SECRET["ab\\\"cd"]

If you have a variable that actually starts with SECRET[ and ends with ] (or starts with ENCRYPTED[ and ends with ]), any character case (upper, lower or combined like sEcReT[), completely unrelated to Bunnyshell secret expressions, you can keep the original value without Bunnyshell trying to parse it, by making it a Bunnyshell Secret. For example SECRET[my data here] should be SECRET["SECRET[my data here]"] and after saving it will look something like ENCRYPTED[cipherText], but when deploying Bunnyshell will use for the variable the original string SECRET[my data here]. The only disadvantage is that you must make it a Bunnyshell Secret and you will see it obfuscated in UI.


Where SECRET[] is allowed

  • project variables
  • templateVariables
  • environmentVariablesGroups
  • environmentVariables
  • Docker-compose Components, DockerImage Components and StaticApplication Components
    • build arguments
    • build secrets
  • Docker-compose Components
    • pod.init_containers[].environment
    • pod.sidecar_containers[].environment

 

Inheritance & override

There are 4 scopes at which variables can be defined, from higher to lower:

  1. Project
  2. Environment
  3. Environment Variable Groups
  4. Component

Variables and their values are inherited from the Project scope into the Environment scope, and then into the Component scope.

Overriding values is possible by defining the same variable with a different value at a lower scope.

Example for Environment scope overriding the Project scope
Let's say we have a variable called APP_VERSION defined at Project level with value 1.1.
We define the same variable with a different value at an Environment level: 2.0.
When injected in each of the containers belonging to all the Components of the respective Environment, the value of APP_VERSION will be 2.0.

The same way, Component scope will override both Environment scope, as well as Project scope.

🚧

So

Environment variables override Project variables.

Component variables override both Project and Environment variables.

 

Project Variables

Project variables are automatically inherited in all new environments from a specific project. These will be available at runtime, as well as during builds and deploys.

Project variables are unique for the entire project and their values can be overridden both at the environment and component level.

Creating a Project Variable

To create project variables, the first thing you have to do is access the Projects screen:

  1. Click on the project name in the upper-right corner of the Bunnyshell interface.
  2. Select View all projects.
  3. Click on your project's Settings button.
  4. On the left-side menu, click Project variables.
  5. Click Create variable.
  6. Enter a name and a value and for your variable.

📘

When choosing a name for your variable, make sure you take into account the following requirements:

  • Variable names should use only alphanumeric characters, underscore, dash and dot character.
  • Variable names should not begin with a digit.
  • Variable names should not begin with BNS_.
  • Variable names cannot contain more than 255 characters.
  • Variable names cannot contain less than 3 characters.
  1. Choose whether your variable should be a secret one or not.
  2. Finally, click the Create variable button.

Editing or Deleting a Project Variable

  1. Go to the Project variables screen.
  2. Click the Options button corresponding to the variable in question.
  3. Choose the desired action: Edit or Delete.

 

Environment Variables

Environment variables are automatically inherited in all applications, services, and databases inside the Environment. These are available at runtime, as well as during builds and deploys.

Environment variables are unique for the entire environment and their values can be overridden only at the component level.

Creating an Environment Variable

To create environment variables, the first thing you have to do is access the Environment View screen:

  1. Select the environment for which you want to add a variable.
  2. Click on your environment's Settings button.
  3. On the left-side menu, click Environment variables.
  4. Click Create variable.
  5. Enter a name and a value and for your variable.

📘

When choosing a name for your variable, make sure you take into account the following requirements:

  • Variable names should use only alphanumeric characters, underscore, dash and dot character.
  • Variable names should not begin with a digit.
  • Variable names should not begin with BNS_.
  • Variable names cannot contain more than 255 characters.
  • Variable names cannot contain less than 3 characters.
  1. Choose whether your variable should be a secret one or not.
  2. Finally, click the Create variable button.

Editing or Deleting an Environment Variable

  1. Go to the Environment variables screen.
  2. Click the Options button corresponding to the variable in question.
  3. Choose the desired action: Edit or Delete.

Environment Variables Groups

Environment variables groups are similar to regular Environment Variables.

Check the dedicated documentation page on how they work and how to use them.

Component Variables

Component variables are available:

These variables are unique for the component where they are defined and cannot be overridden further.

Creating a Component Variable

To create Component variables, the first thing you have to do is access the Environment View screen:

  1. Select an Environment.
  2. Choose a Component.
  3. From the left-side menu, navigate to the desired component.
  4. Click Actions, and then Variables.
  5. You will see the Variables screen. From there, click Create variable.
  6. Enter a name and a value and for your variable.

📘

When choosing a name for your variable, make sure you take into account the following requirements:

  • Variable names should use only alphanumeric characters, underscore, dash and dot character.
  • Variable names should not begin with a digit.
  • Variable names should not begin with BNS_.
  • Variable names cannot contain more than 255 characters.
  • Variable names cannot contain less than 3 characters.
  1. Choose whether your variable should be a secret one or not.
  2. Finally, click the Create variable button.

Editing or Deleting a Component Variable

  1. Select an Environment.
  2. Choose a Component.
  3. From the left-side menu, navigate to the desired component.
  4. Click Actions, and then Variables.
  5. You will see the Variables screen. From there, click Delete from within the Actions (3-dots) menu.

Updated 4 months ago