The .forms.yml file allows the creation of a project via a nice interface. It allows for an easier and more controlled configuration of stacks.

This file will allow you to restrict the values provided, variables exposed, range, etc.

# Example

---
default:
  pipeline:
    AWS:
      - name: "Default Region"
        key: aws_default_region
        type: string
        widget: dropdown
        description: "In which region you would like your project to run"
        default: "eu-west-1"
        values: ["eu-west-1", "eu-west-2", "eu-west3", "eu-south1", "eu-north1", "eu-central1"]
        required: true
      - name: "S3 Bucket"
        key: terraform_storage_bucket_name
        type: string
        widget: simple_text
        description: "The S3 bucket where terraform will store its tfstate"
        default: "($ organization_canonical $)-terraform-remote-state"
        required: true
    Git:
      - name: "Service catalog repository"
        key: sc_repository
        widget: cy_scs
        type: string
        description: "The service catalog repository"
        default: "git@github.com:cycloidio/cycloid-stacks-test.git"
        required: true
      - name: "Service catalog credentials"
        key: sc_git_key
        widget: cy_cred
        type: string
        description: "The credential used to access the service catalog"
        default: "((git_readonly.ssh_key))"
        required: true
      - name: "Service catalog path"
        key: sc_path
        type: string
        widget: simple_text
        description: "The path of the stack in the service catalog"
        default: "8-wordpress-demo"
        required: true
      - name: "Service catalog branch"
        key: sc_branch
        widget: cy_branch
        type: string
        description: "The branch used by the service catalog"
        source: sc_repository
        default: "stacks"
        required: true
      - name: "Config repository"
        key: config_git_repository
        type: string
        widget: cy_crs
        description: "The config repository to save configurations"
        default: "git@github.com:cycloidio/cycloid-stacks-test.git"
        required: true
      - name: "Config repository credentials"
        key: config_git_key
        type: string
        widget: cy_cred
        default: "((git_readonly.ssh_key))"
        required: true
      - name: "Config repository branch"
        key: config_git_branch
        widget: cy_branch
        type: string
        description: "The branch used by the config repository"
        source: config_git_repository
        default: "config"
        required: true
      - name: "Config repository path"
        key: config_terraform_path
        widget: simple_text
        type: string
        description: "The path in which the config will be saved"
        default: "cycloid-wordpress-demo/terraform"
        required: true
  ansible:
    AWS:
      - name: Elastic IP
        key: elastic_ip_set
        description: "Whether or not you want your instances to get public IPs"
        type: boolean
        default: true
        widget: radios
        values: [true, false]
        required: true
      - name: Network for instances
        key: network_range
        type: array
        widget: dropdown
        values:
          - ["192.168.1.0/24", "192.168.50.0/24", "192.168.150.0/24"]
          - ["172.16.1.0/24", "172.16.50.0/24", "172.16.150.0/24"]
          - ["10.0.1.0/24", "10.0.50.0/24", "10.0.150.0/24"]
        default: ["192.168.1.0/24", "192.168.50.0/24", "192.168.150.0/24"]
        required: false
    Nginx:
      - name: Nginx Modules
        key: nginx_modules
        description: List of nginx modules to install
        type: map
        widget: dropdown
        values:
          - {njs: false, perl: false, waf: false, image_filter: false}
          - {njs: false, perl: true, waf: true, image_filter: false}
          - {njs: true, perl: true, waf: true, image_filter: true}
        required: true
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

# Argument Reference

The overall structure can be abstracted via this rough definition:

use-caseN:
  technologyN:
    groupN:
      var1-definition: <content>
      var2-definition: <content>
1
2
3
4
5

# Overall structure

The structure must respect the following:

  • use-case: the configuration made for this specific use-case (different variables, different cloud providers, etc) must match the .cycloid.yml file use-cases defined.
  • group: these groups are here to help gather attributes within a similar scoped view (cloud provider, logic, etc).They have no impact other than this.
  • technology: the technology you configure must match the .cycloid.yml file technologies previously defined. Although you can define the .cycloid.yml file however you please, technologies for the forms are limited to pipeline/Terraform/Ansible.
  • var-definition: please see the next section for an extended description of the format

# Attribute definition

Attribute definition includes many more fields, not all of which are mandatory or have the same constraints.

Attribute Type Required Description
key string yes key is the name of the attribute located in the sample files from .cycloid.yml file. See notes about key attribute
name string yes name of the attribute displayed to the user
type string yes the type of data handled
widget string yes the widget used to display the data in the most suitable way
default any no the default value to assign to the attribute if nothing is set by the user (used when required). Matches the type
description string no description helping users understand the interest/impact of such variable/change
required boolean no whether or not the attribute is required
source string no source is only used for the branch widget, see the section for more details
unit string no unit to be displayed for the attribute, helping to know what's being manipulated amount of servers, storage in Go, users, etc
values any no list of allowed values, please check the possible types

