# Variables

StackForm allows you to define a widget to save and use in your code depending on the technology.

First step is to define in which technologies the variable will be used and if it is a Cycloid credential variables schema

Here is examples of how to define variables

# Pipeline variables

# Details

Pipelines are based on Concourse. So the behavior is exactly the one described here: creds (opens new window) and here: credential-lookup-rules (opens new window)

A variable in Concourse is represented by ((myvar)). There is no difference with regular variables and Vault variables in a pipeline. Concourse will evaluate and render all the variables provided during the pipeline creation. For each variable not provided during the insert, Concourse will assume that they are Vault variables.

So variables will stay in the ((myvar)) format in the pipeline. And will be rendered using Vault only during the runtime of the job.

Vault variables specification When resolving a parameter such as ((foo_param)), it will look in the following credential paths, in order:

PIPELINE_NAME/foo_param
foo_param

That means you can define or override credentials for a specific pipeline scope.

You can specify the field to fetch via a . syntax, e.g. ((foo.bar)). This will look into your credentials for the path foo containing field name bar.

Specific field name Vault credentials are actually key-value, so if you indicate only a path like ((foo)) Concourse will default to the field name “value” corresponding to the credential foo.value field.

# Example

Define the widget variable in your .forms.yml file

Edit .forms.yml

version: "2"
use_cases:
- name: myusecase
  sections:
  - name: mysection
    groups:
    - name: mygroup
      technologies: [pipeline]
      vars:
        - name: "Pipeline variable"
          description: "Example of pipeline variable."
          key: my_pipeline_variable
          widget: simple_text
          type: string
          default: "mydefaultvalue"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Make sure to use technologies: [pipeline] to indicate the variable need to be saved as pipeline variable. Keep in mind your variable name is defined by the key field (my_pipeline_variable)

Define your variable in the pipeline variables file

With technologies: [pipeline], Stackform will search within the pipeline/variables.sample.yml file your variable name. Make sure to have it defined

Edit pipeline/variables.sample.yml

# Define the variable matching the forms key field
my_pipeline_variable: ""

1
2

Use your variable in the pipeline

Edit pipeline/pipeline.yml

jobs:
- name: job-hello-world
  build_logs_to_retain: 3
  plan:
  - task: hello-world
    config:
        platform: linux
        image_resource:
            type: docker-image
            source: {repository: busybox}
        run:
          path: /bin/sh
          args:
          - -ec
          - |
            # Here is the syntax to use pipeline variable ((my_pipeline_variable))
            echo ((my_pipeline_variable))

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

In this example, the variable is used to display a custom message in a pipeline job. Pipeline variable can be used pretty much anywhere in a pipeline

# Terraform variables

Define the widget variable in your .forms.yml file

Edit .forms.yml

version: "2"
use_cases:
- name: myusecase
  sections:
  - name: mysection
    groups:
    - name: mygroup
      technologies: [terraform]
      vars:
        - name: "Terraform variable"
          description: "Example of terraform variable."
          key: my_terraform_variable
          widget: simple_text
          type: string
          default: "mydefaultvalue"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Make sure to use technologies: [terraform] to indicate the variable need to be saved as a pipeline variable. Keep in mind your variable name is defined by the key field (my_terraform_variable)

Define your variable in terraform variables file

With technologies: [terraform], Stackform will search within the terraform/main.tf.sample file. terraform/main.tf.sample is structured as Terraform module call (opens new window) which need to have your variable my_terraform_variable defined

Edit terraform/main.tf.sample

module "example" {
  #####################################
  # Do not modify the following lines #
  source = "./module-example"

  project      = var.project
  env          = var.env
  organization = var.organization
  #####################################

  my_terraform_variable = ""
}

1
2
3
4
5
6
7
8
9
10
11
12

Define local module variable

To use the my_terraform_variable variable insite your terraform module, you need to define a local variable (opens new window) to your module

Edit terraform/module-example/variable.tf

