|
| 1 | +#Terraform template-wide variables |
| 2 | + |
| 3 | +In Coder, Terraform templates offer extensive flexibility through template-wide |
| 4 | +variables. These variables, managed by template authors, facilitate the |
| 5 | +construction of customizable templates. Unlike parameters, which are primarily |
| 6 | +for workspace customization, template variables remain under the control of the |
| 7 | +template author, ensuring workspace users cannot modify them. |
| 8 | + |
| 9 | +```hcl |
| 10 | +variable "CLOUD_API_KEY" { |
| 11 | + type = string |
| 12 | + description = "API key for the service" |
| 13 | + default = "1234567890" |
| 14 | + sensitive = true |
| 15 | +} |
| 16 | +``` |
| 17 | + |
| 18 | +Given that variables are a |
| 19 | +[fundamental concept in Terraform](https://developer.hashicorp.com/terraform/language/values/variables), |
| 20 | +Coder endeavors to fully support them. Native support includes`string`, |
| 21 | +`number`, and`bool` formats. However, other types such as`list(string)` or |
| 22 | +`map(any)` will default to being treated as strings. |
| 23 | + |
| 24 | +##Default value |
| 25 | + |
| 26 | +Upon adding a template variable, it's mandatory to provide a value during the |
| 27 | +first push. At this stage, the template administrator faces two choices: |
| 28 | + |
| 29 | +1._No`default` property_: opt not to define a default property. Instead, |
| 30 | + utilize the`--var name=value` command-line argument during the push to |
| 31 | + supply the variable's value. |
| 32 | +2._Define`default` property_: set a default property for the template |
| 33 | + variable. If the administrator doesn't input a value via CLI, Coder |
| 34 | + automatically uses this default during the push. |
| 35 | + |
| 36 | +After the initial push, variables are stored in the database table, associated |
| 37 | +with the specific template version. They can be conveniently managed via |
| 38 | +_Template Settings_ without requiring an extra push. |
| 39 | + |
| 40 | +###Resolved values vs. default values |
| 41 | + |
| 42 | +It's crucial to note that Coder templates operate based on resolved values |
| 43 | +during a push, rather than default values. This ensures that default values do |
| 44 | +not inadvertently override the configured variable settings during the push |
| 45 | +process. |
| 46 | + |
| 47 | +This approach caters to users who prefer to avoid accidental overrides of their |
| 48 | +variable settings with default values during pushes, thereby enhancing control |
| 49 | +and predictability. |
| 50 | + |
| 51 | +If you encounter a situation where you need to override template settings for |
| 52 | +variables, you can employ a straightforward solution: |
| 53 | + |
| 54 | +1. Create a`terraform.tfvars` file in in the template directory: |
| 55 | + |
| 56 | +```hcl |
| 57 | +coder_image = newimage:tag |
| 58 | +``` |
| 59 | + |
| 60 | +2. Push the new template revision using Coder CLI: |
| 61 | + |
| 62 | +``` |
| 63 | +coder templates push my-template -y # no need to use --var |
| 64 | +``` |
| 65 | + |
| 66 | +This file serves as a mechanism to override the template settings for variables. |
| 67 | +It can be stored in the repository for easy access and reference. Coder CLI |
| 68 | +automatically detects it and loads variable values. |
| 69 | + |
| 70 | +##Input options |
| 71 | + |
| 72 | +When working with Terraform configurations in Coder, you have several options |
| 73 | +for providing values to variables using the Coder CLI: |
| 74 | + |
| 75 | +1._Manual input in CLI_: You can manually input values for Terraform variables |
| 76 | + directly in the CLI during the deployment process. |
| 77 | +2._Command-line argument_: Utilize the`--var name=value` command-line argument |
| 78 | + to specify variable values inline as key-value pairs. |
| 79 | +3._Variables file selection_: Alternatively, you can use a variables file |
| 80 | + selected via the`--variables-file values.yml` command-line argument. This |
| 81 | + approach is particularly useful when dealing with multiple variables or to |
| 82 | + avoid manual input of numerous values. Variables files can be versioned for |
| 83 | + better traceability and management, and it enhances reproducibility. |
| 84 | + |
| 85 | +Here's an example of a YAML-formatted variables file,`values.yml`: |
| 86 | + |
| 87 | +```yaml |
| 88 | +region:us-east-1 |
| 89 | +bucket_name:magic |
| 90 | +zone_types:'{"us-east-1":"US East", "eu-west-1": "EU West"}' |
| 91 | +cpu:1 |
| 92 | +``` |
| 93 | +
|
| 94 | +In this sample file: |
| 95 | +
|
| 96 | +-`region`, `bucket_name`, `zone_types`, and `cpu` are Terraform variable names. |
| 97 | +-Corresponding values are provided for each variable. |
| 98 | +-The `zone_types` variable demonstrates how to provide a JSON-formatted string |
| 99 | +as a value in YAML. |
| 100 | + |
| 101 | +## Terraform .tfvars files |
| 102 | + |
| 103 | +In Terraform, `.tfvars` files provide a convenient means to define variable |
| 104 | +values for a project in a reusable manner. These files, ending with either |
| 105 | +`.tfvars`or `.tfvars.json`, streamline the process of setting numerous |
| 106 | +variables. |
| 107 | + |
| 108 | +By utilizing `.tfvars` files, you can efficiently manage and organize variable |
| 109 | +values for your Terraform projects. This approach offers several advantages: |
| 110 | + |
| 111 | +-Clarity and consistency:Centralize variable definitions in dedicated files, |
| 112 | +enhancing clarity, instead of input values on template push. |
| 113 | +-Ease of maintenance:Modify variable values in a single location under version |
| 114 | +control, simplifying maintenance and updates. |
| 115 | + |
| 116 | +Coder automatically loads variable definition files following a specific order, |
| 117 | +providing flexibility and control over variable configuration. The loading |
| 118 | +sequence is as follows: |
| 119 | + |
| 120 | +1. `terraform.tfvars`:This file contains variable values and is loaded first. |
| 121 | +2. `terraform.tfvars.json`:If present, this JSON-formatted file is loaded after |
| 122 | +`terraform.tfvars`. |
| 123 | +3. `\*.auto.tfvars`:Files matching this pattern are loaded next, ordered |
| 124 | +alphabetically. |
| 125 | +4. `\*.auto.tfvars.json`:JSON-formatted files matching this pattern are loaded |
| 126 | +last. |