info

The default attribute for cy_cred widget might have a different format depending of the technology

  • ansible: cred_path/field
  • pipeline: ((cred_path.field))

# Key attribute

The key format to respect for ansible and pipelines is: keyX, where keyX is the name of the variable you want to replace. For terraform there are 2 ways:

  1. the "short" way (identical to ansible/pipeline): keyX. But this only works if you have only 1 module
  2. the "long" one module.Y.keyX for terraform. Works if one or several modules are provided.

Example: To modify servers, with only one module you can use either servers: 4 or module.infra.servers: 4:

module "infra" {
  source = "./app-cluster"
  servers = 5
}
1
2
3
4

With multiple you should use: module.backend.servers: 10

module "frontend" {
  source = "./app-cluster"
  servers = 5
}

module "backend" {
  source = "./app-cluster"
  servers = 5
}
1
2
3
4
5
6
7
8
9

# Widget attribute

The widgets are meant to provide easy configuration for the most common type of data. Some extras have been added to cover some elements used in Cycloid.

Widget Render
auto_complete ac
cy_cred cred
cy_scs scs
cy_crs crs
cy_branch branch
dropdown dd
number n
radios r
simple_text st
slider_list sl
slider_range sr
switch ta
text_area ta

As you might have noticed, a couple of those widgets are "special". By special, we mean that they aim to simplify using Cycloid entities. In our case: credentials, service catalog, config repositories, and/or branches. To help identify them, we have prefixed them with cy_.

The cy_branch is the only one that uses the variable source because to be able to select it, we need to know which repository to request. This is why the source must reference a valid key that belongs to either a cy_scs or cy_crs variable. If this sn't the case, an error will be triggered.

# Type attribute

The type constraints will ensure that the data provided matches the expected type. If you passed a string instead of a number, an error would be triggered.

The same applies if you set a default or values that do not respect the type.

The list of supported types:

  • integer: an integer number
  • string: any type of string
  • array: any type of array (number, string, etc)
  • boolean: true or false
  • map: any type of map

# Widget/Type couple constraints

Due to the nature of widgets, there are limitations applied to the types & values accepted. Here is a summary of all supported couples:

Widget Type Values
auto_complete string Needs at least 2 values, which are hints rather than restrictions
cy_cred string
cy_scs string
cy_crs string
cy_branch string
dropdown any At least 2 values, if Boolean only 2 allowed
number integer
radios any At least 2 values, if Boolean only 2 allowed
simple_text string
slider_list string, boolean, integer At least 2 values, if Boolean only 2 allowed
slider_range integer Only 2 values accepted, mininimal value first then maximum
switch boolean Does not take any values
text_area any

# Restrictions & Known limitations

Note

We are actively working on improving/solving these aspects, please read with care.

  1. Only one group per technology is accepted within the forms, so this might interfere with the .cycloid.yml ones.

  2. File comments are lost upon generation. We are aware of this limitation and are working towards fixing it.

  3. At the moment, you can only use modules within Terraform sample files. If you use other types of resources, these will be discarded.

  4. Due to the complexity of integrating the credentials, the credential widget works with the pipeline but not with Terraform/Ansible.

  5. Forms are now running with Terraform version 0.12.8, so make sure that the syntax you use is compatible with this one.

# Frequent questions

# How can I use my organization, project or environment name?

To automatically use these, you can insert special variables that will be substituted in both the destination/content of your files.

  • for organization: ($ organization_canonical $)
  • for project: ($ project $)
  • for environment: ($ environment $)

So, as a value in your .forms.yml file, you could use: default: ($ project $)/default/terraform/($ environment $)/wordpress-demo.tf

# What do I need to make this work?

To enable such feature you need couple things:

  1. Have a stack that contains a valid .forms.yml file
  2. Create a project with the configured stack

# Can I still use my project without forms?

Yes, if you made a typo or didn't create the right file, you will still be able to use the console as before.

# Can I name my file differently?

No, we have defined only two names for this file: .forms.yml and .forms.yaml. Anything not matching those names will be ignored.

# Can I edit my project via the forms?

Yes! You can edit it through the environment tab, see more in the project's page..

# Is there a way to validate this file before storing it?

It's coming soon!

# What if I provide extra variables or use-cases?

They will have their definitions validated and will be displayed via the interface but be ignored upon file generation. We advise against providing anything unnecessary, as it would be confusing for users.

# What are the 'new' variables displayed while editing?

Those variables are shown as 'new' becaues they have been added to forms file after the project creation. Therefore if you edit it, they will show up as 'new'.