variable "my_terraform_variable" {
  type        = string
  description = "Variable given by Stackform via the terraform module call."
}

1
2
3
4

Now, my_terraform_variable variable can be used in your terraform code.

# Terraform variables from Cycloid credential

We recommend to the pipeline technology fetch the credential and send it to terraform.

variables-aws-eks.sample.ymlpipeline.ymlmain.tf.samplemodule-****/variable.tf

Define the widget variable in your .forms.yml file

Edit .forms.yml

version: "2"
use_cases:
- name: myusecase
  sections:
  - name: mysection
    groups:
    - name: mygroup
      technologies: [pipeline]
      vars:
        - name: "Cycloid credential to use in Terraform"
          description: "Example of cycloid credential fetch by the pipeline and send to terraform."
          key: my_terraform_credential
          widget: cy_cred
          type: string

1
2
3
4
5
6
7
8
9
10
11
12
13
14

Make sure to use technologies: [pipeline] to indicate the variable need to be saved as a pipeline variable. Keep in mind your variable name is defined by the key field (my_terraform_credential)

Define your variable in the pipeline variables file

With technologies: [pipeline], Stackform will search within the pipeline/variables.sample.yml file your variable name. Make sure to have it defined

Edit pipeline/variables.sample.yml

# Define the variable matching the forms key field
my_terraform_credential: ""

1
2

Provide your credential from the pipeline to terraform

Edit pipeline/pipeline.yml

resources:
- name: tfstate
  type: terraform
  icon: terraform
  source:
    ...
    vars:
      my_terraform_credential: ((my_terraform_credential))

1
2
3
4
5
6
7
8

In this example, we update the Terraform resource configuration to set a my_terraform_credential Terraform variable which will contain our credential data. This is the equivalent of terraform -var my_terraform_credential=my_cred_datas

Now the variable is sent to terraform, we need to define it in the code and module.

Define your credential variable in terraform root level

Edit terraform/variables.tf

variable "my_terraform_credential" {
  description = "root variable used to get the credential from the pipeline"
}

1
2
3

Send your my_terraform_credential root variable to your terraform module

Edit terraform/main.tf.sample

module "example" {
  #####################################
  # Do not modify the following lines #
  source = "./module-example"

  project      = var.project
  env          = var.env
  organization = var.organization
  #####################################

  # Provide my var.my_terraform_credential root variable to my terraform module
  my_terraform_credential = var.my_terraform_credential
}

1
2
3
4
5
6
7
8
9
10
11
12
13

This will ensure terraform provides your var.my_terraform_credential root variable to your Terraform module.

Define local module variable

To use the my_terraform_credential variable inside your terraform module, you need to define a local variable (opens new window) to your module

Edit terraform/module-example/variable.tf

variable "my_terraform_credential" {
  description = "Credential gave by Stackform via the pipeline."
}

1
2
3

Now, my_terraform_credential variable can be used in your terraform code.

# Ansible variables

Define the widget variable in your .forms.yml file

Edit .forms.yml

version: "2"
use_cases:
- name: myusecase
  sections:
  - name: mysection
    groups:
    - name: mygroup
      technologies: [ansible]
      vars:
        - name: "Ansible variable"
          description: "Example of ansible variable."
          key: my_ansible_variable
          widget: simple_text
          type: string
          default: "mydefaultvalue"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Make sure to use technologies: [ansible] to indicate the variable need to be saved as a pipeline variable. Keep in mind your variable name is defined by the key field (my_ansible_variable)

Define your variable in the ansible variables file

With technologies: [ansible], Stackform will search within the ansible/environments/default.yml.sample file your variable name. Make sure to have it defined

Edit ansible/environments/default.yml.sample

# Define the variable matching the forms key field
my_ansible_variable: ""

1
2

Use your variable in ansible

Edit ansible/playbook.yml

- name: Hello world
  ansible.builtin.debug:
    msg: My stackform var is {{ my_ansible_variable }}

1
2
3

In this example, the variable is used to display a custom message in an ansible task.

← Examples FAQ →